# 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`

## 常用命令

```bash
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` 中的记录）：

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

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

```bash
./scripts/db/migrate.sh
./scripts/db/verify.sh
```

然后再启动 cms-service。