数据库迁移

SQLx migration 是数据库结构版本的唯一来源。SQLx 在数据库的 _sqlx_migrations 表记录版本、执行时间和 checksum。

创建 migration

sqlx migrate add <short_description>

每个 migration 只生成一个 .sql 文件。名称使用简短的英文 snake_case， SQL 必须能在空数据库上按版本顺序执行。

本地工作流

sqlx migrate info
make db-migrate

开发者提交前必须在空数据库执行 migration，并再次执行 sqlx migrate run 确认没有待执行项。

Forward-only 规则

• 已合并或已在共享环境执行的 migration 不得修改、重命名或删除。
• 发现历史 migration 有问题时新增前向修复 migration。
• 不创建 .down.sql，也不执行 sqlx migrate revert。
• 应用版本回滚不得反向修改数据库结构；新旧版本必须通过兼容窗口共同支持当前 schema。
• 删除列、表或数据前必须在 PR 中明确数据保留和恢复方案。
• 应用启动、Session Store 初始化和测试辅助代码都不得绕过 migration 建表。

部署顺序

备份与兼容性检查
  -> sqlx migrate info
  -> sqlx migrate run
  -> 启动新应用版本
  -> 验证 /health 和 /ready

需要零停机时，migration 必须遵循 expand-and-contract：先增加兼容结构，完成 代码迁移和数据回填后，再在后续版本删除旧结构。