Flyway & データベースマイグレーション完全ガイド2025：スキーマバージョン管理、ORM統合、ゼロダウンタイムデプロイ

開発者A：「usersテーブルにphoneカラムを追加しましたよ」
開発者B：「え？ローカルにはないんですけど？」
開発者A：「Slackで共有しましたよね...」
開発者C：「ステージングは？プロダクションは？」
（3時間後に障害発生）

-- 金曜日18時、プロダクションで直接実行...
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
ALTER TABLE orders MODIFY COLUMN status ENUM('pending','processing','shipped','delivered','cancelled');

-- うっかりWHEREなしで...
UPDATE users SET role = 'admin';
-- Ctrl+C... もう遅い

Gitでコード管理              DBマイグレーションでスキーマ管理
------------------          ---------------------------
commit history       →      migration history
branch/merge         →      migration branching
code review (PR)     →      migration review
rollback (revert)    →      undo migration
CI/CD pipeline       →      migration in pipeline

プロジェクトの技術スタックは？
├── Java/Spring → FlywayまたはLiquibase
│   ├── シンプルさ重視 → Flyway
│   └── ロールバック/diff必要 → Liquibase
├── TypeScript/Node.js
│   ├── Prisma使用 → Prisma Migrate
│   ├── TypeORM使用 → TypeORM Migration
│   └── 軽量 → Knex.js
├── Python
│   ├── Django → Django Migrations
│   └── Flask/FastAPI → Alembic
├── Go → golang-migrate
└── 言語非依存、SQL直接 → Flyway CLI

flyway_migrations/
├── V1__Create_users_table.sql
├── V2__Create_orders_table.sql
├── V3__Add_email_to_users.sql
├── V4__Create_products_table.sql
├── R__Create_views.sql          # Repeatable
└── U3__Add_email_to_users.sql   # Undo (Teams)

# Homebrew
brew install flyway

# バージョン確認
flyway --version
# Flyway Community Edition 10.x.x

docker run --rm \
  -v $(pwd)/sql:/flyway/sql \
  -v $(pwd)/conf:/flyway/conf \
  flyway/flyway:10-alpine \
  migrate

<plugin>
    <groupId>org.flywaydb</groupId>
    <artifactId>flyway-maven-plugin</artifactId>
    <version>10.8.1</version>
    <configuration>
        <url>jdbc:postgresql://localhost:5432/mydb</url>
        <user>postgres</user>
        <password>secret</password>
        <locations>
            <location>filesystem:src/main/resources/db/migration</location>
        </locations>
    </configuration>
</plugin>

plugins {
    id 'org.flywaydb.flyway' version '10.8.1'
}

flyway {
    url = 'jdbc:postgresql://localhost:5432/mydb'
    user = 'postgres'
    password = 'secret'
    locations = ['filesystem:src/main/resources/db/migration']
}

V{version}__{description}.sql       # Versioned Migration
R__{description}.sql                # Repeatable Migration
U{version}__{description}.sql       # Undo Migration (Teams)

-- V1__Create_users_table.sql
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL UNIQUE,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_users_email ON users(email);
CREATE INDEX idx_users_username ON users(username);

-- V2__Create_orders_table.sql
CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    user_id BIGINT NOT NULL REFERENCES users(id),
    total_amount DECIMAL(10,2) NOT NULL,
    status VARCHAR(20) NOT NULL DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE INDEX idx_orders_user_id ON orders(user_id);
CREATE INDEX idx_orders_status ON orders(status);

-- V3__Add_phone_to_users.sql
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
ALTER TABLE users ADD COLUMN profile_image_url TEXT;

-- R__Create_reporting_views.sql（ファイル変更のたびに再実行）
CREATE OR REPLACE VIEW v_user_order_summary AS
SELECT
    u.id AS user_id,
    u.username,
    u.email,
    COUNT(o.id) AS order_count,
    COALESCE(SUM(o.total_amount), 0) AS total_spent
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
GROUP BY u.id, u.username, u.email;

# マイグレーション実行
flyway migrate

# 現在の状態確認
flyway info

# マイグレーション検証
flyway validate

# データベース初期化（注意：全オブジェクト削除）
flyway clean

# 既存DBにFlyway適用（ベースライン）
flyway baseline

# 失敗したマイグレーションの修復
flyway repair

+-----------+---------+---------------------+------+---------------------+---------+----------+
| Category  | Version | Description         | Type | Installed On        | State   | Undoable |
+-----------+---------+---------------------+------+---------------------+---------+----------+
| Versioned | 1       | Create users table  | SQL  | 2025-03-20 10:15:30 | Success | No       |
| Versioned | 2       | Create orders table | SQL  | 2025-03-20 10:15:31 | Success | No       |
| Versioned | 3       | Add phone to users  | SQL  |                     | Pending | No       |
+-----------+---------+---------------------+------+---------------------+---------+----------+

# データベース接続
flyway.url=jdbc:postgresql://localhost:5432/mydb
flyway.user=postgres
flyway.password=secret

# マイグレーションの場所
flyway.locations=filesystem:./sql,classpath:db/migration

# スキーマ
flyway.schemas=public,app
flyway.defaultSchema=app

# 履歴テーブル
flyway.table=flyway_schema_history

# エンコーディング
flyway.encoding=UTF-8

# プレースホルダー
flyway.placeholders.env=production
flyway.placeholders.schema_name=app

# バリデーション
flyway.validateOnMigrate=true
flyway.validateMigrationNaming=true

# その他
flyway.outOfOrder=false
flyway.baselineOnMigrate=false
flyway.cleanDisabled=true

[environments.default]
url = "jdbc:postgresql://localhost:5432/mydb"
user = "postgres"
password = "secret"

[flyway]
locations = ["filesystem:./sql"]
defaultSchema = "app"
table = "flyway_schema_history"
validateOnMigrate = true
cleanDisabled = true

[flyway.placeholders]
env = "production"
schema_name = "app"

-- V5__Create_audit_table.sql
CREATE TABLE ${schema_name}.audit_log (
    id BIGSERIAL PRIMARY KEY,
    table_name VARCHAR(100) NOT NULL,
    operation VARCHAR(10) NOT NULL,
    old_data JSONB,
    new_data JSONB,
    changed_by VARCHAR(100),
    changed_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

COMMENT ON TABLE ${schema_name}.audit_log IS 'Audit log for ${env} environment';

# flyway-dev.conf
flyway.url=jdbc:postgresql://localhost:5432/mydb_dev
flyway.placeholders.env=development

# flyway-staging.conf
flyway.url=jdbc:postgresql://staging-db:5432/mydb
flyway.placeholders.env=staging

# flyway-prod.conf
flyway.url=jdbc:postgresql://prod-db:5432/mydb
flyway.placeholders.env=production
flyway.cleanDisabled=true

# 環境ごとに実行
flyway -configFiles=flyway-dev.conf migrate
flyway -configFiles=flyway-staging.conf migrate
flyway -configFiles=flyway-prod.conf migrate

コールバックファイル名：
beforeMigrate.sql      - マイグレーション前
beforeEachMigrate.sql  - 各マイグレーション前
afterEachMigrate.sql   - 各マイグレーション後
afterMigrate.sql       - マイグレーション完了後
beforeClean.sql        - クリーン前
afterClean.sql         - クリーン完了後
beforeValidate.sql     - バリデーション前
afterValidate.sql      - バリデーション完了後

-- afterMigrate.sql
REFRESH MATERIALIZED VIEW CONCURRENTLY mv_daily_stats;
ANALYZE users;
ANALYZE orders;

INSERT INTO migration_audit_log (action, executed_at)
VALUES ('migration_completed', NOW());

// V6__Encrypt_user_emails.java
package db.migration;

import org.flywaydb.core.api.migration.BaseJavaMigration;
import org.flywaydb.core.api.migration.Context;
import java.sql.*;

public class V6__Encrypt_user_emails extends BaseJavaMigration {

    @Override
    public void migrate(Context context) throws Exception {
        Connection conn = context.getConnection();

        String selectSql = "SELECT id, email FROM users WHERE encrypted_email IS NULL";
        String updateSql = "UPDATE users SET encrypted_email = ? WHERE id = ?";

        try (Statement select = conn.createStatement();
             PreparedStatement update = conn.prepareStatement(updateSql)) {

            ResultSet rs = select.executeQuery(selectSql);
            int batchSize = 0;

            while (rs.next()) {
                long id = rs.getLong("id");
                String email = rs.getString("email");
                String encrypted = encrypt(email);

                update.setString(1, encrypted);
                update.setLong(2, id);
                update.addBatch();

                if (++batchSize % 1000 == 0) {
                    update.executeBatch();
                }
            }

            if (batchSize % 1000 != 0) {
                update.executeBatch();
            }
        }
    }

    private String encrypt(String value) {
        // 実際の暗号化ロジック
        return "ENC:" + value; // プレースホルダー例
    }
}

# application.yml
spring:
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: true
    baseline-version: '0'
    validate-on-migrate: true
    out-of-order: false
    table: flyway_schema_history
    schemas:
      - public
    placeholders:
      env: ${SPRING_PROFILES_ACTIVE:dev}
    clean-disabled: true
  datasource:
    url: jdbc:postgresql://localhost:5432/mydb
    username: postgres
    password: secret

// FlywayConfig.java
@Configuration
public class FlywayConfig {

    @Bean
    public FlywayMigrationStrategy flywayMigrationStrategy() {
        return flyway -> {
            MigrationInfo[] pending = flyway.info().pending();
            if (pending.length > 0) {
                System.out.println("Pending migrations: " + pending.length);
                for (MigrationInfo info : pending) {
                    System.out.println("  - " + info.getVersion()
                        + ": " + info.getDescription());
                }
            }
            flyway.migrate();
        };
    }
}

my-app/
├── src/main/resources/
│   └── db/
│       └── migration/
│           ├── V1__Create_schema.sql
│           ├── V2__Create_users.sql
│           ├── V3__Create_products.sql
│           ├── V4__Create_orders.sql
│           ├── V5__Add_indexes.sql
│           ├── V6__Create_audit_triggers.sql
│           └── R__Update_views.sql
├── flyway.toml
├── pom.xml
└── docker-compose.yml

# docker-compose.yml
version: '3.8'
services:
  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: myapp
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: secret
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data

  flyway:
    image: flyway/flyway:10-alpine
    depends_on:
      - db
    volumes:
      - ./src/main/resources/db/migration:/flyway/sql
      - ./flyway.toml:/flyway/flyway.toml
    command: migrate
    environment:
      FLYWAY_URL: jdbc:postgresql://db:5432/myapp
      FLYWAY_USER: postgres
      FLYWAY_PASSWORD: secret

volumes:
  pgdata:

# db/changelog/db.changelog-master.yaml
databaseChangeLog:
  - changeSet:
      id: 1
      author: dev-team
      changes:
        - createTable:
            tableName: users
            columns:
              - column:
                  name: id
                  type: bigint
                  autoIncrement: true
                  constraints:
                    primaryKey: true
                    nullable: false
              - column:
                  name: username
                  type: varchar(50)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: email
                  type: varchar(255)
                  constraints:
                    nullable: false
                    unique: true
              - column:
                  name: created_at
                  type: timestamp with time zone
                  defaultValueComputed: NOW()
      rollback:
        - dropTable:
            tableName: users

  - changeSet:
      id: 2
      author: dev-team
      changes:
        - addColumn:
            tableName: users
            columns:
              - column:
                  name: phone
                  type: varchar(20)
      rollback:
        - dropColumn:
            tableName: users
            columnName: phone

-- changeset dev-team:1
CREATE TABLE users (
    id BIGSERIAL PRIMARY KEY,
    username VARCHAR(50) NOT NULL UNIQUE,
    email VARCHAR(255) NOT NULL UNIQUE,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);
-- rollback DROP TABLE users;

-- changeset dev-team:2
ALTER TABLE users ADD COLUMN phone VARCHAR(20);
-- rollback ALTER TABLE users DROP COLUMN phone;

# マイグレーション実行
liquibase update

# 直近N個のチェンジセットをロールバック
liquibase rollbackCount 1

# 特定タグまでロールバック
liquibase rollback v1.0

# 現在のDBとチェンジログの差分
liquibase diff

# 既存DBからチェンジログを生成
liquibase generateChangeLog

# ステータス確認
liquibase status

Flywayを選ぶ場合：
  - 生SQLを直接書きたい
  - シンプルなワークフローを好む
  - Spring Bootエコシステム
  - チームがSQLに慣れている

Liquibaseを選ぶ場合：
  - ロールバックサポートが必須
  - マルチデータベースベンダー対応が必要
  - 既存DBからチェンジログをリバースエンジニアリングしたい
  - XML/YAMLの宣言的管理を好む
  - きめ細かいコンテキスト/条件付き実行が必要

// prisma/schema.prisma
generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String?
  phone     String?
  posts     Post[]
  orders    Order[]
  createdAt DateTime @default(now()) @map("created_at")
  updatedAt DateTime @updatedAt @map("updated_at")

  @@map("users")
}

model Post {
  id        Int      @id @default(autoincrement())
  title     String
  content   String?
  published Boolean  @default(false)
  author    User     @relation(fields: [authorId], references: [id])
  authorId  Int      @map("author_id")
  createdAt DateTime @default(now()) @map("created_at")

  @@map("posts")
}

model Order {
  id         Int         @id @default(autoincrement())
  user       User        @relation(fields: [userId], references: [id])
  userId     Int         @map("user_id")
  totalAmount Decimal    @map("total_amount") @db.Decimal(10, 2)
  status     OrderStatus @default(PENDING)
  items      OrderItem[]
  createdAt  DateTime    @default(now()) @map("created_at")

  @@map("orders")
}

model OrderItem {
  id       Int   @id @default(autoincrement())
  order    Order @relation(fields: [orderId], references: [id])
  orderId  Int   @map("order_id")
  product  String
  quantity Int
  price    Decimal @db.Decimal(10, 2)

  @@map("order_items")
}

enum OrderStatus {
  PENDING
  PROCESSING
  SHIPPED
  DELIVERED
  CANCELLED
}

# 開発用マイグレーション（作成+適用）
npx prisma migrate dev --name create_initial_schema

# プロダクション用マイグレーション（適用のみ）
npx prisma migrate deploy

# データベースリセット
npx prisma migrate reset

# マイグレーション状態確認
npx prisma migrate status

# スキーマとデータベースの差分
npx prisma migrate diff \
  --from-schema-datamodel prisma/schema.prisma \
  --to-schema-datasource prisma/schema.prisma

-- prisma/migrations/20250325_create_initial_schema/migration.sql
CREATE TYPE "OrderStatus" AS ENUM ('PENDING', 'PROCESSING', 'SHIPPED', 'DELIVERED', 'CANCELLED');

CREATE TABLE "users" (
    "id" SERIAL NOT NULL,
    "email" TEXT NOT NULL,
    "name" TEXT,
    "phone" TEXT,
    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
    "updated_at" TIMESTAMP(3) NOT NULL,

    CONSTRAINT "users_pkey" PRIMARY KEY ("id")
);

CREATE TABLE "posts" (
    "id" SERIAL NOT NULL,
    "title" TEXT NOT NULL,
    "content" TEXT,
    "published" BOOLEAN NOT NULL DEFAULT false,
    "author_id" INTEGER NOT NULL,
    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,

    CONSTRAINT "posts_pkey" PRIMARY KEY ("id")
);

CREATE UNIQUE INDEX "users_email_key" ON "users"("email");

ALTER TABLE "posts"
    ADD CONSTRAINT "posts_author_id_fkey"
    FOREIGN KEY ("author_id") REFERENCES "users"("id")
    ON DELETE RESTRICT ON UPDATE CASCADE;

1. 一時的なShadow DBを作成
2. 既存の全マイグレーションをShadow DBに適用
3. 新しいマイグレーションSQLを生成
4. 新マイグレーションをShadow DBで検証
5. Shadow DBを削除

// src/entities/User.ts
import {
  Entity, PrimaryGeneratedColumn, Column,
  CreateDateColumn, UpdateDateColumn, OneToMany
} from 'typeorm';
import { Order } from './Order';

@Entity('users')
export class User {
  @PrimaryGeneratedColumn()
  id: number;

  @Column({ type: 'varchar', length: 50, unique: true })
  username: string;

  @Column({ type: 'varchar', length: 255, unique: true })
  email: string;

  @Column({ type: 'varchar', length: 20, nullable: true })
  phone: string;

  @OneToMany(() => Order, order => order.user)
  orders: Order[];

  @CreateDateColumn({ name: 'created_at' })
  createdAt: Date;

  @UpdateDateColumn({ name: 'updated_at' })
  updatedAt: Date;
}

# エンティティの変更からマイグレーションを自動生成
npx typeorm migration:generate -d src/data-source.ts src/migrations/AddPhoneToUser

# 空のマイグレーションを作成
npx typeorm migration:create src/migrations/SeedAdminUser

# マイグレーション実行
npx typeorm migration:run -d src/data-source.ts

# 直前のマイグレーションを元に戻す
npx typeorm migration:revert -d src/data-source.ts

// src/migrations/1711234567890-AddPhoneToUser.ts
import { MigrationInterface, QueryRunner } from 'typeorm';

export class AddPhoneToUser1711234567890 implements MigrationInterface {
    name = 'AddPhoneToUser1711234567890';

    public async up(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(
            `ALTER TABLE "users" ADD "phone" varchar(20)`
        );
    }

    public async down(queryRunner: QueryRunner): Promise<void> {
        await queryRunner.query(
            `ALTER TABLE "users" DROP COLUMN "phone"`
        );
    }
}

# Alembicインストール
pip install alembic sqlalchemy psycopg2-binary

# プロジェクト初期化
alembic init alembic

# alembic/env.py（キーセクション）
from myapp.models import Base

target_metadata = Base.metadata

def run_migrations_online():
    connectable = engine_from_config(
        config.get_section(config.config_ini_section),
        prefix="sqlalchemy.",
    )
    with connectable.connect() as connection:
        context.configure(
            connection=connection,
            target_metadata=target_metadata,
            compare_type=True,
            compare_server_default=True,
        )
        with context.begin_transaction():
            context.run_migrations()

# 自動生成（モデル変更を検出）
alembic revision --autogenerate -m "add phone to users"

# 手動作成
alembic revision -m "seed initial data"

# 最新に更新
alembic upgrade head

# 特定バージョンに更新
alembic upgrade abc123

# 1ステップロールバック
alembic downgrade -1

# 現在の状態確認
alembic current

# マイグレーション履歴確認
alembic history

# alembic/versions/abc123_add_phone_to_users.py
"""add phone to users"""

from alembic import op
import sqlalchemy as sa

revision = 'abc123'
down_revision = 'prev456'
branch_labels = None
depends_on = None

def upgrade():
    op.add_column('users',
        sa.Column('phone', sa.String(20), nullable=True)
    )
    op.create_index('ix_users_phone', 'users', ['phone'])

def downgrade():
    op.drop_index('ix_users_phone', 'users')
    op.drop_column('users', 'phone')

# models.py
from django.db import models

class User(models.Model):
    username = models.CharField(max_length=50, unique=True)
    email = models.EmailField(unique=True)
    phone = models.CharField(max_length=20, blank=True, null=True)
    created_at = models.DateTimeField(auto_now_add=True)
    updated_at = models.DateTimeField(auto_now=True)

    class Meta:
        db_table = 'users'

# マイグレーション作成
python manage.py makemigrations

# マイグレーション適用
python manage.py migrate

# マイグレーション状態確認
python manage.py showmigrations

# SQLプレビュー
python manage.py sqlmigrate myapp 0002

# マイグレーション圧縮
python manage.py squashmigrations myapp 0001 0005

# migrations/0003_populate_default_roles.py
from django.db import migrations

def create_roles(apps, schema_editor):
    Role = apps.get_model('myapp', 'Role')
    roles = ['admin', 'editor', 'viewer']
    for role_name in roles:
        Role.objects.get_or_create(name=role_name)

def remove_roles(apps, schema_editor):
    Role = apps.get_model('myapp', 'Role')
    Role.objects.filter(name__in=['admin', 'editor', 'viewer']).delete()

class Migration(migrations.Migration):
    dependencies = [
        ('myapp', '0002_create_role_table'),
    ]

    operations = [
        migrations.RunPython(create_roles, remove_roles),
    ]

フェーズ1（Expand）：新カラム追加、両方に書き込み
フェーズ2（Migrate）：データバックフィル、読み取り切替
フェーズ3（Contract）：旧カラム削除

-- Migration V10: 新カラム追加
ALTER TABLE users ADD COLUMN first_name VARCHAR(50);
ALTER TABLE users ADD COLUMN last_name VARCHAR(50);

-- 双方向同期のトリガー
CREATE OR REPLACE FUNCTION sync_user_names()
RETURNS TRIGGER AS $func$
BEGIN
    IF TG_OP = 'INSERT' OR TG_OP = 'UPDATE' THEN
        IF NEW.first_name IS NULL AND NEW.username IS NOT NULL THEN
            NEW.first_name := split_part(NEW.username, ' ', 1);
            NEW.last_name := split_part(NEW.username, ' ', 2);
        ELSIF NEW.username IS NULL AND NEW.first_name IS NOT NULL THEN
            NEW.username := NEW.first_name || ' ' || COALESCE(NEW.last_name, '');
        END IF;
    END IF;
    RETURN NEW;
END;
$func$ LANGUAGE plpgsql;

CREATE TRIGGER trg_sync_user_names
    BEFORE INSERT OR UPDATE ON users
    FOR EACH ROW EXECUTE FUNCTION sync_user_names();

この時点でデプロイ：新コードはfirst_name/last_nameに書き込む
旧コードはusernameに書き込む（トリガーが同期）

-- Migration V11: 既存データのバックフィル
UPDATE users
SET first_name = split_part(username, ' ', 1),
    last_name = split_part(username, ' ', 2)
WHERE first_name IS NULL;

-- NOT NULL制約を追加
ALTER TABLE users ALTER COLUMN first_name SET NOT NULL;

-- Migration V12: 旧カラム削除（全コードが切り替わった後）
DROP TRIGGER IF EXISTS trg_sync_user_names ON users;
DROP FUNCTION IF EXISTS sync_user_names();
ALTER TABLE users DROP COLUMN username;

ステップ1：新カラム + トリガーを追加
ステップ2：データをコピー
ステップ3：コードを新カラムに切り替え
ステップ4：旧カラムを削除

-- 危険：テーブル全体ロック
ALTER TABLE users ALTER COLUMN email SET NOT NULL;

-- 安全：PostgreSQL 12+のCHECK制約
ALTER TABLE users ADD CONSTRAINT users_email_not_null
    CHECK (email IS NOT NULL) NOT VALID;

-- 別トランザクションで検証（AccessExclusiveLockなし）
ALTER TABLE users VALIDATE CONSTRAINT users_email_not_null;

-- NOT NULL制約に変換
ALTER TABLE users ALTER COLUMN email SET NOT NULL;
ALTER TABLE users DROP CONSTRAINT users_email_not_null;

gh-ost \
  --host=db-primary \
  --database=myapp \
  --table=users \
  --alter="ADD COLUMN phone VARCHAR(20)" \
  --execute \
  --allow-on-master \
  --chunk-size=1000 \
  --max-load=Threads_running=25 \
  --critical-load=Threads_running=100

pt-online-schema-change \
  --alter "ADD COLUMN phone VARCHAR(20)" \
  --host=db-primary \
  --user=admin \
  --ask-pass \
  --chunk-size=500 \
  --max-lag=1s \
  --execute \
  D=myapp,t=users

-- 危険：テーブルロック
CREATE INDEX idx_users_email ON users(email);

-- 安全：並行インデックス作成（ロックなし）
CREATE INDEX CONCURRENTLY idx_users_email ON users(email);

-- 注意：トランザクション内では使用不可
-- Flywayではこのマイグレーションのトランザクションを無効にする

-- FlywayでCONCURRENTLYを使用
-- V15__Add_index_concurrently.sql

-- Flywayトランザクション無効（ファイル先頭のコメント）
-- flyway:executeInTransaction=false

CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_users_email
ON users(email);

-- 危険：フルテーブルスキャン + ロック
ALTER TABLE orders ADD CONSTRAINT fk_orders_user
    FOREIGN KEY (user_id) REFERENCES users(id);

-- 安全：NOT VALIDで追加してから別途検証
ALTER TABLE orders ADD CONSTRAINT fk_orders_user
    FOREIGN KEY (user_id) REFERENCES users(id)
    NOT VALID;

ALTER TABLE orders VALIDATE CONSTRAINT fk_orders_user;

Forward-Only（Flywayデフォルト）：
  V1 → V2 → V3 → V4
  V4に問題 → V5を作成して修正

ロールバックサポート（Liquibase、Flyway Teams）：
  V1 → V2 → V3 → V4
  V4に問題 → V3にロールバック

-- U4__Remove_status_column.sql（V4のUndo）
ALTER TABLE orders DROP COLUMN IF EXISTS status;

# Undo実行
flyway undo

# 特定バージョンまでUndo
flyway undo -target=2

-- V4__Add_status_to_orders.sql（元のマイグレーション）
ALTER TABLE orders ADD COLUMN status VARCHAR(20) DEFAULT 'pending';

-- V5__Revert_status_from_orders.sql（補償マイグレーション）
ALTER TABLE orders DROP COLUMN IF EXISTS status;

ロールバックすべきでない場合：
  1. カラム削除によるデータ損失
     - DROP COLUMNは復旧不可
     - 削除前に必ずバックアップを確認

  2. 非可逆データ変換
     - UPDATEでデータ形式を変更
     - 元データが保存されていない

  3. 大規模データ移行
     - 数百万行を移動
     - ロールバック時間が許容範囲を超過

  4. 外部システム連携
     - 外部コンシューマーがAPI変更を適用済み
     - 外部システムはロールバック不可

# .github/workflows/db-migration.yml
name: Database Migration

on:
  push:
    branches: [main]
    paths:
      - 'db/migration/**'
  pull_request:
    paths:
      - 'db/migration/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16-alpine
        env:
          POSTGRES_DB: testdb
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: testpass
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

    steps:
      - uses: actions/checkout@v4

      - name: Run Flyway Validate
        run: |
          docker run --rm --network host \
            -v $(pwd)/db/migration:/flyway/sql \
            flyway/flyway:10-alpine \
            -url=jdbc:postgresql://localhost:5432/testdb \
            -user=postgres \
            -password=testpass \
            validate

      - name: Run Flyway Info
        run: |
          docker run --rm --network host \
            -v $(pwd)/db/migration:/flyway/sql \
            flyway/flyway:10-alpine \
            -url=jdbc:postgresql://localhost:5432/testdb \
            -user=postgres \
            -password=testpass \
            info

      - name: Test Migration
        run: |
          docker run --rm --network host \
            -v $(pwd)/db/migration:/flyway/sql \
            flyway/flyway:10-alpine \
            -url=jdbc:postgresql://localhost:5432/testdb \
            -user=postgres \
            -password=testpass \
            migrate

      - name: Verify Schema
        run: |
          PGPASSWORD=testpass psql -h localhost -U postgres -d testdb -c "
            SELECT table_name FROM information_schema.tables
            WHERE table_schema = 'public'
            ORDER BY table_name;
          "

  deploy-staging:
    needs: validate
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Staging
        run: |
          docker run --rm \
            -v $(pwd)/db/migration:/flyway/sql \
            flyway/flyway:10-alpine \
            -url=$STAGING_DB_URL \
            -user=$STAGING_DB_USER \
            -password=$STAGING_DB_PASSWORD \
            migrate
        env:
          STAGING_DB_URL: ${{ secrets.STAGING_DB_URL }}
          STAGING_DB_USER: ${{ secrets.STAGING_DB_USER }}
          STAGING_DB_PASSWORD: ${{ secrets.STAGING_DB_PASSWORD }}

  deploy-production:
    needs: deploy-staging
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    environment: production
    steps:
      - uses: actions/checkout@v4

      - name: Deploy to Production
        run: |
          docker run --rm \
            -v $(pwd)/db/migration:/flyway/sql \
            flyway/flyway:10-alpine \
            -url=$PROD_DB_URL \
            -user=$PROD_DB_USER \
            -password=$PROD_DB_PASSWORD \
            -validateOnMigrate=true \
            migrate
        env:
          PROD_DB_URL: ${{ secrets.PROD_DB_URL }}
          PROD_DB_USER: ${{ secrets.PROD_DB_USER }}
          PROD_DB_PASSWORD: ${{ secrets.PROD_DB_PASSWORD }}

タイムライン →

1. [Blue稼働中] DB v1, App v1
2. [Blue稼働中] DB v1 → v2マイグレーション（後方互換性あり）
3. [Blue稼働中] App v2をGreenにデプロイ
4. [Blue → Green切替] トラフィック切り替え
5. [Green稼働中] Blueを廃止

キー：DBマイグレーションは必ず後方互換性を維持
     旧バージョンのコードが新スキーマで動作すること

# k8s/deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: myapp
spec:
  replicas: 3
  selector:
    matchLabels:
      app: myapp
  template:
    metadata:
      labels:
        app: myapp
    spec:
      initContainers:
        - name: flyway-migrate
          image: flyway/flyway:10-alpine
          args: ["migrate"]
          env:
            - name: FLYWAY_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
            - name: FLYWAY_USER
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: username
            - name: FLYWAY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: password
          volumeMounts:
            - name: migrations
              mountPath: /flyway/sql
      containers:
        - name: myapp
          image: myapp:latest
          ports:
            - containerPort: 8080
      volumes:
        - name: migrations
          configMap:
            name: flyway-migrations

# k8s/migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: flyway-migrate-v10
  labels:
    app: flyway-migration
spec:
  backoffLimit: 3
  activeDeadlineSeconds: 300
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: flyway
          image: flyway/flyway:10-alpine
          args: ["migrate"]
          env:
            - name: FLYWAY_URL
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: url
            - name: FLYWAY_USER
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: username
            - name: FLYWAY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: db-secret
                  key: password
            - name: FLYWAY_VALIDATE_ON_MIGRATE
              value: "true"
            - name: FLYWAY_CONNECT_RETRIES
              value: "5"
          volumeMounts:
            - name: migrations
              mountPath: /flyway/sql
      volumes:
        - name: migrations
          configMap:
            name: flyway-migrations

# helm/templates/migration-job.yaml
apiVersion: batch/v1
kind: Job
metadata:
  name: "{{ .Release.Name }}-flyway-migrate"
  annotations:
    "helm.sh/hook": pre-install,pre-upgrade
    "helm.sh/hook-weight": "-1"
    "helm.sh/hook-delete-policy": hook-succeeded
spec:
  backoffLimit: 3
  template:
    spec:
      restartPolicy: Never
      containers:
        - name: flyway
          image: "flyway/flyway:{{ .Values.flyway.version }}"
          args: ["migrate"]
          env:
            - name: FLYWAY_URL
              value: "jdbc:postgresql://{{ .Values.db.host }}:{{ .Values.db.port }}/{{ .Values.db.name }}"
            - name: FLYWAY_USER
              valueFrom:
                secretKeyRef:
                  name: "{{ .Values.db.secretName }}"
                  key: username
            - name: FLYWAY_PASSWORD
              valueFrom:
                secretKeyRef:
                  name: "{{ .Values.db.secretName }}"
                  key: password
          volumeMounts:
            - name: migrations
              mountPath: /flyway/sql
      volumes:
        - name: migrations
          configMap:
            name: "{{ .Release.Name }}-migrations"

Flyway組み込みロック：
  - flyway_schema_historyテーブルに組み込みロック機構あり
  - 最初のインスタンスがマイグレーションを実行
  - 他は待機してからスキップ

追加の安全対策：
  - K8s Job（単一Pod）を推奨
  - Init Containerアプローチ：各Podが試行（Flywayがロック処理）
  - DB Advisory Lockで追加の安全性

-- カスタムロック機構（Advisory Lock）
-- beforeMigrate.sql
SELECT pg_advisory_lock(12345);

-- afterMigrate.sql
SELECT pg_advisory_unlock(12345);

# argocd/application.yaml
apiVersion: argoproj.io/v1alpha1
kind: Application
metadata:
  name: myapp
spec:
  project: default
  source:
    repoURL: https://github.com/myorg/myapp.git
    path: helm
    targetRevision: main
  destination:
    server: https://kubernetes.default.svc
    namespace: production
  syncPolicy:
    automated:
      prune: true
      selfHeal: true
    syncOptions:
      - CreateNamespace=true
    retry:
      limit: 3
      backoff:
        duration: 5s
        factor: 2
        maxDuration: 3m

ArgoCD同期フロー：
1. Gitの変更を検出
2. Helm hook (pre-upgrade) → Flyway Jobを実行
3. Flywayマイグレーション成功
4. アプリケーションDeploymentが更新
5. ArgoCD同期完了

良い例：
  V1__Create_users_table.sql
  V2__Add_email_index.sql
  V3__Create_orders_table.sql

悪い例：
  V1__Create_all_tables_and_indexes_and_data.sql

してはいけないこと：
  - 既に実行されたV1__Create_users.sqlを編集
  - Flywayがチェックサムで変更を検出 → エラー

正しいアプローチ：
  - 新しいマイグレーションファイルを作成（V5__Fix_users_table.sql）

# プロダクション規模のデータでテスト
# 1000万行のテーブルでALTER TABLEをテスト

# テストデータ生成
INSERT INTO users_test (username, email)
SELECT
    'user_' || generate_series,
    'user_' || generate_series || '@example.com'
FROM generate_series(1, 10000000);

# マイグレーション実行時間を測定
\timing on
ALTER TABLE users_test ADD COLUMN phone VARCHAR(20);
# Time: 45123.456 ms（約45秒） - プロダクションで45秒のロック！

V10__Add_status_column.sql       # スキーマ変更
V11__Backfill_status_data.sql    # データ変更
V12__Add_status_not_null.sql     # 制約追加

-- 悪い例：一度に全て更新
UPDATE users SET normalized_email = LOWER(email);

-- 良い例：バッチ処理
DO $block$
DECLARE
    batch_size INT := 10000;
    total_updated INT := 0;
    rows_affected INT;
BEGIN
    LOOP
        UPDATE users
        SET normalized_email = LOWER(email)
        WHERE id IN (
            SELECT id FROM users
            WHERE normalized_email IS NULL
            LIMIT batch_size
        );
        GET DIAGNOSTICS rows_affected = ROW_COUNT;
        total_updated := total_updated + rows_affected;
        RAISE NOTICE 'Updated % rows (total: %)', rows_affected, total_updated;
        EXIT WHEN rows_affected = 0;
        PERFORM pg_sleep(0.1);
    END LOOP;
END;
$block$;

アンチパターン1：プロダクションで直接DDLを実行
  → 必ずマイグレーションファイルを経由

アンチパターン2：環境ごとに異なるマイグレーションファイル
  → 全環境で同じマイグレーション（プレースホルダーを使用）

アンチパターン3：マイグレーションにビジネスロジック
  → マイグレーションはスキーマ/データ変更のみ。ロジックはアプリケーションに

アンチパターン4：後方互換性を無視
  → ゼロダウンタイムデプロイでは旧コードが新スキーマで動作すること

アンチパターン5：テストなしでプロダクションにデプロイ
  → CIでテストDBを使って必ず検証

アンチパターン6：ロールバック計画なしでデプロイ
  → 全マイグレーションにロールバック/補償戦略を準備

アンチパターン7：マイグレーションツールのバージョンを固定しない
  → ロックファイルまたは明示的なバージョン指定を使用

デプロイ前レビュー：
  [ ] マイグレーションSQLコードをレビュー済み
  [ ] 後方互換性を確認（旧コードで動作するか）
  [ ] プロダクション相当のデータでテスト済み
  [ ] 実行時間を測定（大規模テーブルに注意）
  [ ] ロックの影響を分析
  [ ] ロールバック/補償マイグレーションを準備

デプロイ中：
  [ ] データベースバックアップを確認
  [ ] モニタリングダッシュボードを確認（CPU、接続数、スロークエリ）
  [ ] メンテナンスウィンドウ内で実行（必要に応じて）
  [ ] flyway validateを先に実行
  [ ] マイグレーション後にflyway infoを確認
  [ ] アプリケーションヘルスチェックを確認

デプロイ後：
  [ ] スキーマ変更を確認（テーブル、インデックス、制約）
  [ ] アプリケーションの正常動作を確認
  [ ] パフォーマンスモニタリング（クエリ性能の変化）
  [ ] エラーログを確認
  [ ] チームに共有（変更内容、影響範囲）