Database
The nineteen tables, what keys them, how ExyliaLib wipes and resets them, running several servers on one database, and what to know before touching them by hand.
Run ExyliaClans on one server with no setup, or point several servers at one database so they share every clan. Storage is ExyliaLib's: choose the engine and set up Redis as described in Database, and the plugin creates and migrates its nineteen tables from its record definitions, so there is no schema file to apply. database.yml is written on first start and defaults to H2.
Most owners only need Several servers. The rest of this page is for people who query the tables.
The nineteen tables#
The nineteen tables
This page names clan_player_stats for the per-player stats; servers upgraded from 1.4.0 or earlier had it as player_stats, and the rows carry over.
| Table | Key | Holds |
|---|---|---|
clans | id (UUID text) | Name, styled name, leader, balance, open, friendly fire, home, banned list, DTR, DTR freeze, last regeneration, EXP, extra member slots |
clan_members | uuid | The player's clan and their rank |
clan_roles | id | Every rank of every clan: name, weight, permissions, whether it is the default |
clan_relations | clanId:targetClanId | One directional opinion, ALLY or RIVAL |
clan_invites | playerUuid:clanId | A standing invitation and when it was sent |
clan_alliance_requests | requestingClanId:targetClanId | A pending alliance request and when it was sent |
clan_claims | id | (scoped by claims-scope) One rectangle: world, minX, minZ, maxX, maxZ, baseY |
clan_stats | clanId | Kills, deaths, playtime seconds |
clan_player_stats | playerUuid:clanId | The same per player per clan, plus the last name seen |
clan_logs | id | Action, actor, target, detail, timestamp |
clan_mails | id | Type, sender, recipient, subject, body, sent, expires, read list, deleted list, pinned |
clan_webhooks | clanId | The webhook URL, its name in Discord, the events switched off, whether Discord deleted it |
lfc_profiles | playerUuid | Status, posted, last posted, expires, the answers |
lfp_postings | clanId | Status, posted, last posted, expires, description, the answers |
lfp_applications | playerUuid:clanId | Status, applied, decided, message |
clan_war_arenas | id | (scoped by war-arenas-scope) A war arena's spawns, spectator spawn, corners, and whether it is enabled |
clan_war_kits | id | A war kit's icon and items |
clan_war_records | clanId | War wins, losses and draws |
clan_war_returns | playerId | Where a real-loss war fighter came from, and their game mode |
Wiping and resetting#
There is no clan wipe or reset command of its own. Every table declares what it holds for ExyliaLib, so
/exylialib wipe and /exylialib resetplayer cover the plugin:
| Kind | Tables |
|---|---|
| World (clans and everything they own) | clans, clan_members, clan_roles, clan_relations, clan_invites, clan_alliance_requests, clan_claims, clan_stats, clan_mails, clan_webhooks, lfc_profiles, lfp_postings, lfp_applications, clan_war_records |
| Progress | clan_player_stats |
| History | clan_logs |
| Setup (kept by a season wipe) | clan_war_arenas, clan_war_kits |
| Cache | clan_war_returns |
/exylialib wipe ExyliaClans all every table
/exylialib wipe ExyliaClans clan_logs one table
/exylialib resetplayer Steve ExyliaClans one player's rowsEach first run prints what would go and a six-digit code; the same line with the code runs it.
A player reset removes the rows keyed by that player: their membership (clan_members), their stats
(clan_player_stats), their invites, LFC profile, LFP applications and pending war return. The running
server lets go of them at once, without a restart. If the player led a clan, the member with the
heaviest rank becomes leader; if nobody is left, the clan is disbanded.
What the keys buy you#
What the keys buy you
Several rules that would otherwise need enforcing are enforced by the key itself:
- A player is in one clan.
clan_membersis keyed by the player's UUID, so a second membership row cannot exist. - A clan has one claim, one LFP posting. Both are keyed by the clan id.
- A player has one LFC profile, and one application per clan.
- An invitation is unique per pair, and so is a relation.
Two indexes#
Indexes
| Index | On | For |
|---|---|---|
idx_cl_clan_ts | clan_logs (clanId, timestamp DESC) | The logs menu: filter by clan, newest first, take a page |
idx_cm_clan_sent | clan_mails (clanId, sentAt DESC) | The inbox, the same way |
Both make a page a bounded read rather than a scan.
Columns worth knowing about#
Columns worth knowing about
| Column | Format |
|---|---|
clans.bannedPlayers | Comma-separated UUIDs |
clan_roles.permissions | Comma-separated permission names. An unknown name is skipped when read |
clans.homeLocation | A serialised location that carries the server it was set on — server,world,x,y,z,yaw,pitch. null when unset. A home saved under a previous server-id is read as this server's |
clans.styled_name | The name as /clan style draws it, up to 1024 characters. null when the clan has no style |
clans.balance | Held in the currency bank-currency names; changing that key later does not convert it |
clans.extraSlots | Member slots granted with /clanadmin setslots, on top of max-members and the level bonus |
clans.dtrRegenAt | When the DTR last regenerated, epoch millis — what keeps several servers from each regenerating it |
clan_invites.sentAt / clan_alliance_requests.sentAt | Epoch millis. 0 on an invite written before 1.2.0, which counts as sent at the update |
clan_webhooks.url | The full webhook URL, token included. Treat the table as a secret; it is never shown in game |
clan_webhooks.disabledEvents | Comma-separated event names the clan switched off: JOIN, LEAVE, KICK, BAN, INVITE, RANK, LEADER, RENAME, ALLIANCE, RIVALRY, BANK, DISBAND |
clan_mails.readByPlayers / deletedByPlayers | Comma-separated UUIDs — which is how read and deleted are per member off one row |
lfc_profiles.data / lfp_postings.data | The serialised answers |
*.status | ACTIVE / EXPIRED for postings and profiles; PENDING / ACCEPTED / REJECTED for applications |
What is not in the database#
- Chat channels. Per session; everybody is back on global after a restart.
- Kill streaks. Per session, and reset by dying.
- Camp, rally, focus and regroup markers. All in memory. A regroup point and a kick truce are shared with the other servers of a network, never stored.
- The anti-spam waits. Create, invite, mail, rival-notice and webhook waits are in memory, per server.
- The clan level. Derived from
clans.expon every read, never stored. - Claim ownership of members. Derived from
clan_members; the claim row names only the clan.
Caches#
Clans, members, ranks, relations, claims, invitations, alliance requests and webhooks are held in memory and written through on change, so the hot path never touches the database. Two things are cached with a TTL instead:
| Cache | TTL | Why |
|---|---|---|
| Each leaderboard ranking | 30 s | A scoreboard asks four times a second |
| The online roster per clan and per alliance | 1 s | Thirty slots × several viewers × four times a second |
The caches are loaded at enable and kept in step by the plugin's own writes — and, on a network, by the
other servers' writes. A row changed directly in the database is not noticed, and will be overwritten
the next time that clan changes. Use /clanadmin where it covers what you need, and stop the servers
where it does not.
Several servers#
Servers that share one database act as one clan system once every one of them enables Redis in
database.yml (the redis block, with a different server-id on each). Nothing else is configured.
| What | How |
|---|---|
| Every table: clans, members, ranks, relations, invites, alliance requests, mail, stats, claims, webhooks, LFC and LFP | Each server keeps its copy and re-reads a row the moment another server writes or deletes it. A join, a kick, a promotion or an alliance made on one server is seen on all of them within milliseconds. |
| Clan chat, ally chat, every clan notice, invitations, kicks, promotions, mail notices | Published once and delivered by each server to the members it holds, so a line is never sent twice and never only where it happened. |
/clan regroup | The point names its server; a clanmate elsewhere is handed over to it. |
| Kick truce | Follows the kicked player to whichever server they move to. |
| DTR regeneration | Once per interval for the whole network, however many servers run the timer. |
Online counts (%exyliaclans_clan_online%, the online roster, menus, the leaderboard) | Count members on any server. |
What stays on the server it was made on: the camp and rally markers and the focus outline (they are drawn on one server's map), the anti-spam waits, and which chat channel a player has toggled. A claim is drawn only where its world is loaded.
Without Redis everything behaves as on one server.
Startup#
The repositories are read asynchronously, so the plugin finishes enabling before the tables have answered. Until they do, every lookup says no clan — the safe way to be wrong for a moment. Once the caches are true, anybody already online has their join replayed, so a player who logged in during that window is not left invisible to their own clan.
If the read fails outright, the console says so and the plugin stays idle rather than starting to write against caches it knows are empty.
Something missing on this page? Tell us on Discord