📌 系统概述
这是一个可持续维护的数据库迁移解决方案，自动化处理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与代码始终保持同步，无需手动维护迁移清单! 🎉
