🗄 EchoFlow 数据库迁移系统

📌 系统概述

这是一个可持续维护的数据库迁移解决方案，自动化处理schema变更，支持多数据库切换，与开发流程深度集成。

🚀 核心特性

✨ 自动化迁移管理

自动检测: 实体变更时自动生成迁移文件
智能分析: 评估迁移风险和时间
安全执行: 生产环境安全迁移流程
一键回滚: 失败时快速恢复

🔄 多数据库支持

无缝切换: SQLite ↔ PostgreSQL ↔ MySQL ↔ MongoDB
零停机: 蓝绿部署迁移策略
数据验证: 自动验证迁移结果

🛠 开发者友好

CLI工具: 简单易用的命令行界面
Git集成: 提交时自动检查schema变更
CI/CD: 部署流水线集成

📚 使用指南

日常开发流程

1. 修改实体后自动处理

# 1. 修改实体文件 (例如: user-audio-settings.entity.ts)
# 2. 自动生成迁移
yarn db:generate

# 3. 查看迁移计划
yarn db:analyze

# 4. 执行迁移
yarn db:migrate

2. 手动管理迁移

# 生成迁移 (指定名称)
yarn db:generate --name add-user-settings

# 模拟执行 (查看会发生什么)
yarn db:migrate --dry-run

# 实际执行
yarn db:migrate

# 回滚
yarn db:rollback

3. 数据库切换

# 切换到 PostgreSQL
yarn db:switch postgres

# 切换到 MySQL  
yarn db:switch mysql

# 模拟切换 (不实际执行)
yarn db:switch postgres --dry-run

4. 生产部署

# 部署前检查
yarn db:pre-deploy

# 生产环境安全迁移
yarn db:migrate --production

# 健康检查
yarn db:health

🎯 实际使用场景

场景1: 添加新字段

// 1. 修改实体
@Entity('user_audio_settings')
export class UserAudioSettingEntity {
  // ... 现有字段
  
  @Column({ type: 'varchar', length: 100, nullable: true })
  newField: string; // 新增字段
}

// 2. 自动生成迁移
// yarn db:generate
// ✅ 迁移文件生成成功: add-new-field-1703123456

// 3. 查看计划
// yarn db:analyze
// 📋 迁移计划:
//   待执行迁移: 1 个
//   预估时间: 30秒  
//   操作类型: 修改表结构
//   风险提示: ⚡ 可能需要数据转换

// 4. 执行迁移
// yarn db:migrate
// ✅ 迁移执行成功

场景2: 数据库切换

// 当前: SQLite
// 目标: PostgreSQL

// 1. 分析当前状态
yarn db:analyze
// 📋 当前数据库: SQLite
//   数据量: 1,245 条记录
//   预估迁移时间: 2分钟

// 2. 切换数据库
yarn db:switch postgres
// 🔄 切换到 postgres 数据库...
// 📦 创建数据备份...
// 🏗 创建目标数据库schema...
// 📊 迁移数据...
// ✅ 数据库切换到 postgres 完成！

// 3. 验证结果
yarn db:health
// ✅ 数据库连接正常
// ✅ 迁移状态正常  
// ✅ 数据一致性检查通过

场景3: 生产部署

# CI/CD 流水线
name: Deploy to Production
on:
  push:
    branches: [main]

jobs:
  deploy:
    steps:
      # ... 其他步骤
      
      - name: 数据库迁移检查
        run: |
          yarn db:pre-deploy
          if [ $? -ne 0 ]; then
            echo "❌ 数据库迁移检查失败，停止部署"
            exit 1
          fi
      
      - name: 执行数据库迁移
        run: yarn db:migrate --production
        
      - name: 健康检查
        run: yarn db:health

📖 命令参考

基础命令

命令	说明	示例
`db:analyze`	分析迁移需求	`yarn db:analyze`
`db:generate`	生成迁移文件	`yarn db:generate --name update-schema`
`db:migrate`	执行迁移	`yarn db:migrate`
`db:rollback`	回滚迁移	`yarn db:rollback --steps 2`
`db:health`	健康检查	`yarn db:health`

高级命令

命令	说明	示例
`db:switch`	切换数据库	`yarn db:switch postgres`
`db:pre-deploy`	部署前检查	`yarn db:pre-deploy`
`db:migrate --production`	生产迁移	`yarn db:migrate --production`
`db:migrate --dry-run`	模拟执行	`yarn db:migrate --dry-run`

🔧 配置说明

数据库配置

// src/config/database.config.ts
export const databaseConfig = {
  type: process.env.DB_TYPE || 'sqlite',
  // SQLite 配置
  database: 'data/echoflow.db',
  // PostgreSQL 配置  
  host: process.env.DB_HOST,
  port: process.env.DB_PORT,
  username: process.env.DB_USERNAME,
  password: process.env.DB_PASSWORD,
};

环境变量

# .env
DB_TYPE=sqlite          # sqlite|postgres|mysql
DB_HOST=localhost       # 数据库主机
DB_PORT=5432           # 数据库端口
DB_USERNAME=postgres   # 用户名
DB_PASSWORD=password   # 密码
DB_NAME=echoflow      # 数据库名

🛡 安全最佳实践

1. 生产环境迁移

✅ 总是先备份数据
✅ 在维护窗口执行
✅ 使用 --production 模式
✅ 验证迁移结果

2. 风险控制

⚠️ 删除操作需人工确认
⚠️ 大数据量分批迁移
⚠️ 保留回滚方案

3. 监控告警

📊 迁移时间监控
📊 数据一致性检查
📊 性能影响评估

🚀 与项目集成

这个迁移系统已经完全集成到EchoFlow项目中：

自动化: 修改实体→自动生成迁移→安全执行
可持续: 支持未来所有领域模型变更
零配置: 开箱即用，无需额外设置
生产就绪: 经过测试，可在生产环境安全使用

每次添加新的领域模型或修改现有模型时，系统会自动：

🔍 检测变更
📝 生成迁移文件
⚡ 评估风险
🚀 安全执行

这确保了数据库schema与代码始终保持同步，无需手动维护迁移清单! 🎉