laravel-migrations

Laravel 13 のデータベースマイグレーションを網羅します。テーブルの作成・変更・削除を行う Schema Builder API、50 種類以上のカラム型と修飾子、インデックスの種類（primary、unique、fulltext、spatial）、カスケードオプション付きの外部キー制約、Artisan マイグレーションコマンド、シーダー、マイグレーションのテスト、本番環境への安全な適用、トラブルシューティング、およびベクトルカラムで pgvector を有効にする Schema::ensureVectorExtensionExists() を扱います（クエリ方法については laravel-vector-search を参照してください）。

Laravel のマイグレーション

エージェントのワークフロー（必須）

実装を始める前に、name を指定して Agent を 1 回ずつ呼び出し、3 つのエージェントを並列で起動してください。

1. fuse-ai-pilot:explore-codebase - 既存のマイグレーションを確認します
2. fuse-ai-pilot:research-expert - Context7 を使って Laravel 13 のパターンを検証します
3. mcp__context7__query-docs - Schema Builder の具体的な機能を確認します

実装後、検証のために fuse-ai-pilot:sniper を実行してください。

---

概要

機能	説明
Schema Builder	テーブルの作成、変更、削除
カラム	50 種類以上のカラム型と修飾子
インデックス	Primary、Unique、Fulltext、Spatial
外部キー	カスケードオプション付きの制約
シーダー	テーブルへのデータ投入

---

重要なルール

1. 必ず down() を定義する - ロールバック可能なマイグレーションにします
2. foreignId()->constrained() を使用する - 生の unsignedBigInteger は使用しません
3. 外部キーにインデックスを追加する - パフォーマンス上、重要です
4. デプロイ前にロールバックをテストする - down() が機能することを検証します
5. デプロイ済みのマイグレーションは変更しない - 新しいマイグレーションを作成します

---

選択ガイド

マイグレーションの種類

Need schema change?
├── New table → make:migration create_X_table
├── Add column → make:migration add_X_to_Y_table
├── Modify column → make:migration modify_X_in_Y_table
├── Add index → make:migration add_index_to_Y_table
└── Seed data → make:seeder XSeeder

カラム型の選択

用途	型	例
主キー	id()	自動インクリメント BIGINT
外部キー	foreignId()->constrained()	親テーブルを参照
UUID 主キー	uuid()->primary()	UUID
Boolean	boolean()	is_active
Enum	enum('status', [...])	order_status
JSON	json()	preferences
金額	decimal('price', 10, 2)	99999999.99
タイムスタンプ	timestamps()	created_at、updated_at
論理削除	softDeletes()	deleted_at

外部キーのカスケード

シナリオ	onDelete	用途
厳格な整合性	restrictOnDelete()	財務記録
自動クリーンアップ	cascadeOnDelete()	投稿 → コメント
NULL として保持	nullOnDelete()	任意のリレーション
何もしない	noActionOnDelete()	監査ログ

---

リファレンスガイド

基本概念

トピック	リファレンス	参照するタイミング
Schema	schema.md	テーブル操作
カラム	columns.md	カラム型
インデックス	indexes.md	パフォーマンス向上のためのインデックス
外部キー	foreign-keys.md	制約
コマンド	commands.md	Artisan コマンド
シーディング	seeding.md	データの投入

高度なトピック

トピック	リファレンス	参照するタイミング
テスト	testing.md	マイグレーションのテスト
本番環境	production.md	安全なデプロイ
トラブルシューティング	troubleshooting.md	エラーの解決

テンプレート

テンプレート	使用する場面
CreateTableMigration.php.md	新しいテーブル
ModifyTableMigration.php.md	テーブルの変更
PivotTableMigration.php.md	多対多
Seeder.php.md	シードパターン
MigrationTest.php.md	マイグレーションのテスト

---

クイックリファレンス

テーブルの作成

Schema::create('posts', function (Blueprint $table) {
    $table->id();
    $table->foreignId('user_id')->constrained()->cascadeOnDelete();
    $table->string('title');
    $table->text('content');
    $table->enum('status', ['draft', 'published'])->default('draft');
    $table->timestamps();
    $table->softDeletes();

    $table->index(['user_id', 'status']);
});

テーブルの変更

Schema::table('posts', function (Blueprint $table) {
    $table->string('slug')->after('title')->unique();
    $table->boolean('featured')->default(false);
});

コマンド

php artisan make:migration create_posts_table
php artisan migrate
php artisan migrate:rollback --step=1
php artisan migrate:fresh --seed

---

ベストプラクティス

実施すること

• 外部キーには foreignId()->constrained() を使用します
• よく使うクエリには複合インデックスを追加します
• デプロイ前に down() メソッドをテストします
• SQL のプレビューには --pretend を使用します

実施しないこと

• デプロイ済みのマイグレーションを変更しないでください
• down() メソッドを忘れないでください
• Schema Builder を使わずに生の SQL を使用しないでください
• 外部キーのインデックスを省略しないでください

---

Laravel 13 に関する注意事項

Schema::ensureVectorExtensionExists()（pgvector）

Laravel 13 では、マイグレーションから PostgreSQL の pgvector 拡張機能を有効にするヘルパーが利用できます。エンベディングやセマンティック検索に便利です。

use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::ensureVectorExtensionExists();

        Schema::create('documents', function (Blueprint $table) {
            $table->id();
            $table->text('content');
            $table->vector('embedding', dimensions: 1536)->index(); // OpenAI text-embedding-3-small; HNSW cosine vector index
            $table->timestamps();
            // equivalent: $table->vectorIndex('embedding'); — removal: dropVectorIndex() (13.30+)
        });
    }
};

vector カラム／インデックスは MariaDB 11.7+ でも動作します（拡張機能は不要です）。whereVectorSimilarTo() クエリについては [[laravel-vector-search]] を参照してください。

Schema Builder 13.x の新機能

• $table->foreignUuidFor(User::class)（13.9+）および foreignUlidFor()（13.25+）
• ロックフリーインデックス：$table->string('email')->unique()->online();（PostgreSQL ／ SQL Server）
• インデックスまたは外部キーの INPLACE DDL アルゴリズムに対応する ->inplace()（13.33+、MySQL）