# 数据库迁移管理系统使用指南

## 📋 概述

这是一个为 Flask + MySQL + Docker 环境设计的数据库迁移管理系统，提供安全、可控的数据库结构更新机制。

## 🏗️ 系统架构

### 核心组件
- **DatabaseMigrationManager**: 迁移管理器核心类
- **migrate.py**: 命令行工具
- **migrations/**: 迁移文件目录
- **CI/CD集成**: 自动化部署和迁移

### 安全特性
- ✅ **自动备份**: 每次迁移前自动创建数据库备份
- ✅ **事务性执行**: 迁移失败自动回滚
- ✅ **版本控制**: 完整的迁移历史记录
- ✅ **校验和验证**: 防止迁移文件被意外修改
- ✅ **试运行模式**: 执行前验证SQL语法

## 🚀 快速开始

### 1. 安装依赖
```bash
pip install pymysql
```

### 2. 配置数据库连接
确保 `database_config.py` 中的 `get_database_config()` 函数返回正确的数据库配置。

### 3. 初始化迁移系统
```bash
python migrate.py status
```

## 📝 创建迁移

### 创建新迁移文件
```bash
python migrate.py create "add_user_email" "为用户表添加邮箱字段"
```

这会创建一个新的迁移文件：`migrations/20250105_143022_add_user_email.sql`

### 编辑迁移文件
```sql
-- ==========================================
-- UP Migration (执行迁移)
-- ==========================================

ALTER TABLE users 
ADD COLUMN email VARCHAR(255) NULL AFTER username;

ALTER TABLE users 
ADD UNIQUE INDEX idx_users_email (email);

-- ==========================================
-- DOWN Migration (回滚迁移)
-- ==========================================

ALTER TABLE users 
DROP INDEX idx_users_email;

ALTER TABLE users 
DROP COLUMN email;
```

## 🔧 执行迁移

### 查看迁移状态
```bash
python migrate.py status
```

### 试运行迁移（推荐）
```bash
python migrate.py migrate --dry-run
```

### 执行迁移
```bash
python migrate.py migrate
```

### 执行到指定版本
```bash
python migrate.py migrate --target=20250105_143022
```

## 🔄 回滚迁移

### 回滚指定版本
```bash
python migrate.py rollback 20250105_143022
```

**注意**: 回滚操作需要迁移文件包含完整的 DOWN 部分。

## 🔍 验证和维护

### 验证迁移文件
```bash
python migrate.py validate
```

### 查看详细状态
```bash
python migrate.py status
```

## 🐳 Docker 环境使用

### 在容器中执行迁移
```bash
docker compose exec patient_callback_app python migrate.py status
docker compose exec patient_callback_app python migrate.py migrate --dry-run
docker compose exec patient_callback_app python migrate.py migrate
```

## 🚀 CI/CD 集成

### 使用新的 CI/CD 配置
1. 将 `.gitlab-ci-new.yml` 重命名为 `.gitlab-ci.yml`
2. 确保环境变量配置正确：
   - `SSH_PRIVATE_KEY`
   - `SSH_KNOWN_HOSTS`
   - `SSH_PORT`
   - `SSH_USER`
   - `SSH_HOST`
   - `DB_PASSWORD`

### 部署流程
1. **验证阶段**: 验证迁移文件语法和完整性
2. **部署阶段**: 更新代码和重启容器
3. **迁移阶段**: 执行数据库迁移
4. **测试阶段**: 验证部署结果

## 📁 文件结构

```
customer-recall/
├── database_migration_manager.py  # 迁移管理器
├── migrate.py                     # 命令行工具
├── migrations/                    # 迁移文件目录
│   ├── 20250101_000000_initial_schema.sql
│   └── 20250102_120000_add_user_email.sql
├── deploy_scripts/
│   └── deploy_with_migration.sh   # 集成迁移的部署脚本
└── .gitlab-ci-new.yml            # 新的CI/CD配置
```

## 🛡️ 安全最佳实践

### 1. 迁移文件编写
- ✅ 总是提供 DOWN 迁移用于回滚
- ✅ 使用事务安全的操作
- ✅ 避免删除数据的操作
- ✅ 大表操作考虑分批执行

### 2. 生产环境部署
- ✅ 部署前在测试环境验证
- ✅ 使用 `--dry-run` 验证SQL语法
- ✅ 确保数据库备份完整
- ✅ 监控迁移执行时间

### 3. 回滚准备
- ✅ 测试回滚脚本的正确性
- ✅ 保留足够的备份文件
- ✅ 记录回滚操作步骤

## 🚨 故障处理

### 迁移失败处理
1. 检查错误日志
2. 验证数据库连接
3. 检查SQL语法
4. 必要时手动回滚

### 回滚失败处理
1. 使用数据库备份恢复
2. 手动执行回滚SQL
3. 更新迁移历史表

### 紧急恢复
```bash
# 使用备份恢复数据库
mysql -u root -p callback_system < database_backups/migration_backup_20250105_143022.sql

# 手动更新迁移历史
UPDATE migration_history SET status = 'ROLLED_BACK' WHERE version = '20250105_143022';
```

## 📊 监控和日志

### 迁移历史查询
```sql
SELECT * FROM migration_history ORDER BY executed_at DESC LIMIT 10;
```

### 性能监控
- 监控迁移执行时间
- 检查数据库锁等待
- 观察系统资源使用

## 🔧 高级功能

### 自定义迁移管理器
```python
from database_migration_manager import DatabaseMigrationManager

# 自定义配置
manager = DatabaseMigrationManager(
    db_config=custom_config,
    migrations_dir="custom_migrations"
)

# 程序化执行迁移
success = manager.migrate(target_version="20250105_143022")
```

### 批量操作
```python
# 获取待执行迁移
pending = manager.get_pending_migrations()

# 逐个执行并记录结果
for migration in pending:
    success = manager.execute_migration(migration)
    if not success:
        break
```

## 📞 支持和维护

如有问题，请检查：
1. 数据库连接配置
2. 迁移文件语法
3. 权限设置
4. 日志文件内容

---

**重要提醒**: 在生产环境执行迁移前，请务必在测试环境充分验证！
