---
name: db-migration
description: 数据库迁移规范。创建迁移、修改数据库结构、执行 migrate 命令时使用。包含迁移工具、文件规范、执行流程、失败处理等完整指南。
---

# 数据库迁移规范

**项目使用 golang-migrate 进行数据库迁移管理。**

## 触发条件

在以下情况下必须遵守本规范：
- 创建新的数据库迁移
- 修改数据库表结构
- 执行 `make migrate-*` 命令
- 处理迁移失败问题

## 基本命令

```bash
# 查看当前迁移版本
make migrate-version

# 执行所有待迁移
make migrate-up

# 回滚上一次迁移
make migrate-down

# 创建新迁移文件
make migrate-create
# 然后输入迁移名称，例如: add_user_email
```

## 迁移文件规范

### 文件位置和命名

迁移文件位于 `migrations/` 目录：

```
migrations/
├── 000001_initial_schema.up.sql
├── 000001_initial_schema.down.sql
├── 000002_add_user_email.up.sql
├── 000002_add_user_email.down.sql
```

**命名规范**:
- 格式: `{序号}_{描述}.{up|down}.sql`
- 序号: 6位数字，从 000001 开始
- 描述: 小写英文，用下划线分隔
- up: 应用迁移（向前）
- down: 回滚迁移（向后）

### 编写规范

```sql
-- up.sql 示例
-- 添加字段时必须考虑向后兼容
ALTER TABLE tb_users 
ADD COLUMN email VARCHAR(100);

-- 添加注释
COMMENT ON COLUMN tb_users.email IS '用户邮箱';

-- 为现有数据设置默认值（如果需要）
UPDATE tb_users SET email = '' WHERE email IS NULL;

-- down.sql 示例
ALTER TABLE tb_users 
DROP COLUMN IF EXISTS email;
```

## 迁移执行流程（必须遵守）

当你创建迁移文件后，**必须**执行以下验证步骤：

### 1. 执行迁移

```bash
make migrate-up
```

### 2. 验证迁移状态

```bash
make migrate-version
# 确认版本号已更新且 dirty=false
```

### 3. 验证数据库结构

使用 PostgreSQL MCP 工具检查：
- 字段是否正确创建
- 类型是否符合预期
- 默认值是否正确
- 注释是否存在

```
PostgresGetObjectDetails:
- schema_name: "public"
- object_name: "tb_users"
- object_type: "table"
```

### 4. 验证查询功能

编写临时脚本测试新字段的查询功能

### 5. 更新 Model

在 `internal/model/` 中添加对应字段

### 6. 清理测试数据

如果插入了测试数据，记得清理

## 迁移失败处理

如果迁移执行失败，数据库会被标记为 dirty 状态：

```bash
# 1. 检查错误原因
make migrate-version
# 如果显示 dirty=true，说明迁移失败

# 2. 手动修复数据库状态
# 使用 PostgreSQL MCP 连接数据库
# 检查失败的迁移是否部分执行
# 手动清理或完成迁移

# 3. 清除 dirty 标记
UPDATE schema_migrations SET dirty = false WHERE version = {失败的版本号};

# 4. 修复迁移文件中的错误

# 5. 重新执行迁移
make migrate-up
```

## 迁移最佳实践

### 1. 向后兼容

- 添加字段时使用 `DEFAULT` 或允许 NULL
- 删除字段前确保代码已不再使用
- 修改字段类型要考虑数据转换

### 2. 原子性

- 每个迁移文件只做一件事
- 复杂变更拆分成多个迁移

### 3. 可回滚

- down.sql 必须能完整回滚 up.sql 的所有变更
- 测试回滚功能: `make migrate-down && make migrate-up`

### 4. 注释完整

- 迁移文件顶部说明变更原因
- 关键 SQL 添加行内注释
- 数据库字段使用 COMMENT 添加说明

### 5. 测试数据

- 不要在迁移文件中插入业务数据
- 可以插入配置数据或枚举值
- 测试数据用临时脚本处理

## PostgreSQL MCP 工具使用

### 查看表结构

```
PostgresGetObjectDetails: 
- schema_name: "public"
- object_name: "tb_permission"
- object_type: "table"
```

### 列出所有表

```
PostgresListObjects:
- schema_name: "public"
- object_type: "table"
```

### 执行查询

```
PostgresExecuteSql:
- sql: "SELECT * FROM tb_permission LIMIT 5"
```

## 注意事项

- ⚠️ MCP 工具只支持只读查询（SELECT）
- ⚠️ 不要直接修改数据，修改必须通过迁移文件
- ⚠️ 测试数据可以通过临时 Go 脚本插入

## AI 助手检查清单

创建迁移后必须：

1. ✅ 执行 `make migrate-up`
2. ✅ 执行 `make migrate-version` 确认成功
3. ✅ 使用 PostgresGetObjectDetails 验证表结构
4. ✅ 在 `internal/model/` 中更新对应 Model
5. ✅ 测试回滚：`make migrate-down && make migrate-up`