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 Migrations (Node.js)	Knex.js のマイグレーション（Node.js）
Alembic Migrations (Python/SQLAlchemy)	Alembic のマイグレーション（Python/SQLAlchemy）
Large Data Migration with Batching	バッチ処理を使った大規模データ移行
Zero-Downtime Migration Pattern	ゼロダウンタイム移行パターン
Migration Validation	マイグレーションの検証
Cross-Database Migration	データベース間の移行

ベストプラクティス

✅ DO

• up と down のマイグレーションを必ず両方作成します
• 本番環境に近いデータでマイグレーションをテストします
• アトミックな操作にはトランザクションを使用します
• 大規模なデータセットはバッチ処理します
• データ挿入後にインデックスを追加します
• マイグレーション後にデータを検証します
• 進行状況とエラーを記録します
• アプリケーションコードの変更には機能フラグを使用します
• マイグレーションの実行前にデータベースをバックアップします
• ロールバック手順をテストします
• マイグレーションの副作用を文書化します
• すべてのマイグレーションをバージョン管理します
• 冪等な操作を使用します

❌ DON'T

• テストしていないマイグレーションを本番環境で実行しません
• 後方互換性のない破壊的変更を行いません
• 数百万行を単一のトランザクションで処理しません
• ロールバックの実装を省略しません
• マイグレーションの失敗を無視しません
• 古いマイグレーションを変更しません
• バックアップなしでデータを削除しません
• 本番環境でマイグレーションを手動実行しません