データマイグレーションスクリプト

目次

• 概要
• 使用場面
• クイックスタート
• リファレンスガイド
• ベストプラクティス

概要

データベーススキーマの変更とデータ変換を、最小限のダウンタイムで実行するための堅牢で安全、かつ可逆的なマイグレーションスクリプトを作成します。

使用場面

• データベーススキーマの変更
• カラムの追加/削除/変更
• データベースシステム間での移行
• データの変換とクリーンアップ
• テーブルの分割またはマージ
• データ型の変更
• インデックスと制約の追加
• データの埋め戻し
• マルチテナントデータの移行

クイックスタート

最小限の動作例:

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/ ディレクトリを参照してください:

ベストプラクティス

✅ やるべきこと

• 常に up と down の両方のマイグレーションを実装する
• 本番環境に似たデータでマイグレーションをテストする
• アトミックな操作にはトランザクションを使用する
• 大規模なデータセットはバッチで処理する
• データ挿入後にインデックスを追加する
• マイグレーション後にデータを検証する
• 進捗状況とエラーをログに記録する
• アプリケーションコード変更にはフィーチャーフラグを使用する
• マイグレーション実行前にデータベースをバックアップする
• ロールバック手順をテストする
• マイグレーションの副作用をドキュメント化する
• すべてのマイグレーションをバージョン管理する
• べき等な操作を使用する

❌ やってはいけないこと

• テストされていないマイグレーションを本番環境で実行する
• 後方互換性のない破壊的な変更を行う
• 数百万行のデータを1つのトランザクションで処理する
• ロールバック実装をスキップする
• マイグレーション失敗を無視する
• 古いマイグレーションを修正する
• バックアップなしでデータを削除する
• 本番環境でマイグレーションを手動で実行する