# 数据库版本化迁移

服务进程启动时**不会**执行数据库结构变更。数据库升级必须在备份成功、单实例维护窗口内显式运行迁移命令，避免大 SQLite 库发生隐式重建和 WAL 写放大。 // Logan.Li

## 日常命令

```bash
# 查看已应用与待执行版本
./aiops migrate status --config /srv/aiops/config.yaml

# 全新空数据库：创建初始基线并执行后续迁移
./aiops migrate up --config /srv/aiops/config.yaml

# 已存在的旧数据库：人工核验、备份完成后，只写入基线记录，不改业务表
./aiops migrate baseline --config /srv/aiops/config.yaml

# 旧库完成 baseline 后，执行后续待迁移版本
./aiops migrate up --config /srv/aiops/config.yaml
```

`baseline` 会校验 `iam_users`、`iam_roles`、`asset_servers`、`deploy_pipelines`、`monitor_agent_reports` 等核心表；校验失败时拒绝登记，不能用它绕过不完整库的恢复或专项迁移。 // Logan.Li

## 已上线数据库的切换步骤

1. 停止写入或切换至维护窗口，并完成可恢复备份。
2. 运行 `aiops migrate status`，确认已有 `0001_agent_credentials` 记录仍然存在。
3. 运行 `aiops migrate baseline`，它只登记 `0000_baseline_schema`。
4. 再运行 `aiops migrate up`；`0002_legacy_schema_patches` 会把既有的兼容字段补丁作为可审计迁移执行。
5. 再次运行 `status`，确认所有版本均为 `applied`，然后启动服务。

线上已存在的 `sys_schema_migrations(version, applied_at)` 表保持兼容：迁移框架不会假设额外列，也不会重写既有 `0001_agent_credentials` 记录。 // Logan.Li

若旧业务库甚至尚无 `sys_schema_migrations`，`migrate up` 会零写入拒绝；只能由维护人员先完成备份并显式执行 `migrate baseline`。 // Logan.Li

## 新迁移规则

- 新版本只追加到 `backend/migrations/` 和 `migrations.All()`，禁止修改或重命名已发布版本。
- 需要方言差异的 SQL 使用 `<version>.<sqlite|mysql|postgres>.sql` 三份脚本。
- 复杂或需调用 GORM 的变更使用 Go 迁移函数，但必须返回错误；禁止吞掉 DDL/DML 错误。
- MySQL DDL 可能隐式提交，执行迁移前必须备份；同一数据库同一时间只能运行一个迁移进程。
- SQLite 大表迁移与 `VACUUM` 必须在停写维护窗口执行，迁移完成后再进行 WAL checkpoint 与空间核验。