---
name: managing-db-migrations
description: "Guides PostgreSQL database migration and rollback for RMDC system. Triggered when adding tables, modifying columns, creating indexes, or evolving schema. Covers migration naming, rollback scripts, field evolution rules, and data migration. Keywords: PostgreSQL, migration, rollback, schema evolution, GORM, ALTER TABLE."
allowed-tools:
  - Read
  - Glob
  - Grep
  - Bash
  - Edit
  - Write
argument-hint: "$ARGUMENTS: <operation> [table] — operation: add-table|add-column|modify-column|add-index|rollback"
---

# managing-db-migrations

## 概述
本 Skill 指导 RMDC 系统的 PostgreSQL 数据库迁移与回滚。

## 动态上下文注入

### 查看现有迁移文件
!`ls -la migrations/ 2>/dev/null || find . -name "*migration*" -type f | head -20`

### 查看表结构定义
!`grep -rn "type.*struct" --include="*.go" -A 20 | grep -E "gorm:|TableName" | head -30`

---

## Plan（规划阶段）

### 迁移类型与影响
| 操作 | 可回滚 | 数据风险 | 锁表影响 |
|:---|:---|:---|:---|
| 新增表 | ✓ | 低 | 无 |
| 新增可空列 | ✓ | 低 | 低 |
| 新增非空列（有默认值） | ✓ | 低 | 中 |
| 修改列类型 | 需评估 | 中 | 高 |
| 删除列 | ✗ | 高 | 低 |
| 新增索引 | ✓ | 低 | 高（大表） |

### 决策点
- [ ] 是否需要停机迁移？
- [ ] 是否需要数据迁移脚本？
- [ ] 回滚脚本是否就绪？
- [ ] 是否影响现有查询性能？

---

## Verify（验证清单）

### 迁移前检查
- [ ] 迁移文件命名符合规范：`YYYYMMDDHHMMSS_description.sql`
- [ ] 包含 UP 和 DOWN 脚本
- [ ] 在测试环境验证通过
- [ ] 回滚脚本已测试

### 迁移后检查
- [ ] 表结构与预期一致
- [ ] 索引正确创建
- [ ] 现有数据未丢失
- [ ] 应用程序正常运行

### 验证命令
```bash
# 检查迁移语法
psql -h localhost -U rmdc -d rmdc_test -f migration.sql --dry-run

# 验证回滚
./scripts/verify-migration-rollback.sh
```

---

## Execute（执行步骤）

### 新增列
```sql
-- UP
ALTER TABLE users ADD COLUMN IF NOT EXISTS new_field VARCHAR(255) DEFAULT '';

-- DOWN
ALTER TABLE users DROP COLUMN IF EXISTS new_field;
```

### 新增索引（大表使用 CONCURRENTLY）
```sql
-- UP
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

-- DOWN
DROP INDEX CONCURRENTLY IF EXISTS idx_users_email;
```

---

## Pitfalls（常见坑）

1. **非空列无默认值**：现有数据无法满足约束，迁移失败。
2. **大表加索引阻塞**：未使用 CONCURRENTLY 导致表锁。
3. **删除列后回滚**：数据已丢失，无法恢复。
4. **字段类型变更**：如 `VARCHAR(50)` 改 `VARCHAR(20)`，可能截断数据。
5. **迁移顺序错误**：依赖的表/列不存在。

---

## 相关文件
| 用途 | 路径 |
|:---|:---|
| 命名规范 | [reference/migration-naming.md](reference/migration-naming.md) |
| 回滚策略 | [reference/rollback-policy.md](reference/rollback-policy.md) |
| 字段演进 | [reference/field-evolution-rules.md](reference/field-evolution-rules.md) |