マイグレーション作成パターン

このプロジェクトのデータベースマイグレーション実装パターンを定義します。

ディレクトリ構成

スキーマは db/schema/ に .hcl 形式で定義されている。db/migrations/ には master / master-mysql / view_master / view_master-mysql および sharding_1..4 / sharding_1..4-mysql など、環境別・用途別のマイグレーションがある。

db/schema/
├── master.hcl              # マスタースキーマ（.hcl）
├── master-mysql/          # マスター（MySQL向け .hcl）
│   └── master.hcl
├── sharding_1/ .. sharding_4/   # シャード別 .hcl（_schema.hcl + dm_*.hcl）
└── sharding_*_mysql/      # シャード別 MySQL 向け .hcl

db/migrations/
├── master/                 # マスターDB用
├── master-mysql/           # マスターDB用（MySQL）
├── view_master/            # ビュー用（マスター）
├── view_master-mysql/      # ビュー用（マスター・MySQL）
├── sharding_1/ .. sharding_4/   # シャーディングDB用
└── sharding_*_mysql/      # シャーディングDB用（MySQL）

マイグレーションツール

• Atlas CLI: マイグレーション管理
• SQLite: 開発環境のDB

参照ファイル

既存マイグレーション:

• db/migrations/master/ - マスターDBマイグレーション
• db/migrations/sharding_1/ - シャーディングDBマイグレーション例

スクリプト:

• scripts/migrate.sh - マイグレーション適用スクリプト

マイグレーション作成手順

1. 新しいマイグレーションファイルの作成

Atlas CLIで差分を生成。スキーマが .hcl の場合は --to に .hcl ファイルまたは .hcl があるディレクトリを指定する。

# マスターDB用（.hcl スキーマの場合）
atlas migrate diff {migration_name} \
    --dir "file://db/migrations/master" \
    --to "file://db/schema/master.hcl" \
    --dev-url "sqlite://file?mode=memory"

# マスターDB用（master-mysql ディレクトリの .hcl の場合）
atlas migrate diff {migration_name} \
    --dir "file://db/migrations/master-mysql" \
    --to "file://db/schema/master-mysql" \
    --dev-url "mysql://root:password@localhost:3306/dev"

# シャーディングDB用（.hcl スキーマの場合、4つ全てに適用）
for i in 1 2 3 4; do
    atlas migrate diff {migration_name} \
        --dir "file://db/migrations/sharding_$i" \
        --to "file://db/schema/sharding_$i" \
        --dev-url "sqlite://file?mode=memory"
done

# シャーディングDB用（MySQL の場合、4つ全てに適用）
for i in 1 2 3 4; do
    atlas migrate diff {migration_name} \
        --dir "file://db/migrations/sharding_${i}-mysql" \
        --to "file://db/schema/sharding_${i}_mysql" \
        --dev-url "mysql://root:password@localhost:3306/dev"
done

2. マイグレーションファイルの形式

ファイル名: {YYYYMMDDHHMMSS}_{description}.sql

例: 20251226074846_initial.sql

3. SQLite構文パターン

テーブル作成

-- Create "entities" table
CREATE TABLE `entities` (
  `id` integer NOT NULL PRIMARY KEY AUTOINCREMENT,
  `name` text NOT NULL,
  `created_at` datetime NOT NULL,
  `updated_at` datetime NOT NULL
);

シャーディングテーブル作成

シャーディングDBでは、テーブル名にサフィックスが付きます:

-- DB1: entities_000 ~ entities_007
-- DB2: entities_008 ~ entities_015
-- DB3: entities_016 ~ entities_023
-- DB4: entities_024 ~ entities_031

CREATE TABLE `users_000` (
  `id` integer NOT NULL,
  `name` text NOT NULL,
  `email` text NOT NULL,
  `created_at` datetime NOT NULL,
  `updated_at` datetime NOT NULL,
  PRIMARY KEY (`id`)
);
-- 同様に users_001 ~ users_007 を作成

インデックス作成

-- Create index "idx_entities_name" to table: "entities"
CREATE INDEX `idx_entities_name` ON `entities` (`name`);

カラム追加

-- Add column "description" to table: "entities"
ALTER TABLE `entities` ADD COLUMN `description` text NULL;

マイグレーション適用

# 全マイグレーション適用
./scripts/migrate.sh all

# マスターのみ
./scripts/migrate.sh master

# シャーディングのみ
./scripts/migrate.sh sharding

atlas.sum の更新

マイグレーションファイルを手動で編集した場合:

atlas migrate hash --dir "file://db/migrations/master"
atlas migrate hash --dir "file://db/migrations/sharding_1"
# ... sharding_2, 3, 4 も同様

注意事項

1. シャーディングDBは4つ全てに同じ変更を適用
2. テーブル名のサフィックスに注意 (_000 ~ _031)
3. SQLite構文を使用 (バッククォートでカラム名を囲む)
4. PRIMARY KEY AUTOINCREMENT はマスターDBのみ (シャーディングDBはアプリ側でID生成)