huang
9795bb9ace
- 新增 6 个 Skill 文件：api-routing, db-migration, db-validation, doc-management, dto-standards, model-standards - 简化 AGENTS.md 和 CLAUDE.md，保留核心规范，详细内容移至 Skills - 添加 Skills 触发表格，说明各规范的加载时机 - 优化规范文档结构，提升可维护性和可读性
213 lines
4.3 KiB
Markdown
213 lines
4.3 KiB
Markdown
---
|
||
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`
|