70 lines
2.3 KiB
Markdown
70 lines
2.3 KiB
Markdown
# 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。
|