# 数据库结构与迁移

VOKO 使用独立 MySQL 8.4 库（本地默认 `voko`），不连接 shadiao-2d 的 `idearun` / `idearun_visual_game` / `visual_game_stage`。时间列 `DATETIME(3)` 存 UTC，列名与字段统一 snake_case。

## 结构事实源

- `packages/*/src/db/tables/*.cjs`：当前完整结构，`apps/voko-server/src/db/schema.js` 汇总为 `vokoTargetTables`。
- `apps/voko-server/src/db/migrations/*.js`：已存在的库如何从一个版本变到下一个版本。历史表 `voko_schema_migrations`。
- 服务启动不执行 DDL。改表必须同时改 `tables/*.cjs` 和新增一个 migration。

## 命令

| 目的 | 命令 | 只能用于 |
| --- | --- | --- |
| 新空库建表 | `pnpm --filter @voko/server db:init` | 确认没有任何表的空库 |
| 执行未执行的 migration | `pnpm --filter @voko/server db:migrate` | 已 init 的库 |
| 查看状态 | `pnpm --filter @voko/server db:status` | 已 init 的库 |

三个命令都读取 `apps/voko-server/.env` 的 `DATABASE_URL`，或用 `--env <文件>` 指定；都未设置时连本地开发库 `voko`。

## 纪律

- migration 只在合入主干之后，才允许在 stage / 生产等共享库执行；开发只连本地库。
- 唯一性、非空、状态与字段组合一律写成 DB 约束（UNIQUE / NOT NULL / CHECK），不在应用层先查再写。
- 禁止对共享库执行 init；禁止在共享库上手工改结构。