メシのタネ

メシのタネになる、AIや技術総合情報のサイト


Laravelマイグレーションのコマンド一覧|migrate・rollback・freshの違い


  1. Laravel
  2. Laravelマイグレーションのコマンド一覧|migrate・rollback・freshの違い

広告

Laravelのマイグレーションは、テーブルやカラムの変更をPHPファイルで管理する仕組みです。未適用の変更を実行するのは php artisan migrate。実行状況は migrate:status、直近のバッチを戻す操作は migrate:rollback です。データを削除する migrate:fresh との違いを押さえてから使い分けます。

操作コマンドと動作
未適用を実行php artisan migrate
状態を確認php artisan migrate:status
SQLを確認php artisan migrate --pretend
直近のバッチを戻すphp artisan migrate:rollback
直近1ファイルを戻すphp artisan migrate:rollback --step=1
全テーブルを削除して再構築php artisan migrate:fresh --seed
本番環境の確認プロンプトを省略php artisan migrate --force

--force は実行確認を省略するオプションです。変更の安全性を確認する機能は持ちません。fresh は接続先の全テーブルを削除するため、データを残す環境では実行前に対象とバックアップを確認してください。

はじめに ― Laravelのmigrationってなにするの?

マイグレーションファイルをGitで共有し、各環境で同じスキーマ変更を適用します。migrate を実行すると、未適用のファイルが順に処理されます。down() で構造を戻せても、削除したデータが復元されるとは限りません。

  1. 差分管理 ― 変更履歴が Git に残る
  2. 巻き戻し down() に定義した操作を実行する。直近1ファイルなら migrate:rollback --step=1 を指定する
  3. テストとの親和性 ― テスト前に migrate:fresh すれば毎回クリーンな DB

3 行で動く最小サンプル

php artisan make:migration create_posts_table
php artisan migrate
php artisan migrate:rollback

マイグレーションの作法 ― コマンドを「使う順」で覚える

前章の 3 行サンプル で posts テーブルを作ったあなたが、次に踏むべきステップを「作る → 試す → 壊す → また作る」の順でまとめる。コマンド名を丸暗記するより ストーリー で覚えるとミスが減る。

作成 — 雛形を切る

変更用マイグレーションのクラスファイルを生成する。

# posts テーブルに status カラムを追加する雛形
php artisan make:migration add_status_to_posts --table=posts

適用 / 戻す — 反映・検証

マイグレーションを実際に流してアプリを動かし、問題があればすぐ巻き戻す。

# 未適用の変更を実行
php artisan migrate

# 適用状況を確認
php artisan migrate:status

# 直近のマイグレーションを1ファイル戻す
php artisan migrate:rollback --step=1

Tip: --pretend フラグを付ければ、実行される SQL だけを表示して安全確認できる。

作り直し — リセット / 一括実行

ローカル環境や CI で DB をまっさら状態から再構築したいときに便利。

# 全マイグレーションをやり直し & seeder を流す
php artisan migrate:refresh --seed

# すべての down() を実行して初期状態へ戻す
php artisan migrate:reset

マイグレーションは コードの一部。小さく回して「作る → 試す → 壊す」を高速で繰り返せば、想定外のバグも rollback と Git で即リカバーできる。

Migration コマンド早見表(チートシート)

# ファイルを生成する
php artisan make:migration create_tasks_table --create=tasks

# 状態とSQLを確認して適用する
php artisan migrate:status
php artisan migrate --pretend
php artisan migrate

# 直近1ファイルを戻す
php artisan migrate:rollback --step=1

# 本番で対話確認を省略する場合。事前に対象・変更内容を確認する
php artisan migrate --force

# 全テーブル削除を伴うため、再構築できる開発・テストDB向け
php artisan migrate:fresh --seed

# スキーマダンプを生成する
php artisan schema:dump

スキーマ定義のツボ ― 型・インデックス早見表 + 失敗例

カラム属性早見表

メソッド / 型例目的一言メモ
bigIncrements('id')符号なし 64‑bit 主キー自動採番の主キー。複数DBで書き込む場合の衝突対策は別に設計する
uuid('id')UUID 主キーマルチ DB で被りにくい
string('title', 150)可変長文字列191 文字以下なら古い MySQL でも index 可能
text('body')長文通常の索引や全文検索の対応・制限はDBとインデックス方式による
boolean('is_published')->default(false)真偽値 + デフォルトTINYINT(1) 扱いなので注意
decimal('price', 8, 2)固定小数金額計算は decimal 一択。float は誤差が出る
enum('status', ['draft','published'])列挙型指定した候補の値を取るカラム。実際の型や制約の生成方法はDBドライバーによって異なる
timestamps()created_at / updated_atnullableTimestamps() も選択可
softDeletes()deleted_at ソフト削除withTrashed() で取得可能

インデックス・制約早見表

メソッド / 型例目的一言メモ
foreignId('user_id')->constrained()外部キー + インデックスconstrained() で users.id を推測
index(['a', 'b'])複合インデックスカーディナリティの高い列を先頭に
unique('email')一意制約NULL を許すかは DB ごとに挙動が違う
fullText(['title','body'])全文検索インデックスMySQL 5.7+ / InnoDB 限定
spatialIndex('location')GIS インデックスpoint, polygon など地理情報向け

NG 例:nullable FK と順序ミス

$table->foreignId('user_id')->nullable();
$table->foreign('user_id')->references('id')->on('users');

nullable() を指定すると 外部キー制約違反が起きにくい が、参照整合性が崩れやすい。実運用では SET NULL / CASCADE の onDelete を明示するか、NOT NULL + デフォルト値を検討しよう。

テーブル変更を安全に運用するコツ

そもそも「テーブルを変える」とは?

  • 追加: 新しいカラムやインデックスを足す
  • 変更: 既存カラムの型・長さ・NULL 制約を変える
  • 削除: 不要になったカラム・インデックスを落とす

Laravel のスキーマビルダには addColumn()・dropColumn()・renameColumn() など多数あるが、型や制約を直接変更するメソッドが change()。便利だが、裏では ALTER TABLE ... MODIFY が実行される。

MySQL 5.7 以前や Aurora MySQL では ALTER TABLE が全行ロックを取得することがあり、巨大テーブルでは 数十秒〜数分サービスが停止 するリスクがある。

操作例MySQL / MariaDBPostgreSQL備考
新しい nullable カラムを追加非ロック(即時適用)非ロック比較的安全
非 NULL カラムを追加 (default 無し)全行バックフィルテーブルリライトデフォルト値を付けて後で alter が安全
varchar(100) → varchar(255)全行コピーメタデータ変更のみMySQL は行コピーが走る
INT → BIGINTテーブルコピーテーブルリライト書込み停止時間が長い
カラム削除 / 変更テーブルコピーテーブルリライト最もロック時間が長い

Laravel 12 で使えるスキーマダンプと条件付き実行

php artisan schema:dump --prune ― Migration を SQL スナップショット化

schema:dump --prune は 「過去のマイグレーション > 1 本の SQL」 にまとめるコマンド。差分を整理できる一方、いくつか副作用もある。

何が起きる?

  • 現在の DB スキーマを database/schema/*.sql にダンプ。
  • database/migrations/*.php から実行済みファイルを削除(--prune)。
  • 以後 php artisan migrate は ① スナップショット → ② 残りの未実行マイグレーション の順に適用。

メリット

  1. 初期構築が速い — CI で migrate が数十秒→数秒になる。
  2. ファイル数が減る — 100 本以上の古いファイルを整理できる。
  3. Git で差分が追いやすい — 大量の自動生成ファイルをレビューせずに済む。

🚨 副作用・注意点

項目内容回避策
ロールバック不可ダンプより前の状態へ migrate:rollback できない古いブランチが必要なら dump 前に残すか、タグを切る
旧マイグレーションが HEAD から削除される順序や経緯を git log で辿る手間が増える(履歴コミットには残る)dump 前にタグを切る・Wiki/ADR に経緯を記録
dump ファイルが肥大化大規模 DB ではダンプ SQL が数 MB〜数十 MB。差分 1 行でも 巨大ファイル全体が変更扱い となり Git でコンフリクトしやすいdump は 最後に 1 人がまとめて実行 する / PR 前に schema:dump を再実行して衝突を解消 / テーブル単位に分割ダンプする
関数・トリガ・ビューDB により一部含まれない場合あり追加で after_dump.sql などに手動記述
DB ごとの差分MySQL と SQLite で SQL 方言が違うテスト用接続ごとに --database で個別ダンプ

推奨手順

# 開発環境で、接続先とマイグレーション適用状況を確認して実行
php artisan migrate:status
php artisan schema:dump

# テスト用の接続にもダンプを生成する場合
php artisan schema:dump --database=testing

# --pruneは既存のマイグレーションファイルを削除する
# ダンプから再構築できることを別の開発DBで確かめてから使用する
  1. ダンプ後は 必ずコミット。CI・本番で同じファイルを使う。
  2. 新しいマイグレーションを追加したら、定期的に再度 schema:dump --prune でクリーンアップ。

shouldRun() で機能フラグ付き Migration. shouldRun() で機能フラグ付き Migration

  • Laravel 12のMigrationには shouldRun(): bool を定義でき、falseを返すとそのマイグレーションがスキップされます。Pennantを使う場合は、パッケージの導入と機能フラグの定義が必要です。
use Laravel\Pennant\Feature;
use App\Features\Bookings;

public function shouldRun(): bool
{
    // 機能フラグが ON なら走らせる
    return Feature::active(Bookings::class);
}

テスト連携の基本

  • use RefreshDatabase; でテストごとにトランザクション → ロールバック
  • schema:dump をコミットしておけば migrate:freshが一瞬で完了。CI のタイムアウトに怯えない。
  • Faker でダミーデータ → Factory / Seeder を使い回し、E2E でも同じシナリオを共有。

→ Faker活用ライトガイド – “それっぽい” ダミーデータを 5 秒で錬成する

よくあるエラーと速攻対処集

Laravel + MySQL で初心者がつまずきやすい代表的なエラーを「症状 → 原因 → 対処」の順でまとめました。順位やランキングではなく、遭遇頻度が高いものから順に並べています。

1071 Key too long — インデックス長オーバー

症状: index() や unique() を貼った文字列カラムで発生。

原因: utf8mb4 4 バイト文字 × 長い文字数で、インデックス長が MySQL の 767 バイト制限を超過。

対処コード例

// ① フレームワーク全体でデフォルト長を狭める
Schema::defaultStringLength(191);

// ② またはカラム長を縮める
$table->string('email', 191)->unique();

Unknown collation utf8mb4_0900_ai_ci — Collation 非対応

旧版MySQLを使う環境では、utf8mb4の索引サイズ制限が問題になることがあります。Laravel 12で使うDBは公式のサポート対象バージョンを確認し、古い環境向けの回避策をそのまま適用しないようにしてください。

原因: utf8mb4_0900_ai_ci は MySQL 8.0 用。古いバージョンは理解できない。

対処例

# .env
DB_COLLATION=utf8mb4_general_ci

またはマイグレーションで明示的に collation() を指定。

Cannot drop column 'x' used by a view — View が依存

症状: カラム変更や削除時にエラー。

原因: そのカラムを参照する View が存在し、MySQL が整合性を守るため拒否。

対処手順

  1. 依存している View を DROP VIEW または再定義。
  2. マイグレーションでカラムを削除。
  3. 必要なら View を再作成。

Foreign key constraint fails — 外部キー制約違反

症状: レコード挿入・削除・更新時に制約エラー。

原因: 親レコードが無い(孤児)/子テーブルが参照中など整合性が崩壊。

対処例

// まず不整合のある行を確認する
SELECT comments.*
FROM comments
LEFT JOIN posts ON posts.id = comments.post_id
WHERE posts.id IS NULL;

// 原因と対象を確認したうえで、データ修正と制約追加を計画する

Syntax error in SQL generated by Doctrine — 複雑な change()

症状: change() で型や制約を複数同時に変更すると発生しやすい。

これはDoctrine DBALを使ってカラム変更する旧構成での確認例です。現在のLaravelで同じ依存関係を前提にせず、使用中のLaravel・DBのバージョンと、生成されるALTER文を確認します。

対処の鉄則

// 既存カラムを変更する場合はchange()を使う
// 維持したいnullableやdefaultなどの属性も指定する
Schema::table('users', function (Blueprint $table) {
    $table->string('name', 200)->nullable()->change();
});

// dropColumn()して作り直すと、既存のカラム値は失われる

まとめ

ここまでで Laravel マイグレーションの基本操作から安全なスキーマ変更、テスト連携までひと通り眺めました。この記事が最初の一歩を踏み出す助けになれば幸いです!

2026年11月18日に内容を確認。参考にした公式資料は Laravelのマイグレーション。


コメントを残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

このサイトはスパムを低減するために Akismet を使っています。コメントデータの処理方法の詳細はこちらをご覧ください。