What is migration-helper?

The migration-helper skill is a specialized tool designed to automate and streamline database migration workflows using Atlas CLI and SQLite. It excels at managing complex schema changes across both master and sharded database architectures, ensuring that SQL migrations are generated consistently and accurately. By providing predefined patterns for table creation, indexing, and column modifications, it minimizes manual errors and maintains database integrity through automated checksum management.

When should I use migration-helper?

migration-helper is useful in the following scenarios: • Generating timestamped SQL migration files for master and sharded databases (sharding_1 to sharding_4) using Atlas CLI diff commands. • Synchronizing schema updates across multiple database shards to ensure architectural consistency in distributed environments. • Creating SQLite-compatible SQL scripts for new tables and indexes while adhering to specific naming conventions and syntax requirements. • Automating the update of atlas.sum hash files to maintain migration history integrity after manual script adjustments. • Executing batch migration scripts to apply changes across different database environments (master, sharding, or all) with a single command.

name	migration-helper
description	データベースマイグレーションを作成する際に使用。Atlas CLI使用、master/shardingのマイグレーション、SQLite構文。DB変更、テーブル追加、カラム追加、マイグレーションファイル作成時に使用。
allowed-tools	Read, Bash(atlas:), Bash(./scripts/migrate.sh:)

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

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

ディレクトリ構成

db/migrations/
├── master/           # マスターDB用（news, goadminテーブル等）
│   ├── atlas.sum
│   └── *.sql
├── sharding_1/       # シャーディングDB 1用
├── sharding_2/       # シャーディングDB 2用
├── sharding_3/       # シャーディングDB 3用
└── sharding_4/       # シャーディングDB 4用

マイグレーションツール

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

参照ファイル

既存マイグレーション:

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

スクリプト:

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

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

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

Atlas CLIで差分を生成:

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

# シャーディングDB用（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.sql" \
        --dev-url "sqlite://file?mode=memory"
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 も同様

注意事項

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

migration-helper

When & Why to Use This Skill

Use Cases