cms-service/scripts/db

cms-service 数据库脚本（migrate / verify / rollback）

本目录提供一套与 iam-service/scripts/db 类似的数据库操作脚本，适用于：

• 生产/预发：在启动 cms-service 前，显式执行迁移与校验
• 开发/测试：快速初始化/回滚 schema

说明：

• cms-service 运行时也会自动执行 SQLx migrations（见 src/infrastructure/db/mod.rs）。如果你选择使用本目录脚本管理迁移，建议在部署流程中做到“先 migrate，再启动服务”，并在同一数据库上保持一致的迁移源（cms-service/migrations/*.sql）。
• 本脚本会写入 SQLx 使用的 _sqlx_migrations 表，使得服务启动时不会重复执行已应用的迁移。

前置条件

• 已安装 psql
• DATABASE_URL 可用（可通过导出环境变量或在项目根目录 .env 中配置）
• 校验/迁移 checksum 需要 sha384sum 或 openssl + xxd

常用命令

export DATABASE_URL='postgres://...'

# 1) 应用迁移（写入 _sqlx_migrations）
./scripts/db/migrate.sh

# 2) 校验 schema（包含：迁移校验 + 结构校验）
./scripts/db/verify.sh

# 3) 回滚到指定版本（例如回滚到 0001）
ROLLBACK_TO_VERSION=1 ./scripts/db/rollback.sh

# 4) 回滚所有迁移（仅回滚 cms-service 自己的对象；不会卸载 pgcrypto extension）
ROLLBACK_TO_VERSION=0 ./scripts/db/rollback.sh

版本号规则

• 迁移文件目录：cms-service/migrations/*.sql
• 迁移版本号：取文件名前缀数字（例如 0002_cms.sql -> version=2）
• 回滚脚本：scripts/db/rollback/<version>.down.sql（例如 0002.down.sql）
• 校验脚本：scripts/db/verify/<version>_*.sql

故障排查

启动时报 failed to run migrations: VersionMismatch(<n>)

含义：

• 数据库 _sqlx_migrations 表里记录的 <n> 号迁移 checksum，和当前仓库里对应 migrations/<n>_*.sql 的 checksum 不一致。
• 常见原因是：迁移文件被改动过、或曾使用非 SQLx 算法写入了 _sqlx_migrations.checksum。

解决（开发环境推荐做法）：

1. 停止 cms-service
2. 回滚到 0（会删除 cms 表/类型，并清理 _sqlx_migrations 中的记录）：

ROLLBACK_TO_VERSION=0 ./scripts/db/rollback.sh

3. 重新执行迁移与校验：

./scripts/db/migrate.sh
./scripts/db/verify.sh

然后再启动 cms-service。