data-migration-scripts

数据迁移脚本

目录

• 概述
• 适用场景
• 快速入门
• 参考指南
• 最佳实践

概述

为数据库架构变更和数据转换编写可靠、安全且可逆的数据迁移脚本，尽可能减少停机时间。

适用场景

• 数据库架构变更
• 添加／删除／修改列
• 在不同数据库系统之间迁移
• 数据转换和清理
• 拆分或合并表
• 更改数据类型
• 添加索引和约束
• 回填数据
• 多租户数据迁移

快速入门

最小可运行示例：

import { Knex } from "knex";

// migrations/20240101000000_add_user_preferences.ts
export async function up(knex: Knex): Promise<void> {
  // Create new table
  await knex.schema.createTable("user_preferences", (table) => {
    table.uuid("id").primary().defaultTo(knex.raw("gen_random_uuid()"));
    table
      .uuid("user_id")
      .notNullable()
      .references("id")
      .inTable("users")
      .onDelete("CASCADE");
    table.jsonb("preferences").defaultTo("{}");
    table.timestamp("created_at").defaultTo(knex.fn.now());
    table.timestamp("updated_at").defaultTo(knex.fn.now());

    table.index("user_id");
  });

  // Migrate existing data
  await knex.raw(`
    INSERT INTO user_preferences (user_id, preferences)
    SELECT id, jsonb_build_object(
      'theme', COALESCE(theme, 'light'),
// ... (see reference guides for full implementation)

参考指南

references/ 目录中的详细实现：

指南	内容
Knex.js 迁移（Node.js）	Knex.js 迁移（Node.js）
Alembic 迁移（Python/SQLAlchemy）	Alembic 迁移（Python/SQLAlchemy）
批量处理大型数据迁移	批量处理大型数据迁移
零停机迁移模式	零停机迁移模式
迁移验证	迁移验证
跨数据库迁移	跨数据库迁移

最佳实践

✅ 应该做

• 始终同时编写 up 和 down 迁移
• 在类似生产环境的数据上测试迁移
• 对原子操作使用事务
• 分批处理大型数据集
• 在插入数据后添加索引
• 在迁移后验证数据
• 记录进度和错误
• 对应用代码变更使用功能标志
• 运行迁移前备份数据库
• 测试回滚流程
• 记录迁移的副作用
• 对所有迁移进行版本控制
• 使用幂等操作

❌ 不应该做

• 在生产环境运行未经测试的迁移
• 在不保证向后兼容的情况下进行破坏性变更
• 在单个事务中处理数百万行
• 跳过回滚实现
• 忽略迁移失败
• 修改旧迁移
• 不备份就删除数据
• 在生产环境手动运行迁移