Antigravity Agent でデータベースマイグレーションを安全に自動化する方法

# Database Migration Policy
 
## Rules
- Always create reversible migrations (include down migration)
- Never drop columns directly — rename to _deprecated first
- Add NOT NULL columns with DEFAULT value to avoid breaking existing rows
- Create indexes concurrently for tables with > 10,000 rows
- Migration file names must follow: YYYYMMDD_HHMMSS_description.sql
 
## Naming Conventions
- Tables: snake_case, plural (e.g., user_profiles)
- Columns: snake_case (e.g., created_at)
- Indexes: idx_{table}_{columns} (e.g., idx_users_email)
- Foreign keys: fk_{table}_{ref_table} (e.g., fk_orders_users)
 
## Safety Checks
- Verify no data loss before applying
- Check for long-running locks on production tables
- Estimate migration duration for large tables

// prisma/schema.prisma — エージェントが自動更新
model User {
  id        Int      @id @default(autoincrement())
  email     String   @unique
  name      String
  avatarUrl String?  // Step 1: nullable で追加
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

-- prisma/migrations/20260328_153000_add_avatar_url/migration.sql
-- Step 1: nullable カラムを追加（ダウンタイムなし）
ALTER TABLE "User" ADD COLUMN "avatar_url" TEXT;
 
-- 期待される結果: User テーブルに avatar_url カラムが追加される
-- 既存の行は avatar_url = NULL となる

// src/db/schema.ts — エージェントが自動更新
import { pgTable, serial, text, timestamp, index } from "drizzle-orm/pg-core";
 
export const users = pgTable(
  "users",
  {
    id: serial("id").primaryKey(),
    email: text("email").notNull().unique(),
    name: text("name").notNull(),
    avatarUrl: text("avatar_url"), // エージェントが追加
    createdAt: timestamp("created_at").defaultNow().notNull(),
    updatedAt: timestamp("updated_at").defaultNow().notNull(),
  },
  (table) => ({
    // エージェントがインデックスも自動提案
    emailIdx: index("idx_users_email").on(table.email),
  })
);

# エージェントが自動実行するコマンド
npx drizzle-kit generate  # マイグレーションファイル生成
npx drizzle-kit push      # 開発DBに適用
 
# 期待される出力:
# Generated migration: 0001_add_avatar_url.sql
# Applied 1 migration(s)

## Migration Review Checklist
- [ ] Reversible: DOWN migration exists and is tested
- [ ] No data loss: SELECT COUNT before/after matches
- [ ] Performance: No full table locks on tables > 100K rows
- [ ] Indexes: New columns used in WHERE/JOIN have indexes
- [ ] Defaults: NOT NULL columns have sensible defaults
- [ ] Naming: Follows project naming conventions

-- エージェントによる改善提案
-- WARNING: avatar_url を WHERE 句で使用する予定がある場合、
-- インデックスの追加を推奨します
 
CREATE INDEX CONCURRENTLY idx_users_avatar_url
  ON "users" ("avatar_url")
  WHERE "avatar_url" IS NOT NULL;
 
-- CONCURRENTLY を使用することでテーブルロックを回避します

#!/usr/bin/env bash
# scripts/verify-migration.sh — エージェントに実行させる検証タスク
set -euo pipefail
 
SHADOW_URL="postgresql://postgres:test@localhost:5432/shadow_db"
: "${PROD_URL:?PROD_URL を設定してから実行してください}"
 
# 1. Shadow をまっさらにしてから、本番スキーマを複製（構造のみ）
#    前回の残骸が居座ると、差分ゼロの判定そのものが信用できなくなります
psql "$SHADOW_URL" -v ON_ERROR_STOP=1 \
  -c 'DROP SCHEMA public CASCADE; CREATE SCHEMA public;'
pg_dump --schema-only "$PROD_URL" | psql "$SHADOW_URL" -v ON_ERROR_STOP=1
 
# 2. 新しいマイグレーションを Shadow に適用
DATABASE_URL="$SHADOW_URL" npx prisma migrate deploy
 
# 3. スキーマとマイグレーションのずれ（ドリフト）を「終了コード」で判定する
#    --exit-code … 差分なし=0 / エラー=1 / 差分あり=2
rc=0
DATABASE_URL="$SHADOW_URL" npx prisma migrate diff \
  --exit-code \
  --from-schema prisma/schema.prisma \
  --to-config-datasource || rc=$?
 
case "$rc" in
  0)
    echo "✅ Shadow DB 検証を通過しました"
    ;;
  2)
    echo "❌ スキーマドリフトを検出しました。適用を中止します。"
    DATABASE_URL="$SHADOW_URL" npx prisma migrate diff \
      --from-schema prisma/schema.prisma \
      --to-config-datasource --script
    exit 1
    ;;
  *)
    echo "❌ 差分の取得そのものに失敗しました（exit=$rc）"
    exit 1
    ;;
esac

-- rollback/20260328_153000_remove_avatar_url.sql
 
-- Safety check: カラムにデータが存在するか確認
DO $$
DECLARE
  row_count INTEGER;
BEGIN
  SELECT COUNT(*) INTO row_count
  FROM "users"
  WHERE "avatar_url" IS NOT NULL;
 
  IF row_count > 0 THEN
    RAISE NOTICE '⚠ % rows have avatar_url data. Backing up...', row_count;
 
    -- バックアップテーブルに退避
    CREATE TABLE IF NOT EXISTS "_backup_users_avatar_url" AS
    SELECT id, avatar_url FROM "users" WHERE "avatar_url" IS NOT NULL;
  END IF;
END $$;
 
-- ロールバック実行
ALTER TABLE "users" DROP COLUMN IF EXISTS "avatar_url";
 
-- 期待される結果: avatar_url カラムが削除される
-- データが存在した場合は _backup_users_avatar_url に退避済み

# .github/workflows/migration-check.yml
name: Migration Safety Check
 
on:
  pull_request:
    paths:
      - "prisma/migrations/**"
      - "drizzle/**"
      - "src/db/schema.*"
 
jobs:
  migration-check:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: test
          POSTGRES_DB: test_db
        ports:
          - 5432:5432
 
    steps:
      - uses: actions/checkout@v4
 
      - name: Apply migrations to test DB
        env:
          DATABASE_URL: postgresql://postgres:test@localhost:5432/test_db
        run: |
          npx prisma migrate deploy
          echo "✅ Migrations applied successfully"
 
      - name: Verify rollback scripts exist
        run: |
          # 各マイグレーションに対応するロールバックがあるか確認
          for dir in prisma/migrations/*/; do
            migration_name=$(basename "$dir")
            if [ ! -f "rollback/${migration_name}_rollback.sql" ]; then
              echo "❌ Missing rollback for: $migration_name"
              exit 1
            fi
          done
          echo "✅ All rollback scripts present"