junhong_cmp_fiber/.claude/skills/db-migration/SKILL.md

name, description

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

数据库迁移规范

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

触发条件

在以下情况下必须遵守本规范：

• 创建新的数据库迁移
• 修改数据库表结构
• 执行 make migrate-* 命令
• 处理迁移失败问题

基本命令

# 查看当前迁移版本
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: 回滚迁移（向后）

编写规范

-- 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. 执行迁移

make migrate-up

2. 验证迁移状态

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 状态：

# 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