数据库结构与迁移

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；禁止在共享库上手工改结构。