Reference

Database schema

AgentsVille stores everything in one MySQL 8.4 database. There are twenty-seven tables: four that belong to authentication, one that holds instance-wide settings, one that is seeded content, and twenty-one that hold what Players create.

Every table is utf8mb4 with the utf8mb4_unicode_ci collation. Timestamps are datetime(3) — millisecond precision — and are written in UTC. Identifiers are varchar(191) holding application-generated UUIDs; the database generates no ids.

Naming

Columns are snake_case in SQL and camelCase in TypeScript. Kysely's CamelCasePlugin sits on the runtime connection and translates in both directions — identifiers on the way out, result keys on the way back — so mcp_server.owner_id is mcpServer.ownerId in application code. The rename that made the database snake_case throughout and that plugin are halves of one decision; applying either alone breaks every query. See ADR 0019.

This page names columns as SQL holds them.

Migrations

The schema is built by migrations in packages/db/migrations, applied in name order by Kysely's Migrator: the initial schema, which creates the tables and seeds the first Templates; the rename that made every column snake_case; and each change since, such as the one that made Providers rows and added Levels.

None has a down. Rolling back means writing the migration that undoes it; a generated down that has never been run is not a rollback plan. The migrator takes a lock first, so two containers starting together cannot both run the same CREATE TABLE, and it keeps its own bookkeeping tables alongside the ones below. See ADR 0018 and Scripts for pnpm db:migrate.

What cascades

Deleting a Player deletes everything they own. user is the root: session, account, npc, conversation, mcp_server, skill, memory, connector, player_achievement and player_hidden_skin all reference it with ON DELETE CASCADE. The exception is custom_skin.created_by, which is ON DELETE SET NULL: an uploaded Skin belongs to the Village, so it outlives the Player who made it.

Deleting an NPC deletes what belongs to that NPC: conversation, npc_tool, sandbox, conversation_participant, and the skill and memory rows scoped to it. One reference is deliberately different — message.npc_id is ON DELETE SET NULL, so deleting an NPC does not delete the Conversation a Player had with it. The transcript survives; the attribution goes null.

Deleting a custom_skin deletes its custom_skin_file rows.

Deleting an MCP Server cascades to the connector row that backs it, which is why revoking a Connector is implemented as deleting its MCP Server.

Two things do not cascade, and are cleaned up in application transactions instead: an npc_tool grant naming an MCP Server or a Skill holds that id in a plain ref column with no foreign key, so the routes that delete a Skill or an MCP Server delete the matching grants in the same transaction.

Every foreign key is ON UPDATE CASCADE.

user

The Players. The first Player to register becomes the Operator.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`name`	`text`	Not null.
`email`	`varchar(191)`	Not null, unique.
`email_verified`	`boolean`	Not null, defaults to false.
`image`	`text`	Nullable.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained by the database on update.
`is_operator`	`boolean`	Not null, defaults to false. True for exactly one Player.
`skin`	`varchar(64)`	Nullable. The Player's Skin: a built-in name or an uploaded Skin's id; null means Farm, the default, or Classic for a Player who hid Farm.
`villager`	`tinyint unsigned`	Nullable. Which of the fifty people (0-49) the Player walks the Village as; null means one picked from their id.
`font`	`varchar(32)`	Nullable. The Player's own Font; null means the Village font.

The Invite Code is never stored here, or anywhere else against a Player. It is checked at registration and then forgotten. See Village and invites and invite_code below.

skin and villager sit on user rather than in a preferences table because they are two values with nowhere else to live yet; a preferences table can come with the second. See ADR 0031 and ADR 0033.

custom_skin

Uploaded Skins (ADR 0038).

Column	Type	Notes
`id`	`varchar(36)`	Primary key. Unguessable; this is what `user.skin` holds.
`name`	`varchar(60)`	Not null.
`base`	`varchar(16)`	Not null. The built-in Skin that fills in whatever the pack lacks.
`theme`	`enum('light','dark')`	Not null.
`path_edge`	`char(7)`	Not null. The map's road edge colour.
`tokens`	`json`	Not null. The merged CSS tokens.
`created_by`	`varchar(191)`	Nullable. The uploader; references `user.id`, set null on delete.
`created_at`	`datetime(3)`	Defaults to now.

Deleting a Skin removes its files, and wearers go back to Farm, or Classic if they hid Farm: a user.skin that names no Skin reads as the default.

custom_skin_file

Column	Type	Notes
`id`	`varchar(36)`	Primary key. The id in `/api/skin-files/:id`.
`skin_id`	`varchar(36)`	References `custom_skin.id`, cascade.
`path`	`varchar(64)`	The art path, such as `characters/07.png`. Unique per Skin.
`png`	`mediumblob`	The re-encoded PNG.

player_hidden_skin

Column	Type	Notes
`user_id`	`varchar(191)`	Primary key with `skin`. References `user.id`, cascade.
`skin`	`varchar(64)`	Primary key with `user_id`. A built-in name or an uploaded Skin's id.

invite_code

The Village's invite codes (ADR 0036). Not linked to user: a code is never stored against a Player.

Column	Type	Notes
`id`	`varchar(191)`	Primary key. `env` is `SIGNUP_INVITE_CODE`, synced in by the first sign-up or code listing.
`code_hash`	`varchar(191)`	Not null, unique. HMAC-SHA256 of the code, keyed with `BETTER_AUTH_SECRET`.
`hint`	`varchar(191)`	Not null. The last four characters of the code.
`label`	`varchar(191)`	Not null. The Operator's name for it.
`max_uses`	`int`	Nullable. Null is no limit; 0 turns the code off.
`uses`	`int`	Not null, defaults to 0. Counted by one conditional update; a failed registration gives it back.
`expires_at`	`datetime(3)`	Nullable.
`created_by`	`varchar(191)`	Nullable. The Operator who made it.
`created_at`	`datetime(3)`	Defaults to now.

session

Sign-in sessions, written and read by better-auth.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`expires_at`	`datetime(3)`	Not null.
`token`	`varchar(191)`	Not null, unique.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.
`ip_address`	`text`	Nullable.
`user_agent`	`text`	Nullable.
`user_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.

account

Credentials, also better-auth's. For email-and-password registration this holds the password hash.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`issuer`	`varchar(191)`	Not null. Unique together with `account_id`.
`account_id`	`varchar(191)`	Not null.
`provider_id`	`text`	Not null.
`user_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`access_token`	`text`	Nullable.
`refresh_token`	`text`	Nullable.
`id_token`	`text`	Nullable.
`access_token_expires_at`	`datetime(3)`	Nullable.
`refresh_token_expires_at`	`datetime(3)`	Nullable.
`scope`	`text`	Nullable.
`password`	`text`	Nullable. The hash, for password accounts.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

verification

Short-lived verification tokens, better-auth's third table.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`identifier`	`text`	Not null. Indexed on its first 191 characters — the one index in this schema that needs a prefix length, because MySQL will not index a `TEXT` column without one.
`value`	`text`	Not null.
`expires_at`	`datetime(3)`	Not null.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

village_setting

Instance-wide settings, one row per key. No foreign keys and no owner: these belong to the Village, not to a Player.

Column	Type	Notes
`key`	`varchar(120)`	Primary key.
`value`	`text`	Not null. Always a string; callers parse it.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

Keys in use:

Key	Meaning
`model.defaultProvider`	The Provider an NPC inherits when it names none.
`model.defaultModel`	The Model an NPC inherits when it names none.
`model.levels`	JSON mapping `beginner`, `advanced`, `expert`, `ultra` to `{ provider, model }`. Unmapped Levels are absent.
`party.maxHops`	How many times NPCs in a Party may hand the turn between themselves. 6 when unset or unparseable.
`village.font`	The Village font's name; empty for each Skin's own fonts.
`usage.limit`	JSON `{ tokens, window }`; empty for no Village Usage limit.

The whole table is read as one object and cached, so a read costs nothing per key.

provider

Where models run. Seeded with anthropic and openai; the Operator adds more. No owner: Providers belong to the Village.

Column	Type	Notes
`id`	`varchar(64)`	Primary key. Readable: `ollama`, `lm-studio`. The seeded ids are the old enum values.
`name`	`varchar(120)`	Not null, unique.
`kind`	`enum('anthropic','openai','openai-compatible')`	Not null. Which SDK client talks to it.
`base_url`	`varchar(500)`	Nullable. Null means the Provider's public endpoint; required for `openai-compatible`.
`api_key`	`text`	Nullable, encrypted. Null on a seeded row means the `.env` key; on any other row, no key at all.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update. Rebuilds the cached SDK client when it changes.

See ADR 0022.

npc

The characters a Player creates.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`name`	`varchar(200)`	Not null.
`system_prompt`	`text`	Not null; may be empty. Name, job title and description reach the model without it.
`avatar`	`varchar(16)`	Nullable. `npc-01` … `npc-50`, a portrait in `apps/web/public/avatars`.
`provider`	`varchar(64)`	Nullable. References `provider.id`, restrict on delete. Null means Levels or the Village default.
`model`	`varchar(200)`	Nullable. Free text, because a Provider may release a model before AgentsVille knows about it.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.
`job_title`	`varchar(200)`	Nullable.
`description`	`text`	Nullable.
`thinking`	`enum('off','low','medium','high')`	Not null, defaults to `off`.
`levels`	`json`	Nullable. The Levels this NPC works at, as an ordered array. Ignored while `provider` and `model` are set.
`usage_limit_tokens`	`int unsigned`	Nullable. A Usage limit's tokens, set with `usage_limit_window` or not at all.
`usage_limit_window`	`enum('day','week','month')`	Nullable. The rolling window: 24 hours, 7 or 30 days.

provider and model move together: a model id only means something to the Provider that issued it, so a half-set pair is not a state worth storing. Both null is the one meaningful mixed case, and it means "inherit". See NPC.

conversation

One Conversation between a Player and one or more NPCs.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`npc_id`	`varchar(191)`	Not null. References `npc.id`, cascade. Indexed. The NPC the Conversation started with.
`user_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update. Bumped by every Message, which is what makes "most recently active" ordering mean that.
`title`	`varchar(200)`	Nullable. Set once, from the first 80 characters of the first Message, and renameable after.
`summary`	`text`	Nullable. What fell off the front of the history, condensed, so "as we agreed earlier" still means something.
`lead_npc_id`	`varchar(191)`	Nullable. References `npc.id`, set null on delete. The Party's Lead; cleared when the Lead leaves the Party.

npc_id is the founding NPC, not the membership list. Who is actually in a Conversation is conversation_participant, and a Conversation has a participant row from the moment it is created.

conversation_participant

Who is in a Conversation. One row is the ordinary case; two or more make it a Party.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`conversation_id`	`varchar(191)`	Not null. References `conversation.id`, cascade. Indexed.
`npc_id`	`varchar(191)`	Not null. References `npc.id`, cascade. Indexed.
`turn_order`	`integer`	Not null, defaults to 0.
`added_at`	`datetime(3)`	Defaults to now.

(conversation_id, npc_id) is unique, so adding an NPC that is already present is a no-op rather than a constraint error the interface has to interpret.

turn_order decides who speaks first when nobody is addressed by name, and it is read ascending with added_at as the tie-break. A new participant is given the count of participants already present, so the order is the order they were added unless something changes it. See Party.

party_task

One item on a Party's task board.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`conversation_id`	`varchar(191)`	Not null. References `conversation.id`, cascade. Indexed.
`title`	`varchar(300)`	Not null.
`status`	`enum('todo','doing','done')`	Not null, defaults to `todo`.
`assignee_npc_id`	`varchar(191)`	Nullable. References `npc.id`, set null.
`created_by_npc_id`	`varchar(191)`	Nullable; null when the Player added it. References `npc.id`, set null.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

message

One turn in a Conversation.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`conversation_id`	`varchar(191)`	Not null. References `conversation.id`, cascade. Indexed.
`role`	`enum('user','assistant')`	Not null.
`content`	`text`	Not null. The plain text of the turn.
`created_at`	`datetime(3)`	Defaults to now.
`input_tokens`	`integer`	Nullable. What the Provider reported.
`output_tokens`	`integer`	Nullable. What the Provider reported.
`parts`	`json`	Nullable. The ordered Parts: text, reasoning, Tool calls and Tool results.
`npc_id`	`varchar(191)`	Nullable. References `npc.id`, set null on delete. Indexed. Which NPC spoke, which matters once more than one can.
`level`	`varchar(16)`	Nullable. The Level the reply ran at, so a reloaded transcript still shows it.

History is read ordered by created_at then id. The tie-break is not decoration: created_at alone is non-deterministic for rows written in the same millisecond, and a history that reorders itself between turns is a model that contradicts itself.

parts is what makes thinking and Tool use visible rather than hidden. Because MySQL hands json columns back already parsed, the CamelCasePlugin is configured not to recurse into values — a Tool call stored here keeps its own keys. See Conversation and parts and Usage.

token_usage

The Usage ledger: one row per model call. No foreign keys, so deleting a Conversation, an NPC or a Player's Message never changes what was used; and no owner cascade, so a deleted Player's rows stay too.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`user_id`	`varchar(191)`	Not null. The Player whose action caused the call.
`npc_id`	`varchar(191)`	Nullable. Null for a draft or a Level rating.
`npc_name`	`varchar(200)`	Nullable. The NPC's name at the time, kept after deletion.
`conversation_id`	`varchar(191)`	Nullable.
`kind`	`enum('message','summary','rating','draft','embedding')`	Not null.
`level`	`enum('beginner','advanced','expert','ultra')`	Nullable. Only on `message` rows.
`provider`	`varchar(64)`	Not null. A Provider id, or `unknown` on backfilled rows.
`model`	`varchar(200)`	Not null.
`input_tokens`	`int`	Not null, 0 when the Provider reported nothing.
`output_tokens`	`int`	Not null, 0 for embeddings.
`created_at`	`datetime(3)`	Defaults to now. Indexed with `npc_id`, with `user_id`, and alone.

Its migration backfilled one message row per earlier assistant Message with tokens, taking the provider and model from the NPC as it was then.

npc_group

A named set of one Player's NPCs.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Unique with `name`.
`name`	`varchar(120)`	Not null.
`description`	`text`	Nullable.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

npc_group_member

Column	Type	Notes
`group_id`	`varchar(191)`	References `npc_group.id`, cascade. Primary key with `npc_id`.
`npc_id`	`varchar(191)`	References `npc.id`, cascade. Indexed.

tool_grant

Grants that reach many NPCs: every NPC the Player has (all) or a Group's members. Per-NPC grants stay in npc_tool.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`subject`	`enum('all','group')`	Not null.
`group_id`	`varchar(191)`	Nullable; set for `group`. References `npc_group.id`, cascade.
`kind`	`enum('builtin','mcp','skill')`	Not null.
`ref`	`varchar(200)`	Not null. As in `npc_tool`.

A unique index cannot dedupe rows whose group_id is NULL, so each set is replaced in one transaction instead. What an NPC can use is its own npc_tool rows, plus these, minus its own rows with enabled = false.

host_mount

Host folders the Operator lends to Sandboxes.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`name`	`varchar(64)`	Not null, unique. The directory under `/work/mnt`.
`host_path`	`varchar(500)`	Not null. Inside one of `SANDBOX_HOST_MOUNT_ROOTS`.
`read_only`	`boolean`	Not null, defaults to true.
`subject`	`enum('all','group','npc')`	Not null.
`group_id`	`varchar(191)`	Nullable. References `npc_group.id`, cascade.
`npc_id`	`varchar(191)`	Nullable. References `npc.id`, cascade.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

npc_tool

Which Tools one NPC may use. One row per grant.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`npc_id`	`varchar(191)`	Not null. References `npc.id`, cascade. Indexed.
`kind`	`enum('builtin','mcp','skill')`	Not null.
`ref`	`varchar(200)`	Not null. A built-in's name, or an `mcp_server.id`, or a `skill.id`.
`enabled`	`boolean`	Not null, defaults to true.

(npc_id, kind, ref) is unique. ref carries no foreign key, because it points at three different things depending on kind — which is why deleting a Skill or an MCP Server also deletes the grants naming it, in the same transaction.

Two builtin refs are grants rather than single Tools: sandbox turns on the Sandbox Tools, and memory turns on the Memory Tools. See Tools.

skill

Written instructions an NPC loads on demand.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`npc_id`	`varchar(191)`	Nullable. References `npc.id`, cascade. Indexed.
`name`	`varchar(200)`	Not null.
`description`	`text`	Not null. What the NPC reads to decide whether to load it.
`instructions`	`text`	Not null. The prose itself.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

A null npc_id is the whole point of the column being nullable: it means the Skill belongs to the Village and every NPC in it can be granted the Skill. A non-null npc_id scopes it to that one NPC, and the Skill is deleted with it. Listing Skills for an NPC returns both. See Skills.

mcp_server

An external process or endpoint offering Tools over the Model Context Protocol. Registered once, enabled per NPC.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`name`	`varchar(200)`	Not null.
`transport`	`enum('stdio','http','sse')`	Not null.
`command`	`text`	Nullable. Required in practice for `stdio`.
`args`	`json`	Nullable. An array of strings.
`url`	`text`	Nullable. Required in practice for `http` and `sse`.
`headers`	`text`	Nullable. Encrypted at rest, and never returned by any route.
`enabled`	`boolean`	Not null, defaults to true.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

headers is where a bearer token for a remote server lives. Reads report only whether it is set, never a masked value: a field that is sometimes a secret and sometimes a placeholder is a field someone will eventually save back. See MCP servers.

connector

A pre-configured MCP Server plus the credentials to reach a third-party service.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`kind`	`varchar(120)`	Not null. The catalogue key — `linear`, `notion`, `atlassian`, `composio`, `sentry`.
`label`	`varchar(200)`	Not null.
`mcp_server_id`	`varchar(191)`	Not null, unique. References `mcp_server.id`, cascade.
`status`	`enum('pending','connected','expired')`	Not null, defaults to `pending`.
`access_token`	`text`	Nullable. Never leaves this table.
`refresh_token`	`text`	Nullable. Never leaves this table.
`expires_at`	`datetime(3)`	Nullable.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

mcp_server_id being unique is what makes a Connector exactly one MCP Server: a Connector is not a separate mechanism, it is a Tool source with an OAuth story. Because the reference cascades, deleting the MCP Server removes the Connector with it. The routes that list Connectors name their columns explicitly so the two token columns cannot be selected by accident.

A pending OAuth flow is not stored here. It lives in Valkey for ten minutes and expires without being asked. See Connectors.

sandbox

The record that an NPC has been granted a machine, and on what terms.

Column	Type	Notes
`npc_id`	`varchar(191)`	Primary key. References `npc.id`, cascade.
`egress`	`boolean`	Not null, defaults to false. Whether the machine may reach the internet.
`created_at`	`datetime(3)`	Defaults to now.
`updated_at`	`datetime(3)`	Defaults to now, maintained on update.

One Sandbox per NPC, so npc_id is the key rather than a column beside one.

The row is the record of the decision; the container is the consequence. The row is read every time a machine is started, which is what stops a restarted broker quietly bringing a Sandbox back on the wrong network. Revoking a Sandbox deletes the row and destroys the machine, filesystem and all. Only the Operator can set egress. See Sandbox.

memory

Something an NPC should still know in a Conversation that has not happened yet.

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`owner_id`	`varchar(191)`	Not null. References `user.id`, cascade. Indexed.
`npc_id`	`varchar(191)`	Nullable. References `npc.id`, cascade. Indexed.
`scope`	`enum('npc','village')`	Not null, defaults to `npc`.
`content`	`text`	Not null. Up to 2000 characters, enforced by the routes.
`embedding`	`json`	Nullable. An array of floats.
`created_at`	`datetime(3)`	Defaults to now.
`last_used_at`	`datetime(3)`	Nullable. When recall last surfaced it.

scope decides who the Memory is for. npc means it belongs to one NPC; village means every NPC in the instance shares it. Listing an NPC's Memories returns both, because a list that omitted the shared ones would misrepresent what the NPC knows.

embedding is a JSON array rather than a vector column, because MySQL 8.4 has no vector type. Recall prefilters with the FULLTEXT index on content and scores the survivors in process. Editing a Memory clears the embedding rather than recomputing it, so an edit stays instant and the Memory is still found by keyword. See ADR 0010 and Working with memory.

npc_template

Starting points for a new NPC. Read-only at runtime and seeded by migrations (the initial schema and 20260928090000_more_templates).

Column	Type	Notes
`id`	`varchar(191)`	Primary key.
`slug`	`varchar(120)`	Not null, unique.
`name`	`varchar(200)`	Not null.
`job_title`	`varchar(200)`	Not null.
`description`	`text`	Not null.
`system_prompt`	`text`	Not null.
`suggested_tools`	`json`	Not null. An array of built-in Tool names or grants.
`sort_order`	`integer`	Not null, defaults to 100.
`created_at`	`datetime(3)`	Defaults to now.

No owner and no foreign keys: Templates belong to the instance, and a Template is copied on use rather than linked, so nothing points back at this table. The seeded set is Wren (Researcher), Pike (Engineer), Quill (Editor), Ledger (Analyst), Compass (Generalist), Tally (Accountant), Lark (Writer), Lens (Reviewer) and Brief (Legal). See Templates.

player_achievement

The Achievements each Player holds.

Column	Type	Notes
`user_id`	`varchar(191)`	Primary key with `achievement_id`. References `user.id`, cascade.
`achievement_id`	`varchar(64)`	Primary key with `user_id`. An id from `ACHIEVEMENTS` in `apps/server/src/lib/progression.ts`.
`unlocked_at`	`datetime(3)`	Not null, defaults to now.

A row is written the first time a Player meets an Achievement and never removed, so deleting what earned it — the NPC behind "First NPC", say — does not take the Achievement away. XP and Rank are not stored: both are derived from these rows every time they are read, by summing the xp each held achievement_id is worth in the catalogue and applying the Rank formula to the total. See Achievements and Rank and ADR 0032.