Laravelのテーブル作成と定義変更｜マイグレーション・up/down・注意点

Laravelのデータベースマイグレーションという機能を使用すればphpファイル上でテーブル定義をすることが出来ます。

元のコードは旧Laravelの手順として残し、下にLaravel 13の定義例を分けて掲載しています。 マイグレーションは実DBの構造を変える操作です。学習用の隔離環境で確認し、既存システムでは運用規則・バックアップ・承認された変更手順を優先してください。コマンドを読んだだけで本番へ実行しないでください。

マイグレーションファイルの作成

Laravelプロジェクトのルートディレクトリで以下のコマンドを実行すると、マイグレーションファイルを作成することが出来ます。

以下、実行例です。

マイグレーションファイルは「database/migrations」に格納されます。

テーブルの作成

先ほど作成したマイグレーションファイルの中身を見てみましょう。

「database\migrations」配下にファイルが新規作成されたことを確認できます。

ファイルの中身を見てみましょう。

テーブルの作成が完了します。

テーブル定義の変更

tasksテーブルにカラムの追加、変更をしてみましょう。

以下の例ではstring型のnameというカラムを追加しています。

更にidのデータ型を変更する旧例です。主キーの型を変える場合は、参照する外部キーの型・符号・既存データ・インデックスと変更順を確認します。単に容量を増やす目的で、下の例を既存テーブルへ無条件に適用しないでください

upは変更を進める処理、downはその変更を戻す処理です。新規テーブル作成のdownはテーブル削除になり得ますが、カラム変更のdownは元の定義への変更など、upの内容に対応して設計します。downを単なる削除処理とは扱いません。

ファイルを書き換えただけではテーブルの構造は変化しません。

ファイルを保存して以下のコマンドを実行しましょう。

以下のエラーが発生した場合はこちらを参照。

新規作成と既存テーブル変更を分ける

未適用のマイグレーションが実行対象です。既に適用したファイルを書き換えて再実行すれば、その差分が自動で反映されるという仕組みではありません。共有環境で適用済みの履歴を改変せず、新しい変更ファイルを作り、対象環境の適用状態を確認します。

変更前の読み取り確認

以下はMySQLの確認SQLです。example_tasksは以下の独立例のテーブル名で、既存DBでは実際の対象へ合わせます。最初の例をまだ作成していなければこのテーブルはありません。

SHOW CREATE TABLE example_tasks;
SHOW INDEX FROM example_tasks;
SELECT COUNT(*) AS row_count, MAX(CHAR_LENGTH(name)) AS longest_name
FROM example_tasks;

NULL/DEFAULT/コメント、主キー・外部キー、既存の長さやNULL値を確認します。大きなテーブルの全件集計は負荷も考え、検証用コピーなど運用に適した場所で実行してください。バックアップは取得だけでなく復元可能かも確認します。

Laravel 13の独立した定義例

以下は別々のマイグレーションファイルです。最初にexample_tasksを作り、次の変更でnameの長さを100から150へ広げます。元のtasks例へ途中だけ貼り付けるものではありません。ここではPHP 8.5 / Laravel 13のMySQL生成SQLを確認しました。実DBへのDDL実行はしていません。

新規作成ファイル

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::create('example_tasks', function (Blueprint $table) {
            $table->id();
            $table->string('name', 100)->nullable()->default(null)->comment('Task name');
            $table->timestamps();
        });
    }

    public function down(): void
    {
        Schema::dropIfExists('example_tasks');
    }
};

既存カラム変更ファイル

<?php

use Illuminate\Database\Migrations\Migration;
use Illuminate\Database\Schema\Blueprint;
use Illuminate\Support\Facades\Schema;

return new class extends Migration {
    public function up(): void
    {
        Schema::table('example_tasks', function (Blueprint $table) {
            $table->string('name', 150)->nullable()->default(null)->comment('Task name')->change();
        });
    }

    public function down(): void
    {
        Schema::table('example_tasks', function (Blueprint $table) {
            $table->string('name', 100)->nullable()->default(null)->comment('Task name')->change();
        });
    }
};

id()はLaravel 13ではbigIncrements相当です。旧例のincrementsはunsigned INT、こちらはunsigned BIGINTなので、既存の関連テーブルと型が合うか確認します。nameのchangeではnullable・default・commentを明示しています。定義変更時に保持したい属性は再指定し、インデックスは別途確認します。

属性を省略するとどうなるか

今回、保持属性を付けた例は次のSQLを生成しました。

alter table `example_tasks` modify `name` varchar(150) null comment 'Task name'

対してstring(name, 150)->change()だけでは、次のようにNOT NULLになり、コメント指定もなくなりました。これは生成SQLの比較であり、すべてのDB製品・Laravel版に同じ構文が出る保証ではありません。

alter table `example_tasks` modify `name` varchar(150) not null

rollbackとデータ復元は別

migrate:rollbackは通常、最後のバッチを戻すため、複数ファイルが対象になり得ます。対象ファイル・バッチ・downの内容を確認してください。テーブルをdropしたdownは保存済みの行を失い、後でupを実行しても元の行は戻りません。

上の変更例のdownは150から100へ縮めます。101文字以上の値があれば、そのまま戻せるとは限りません。事前に既存値を調べ、縮小で失敗・切詰め・データ損失が起きないか検証し、安全に戻せない場合の復旧方針を決めます。DDLを一律にトランザクションで取り消せる前提にも立ちません。

変更後の確認

• 生成SQLと実行対象、変更後のSHOW CREATE TABLEを比較する。
• 既存行数・値・NULL/DEFAULT・コメント・制約と、アプリの読込/保存を確認する。
• 主キー変更なら関連テーブルの参照整合性も確認する。
• ロック・実行時間・失敗時の状態と、バックアップからの復旧手順を検証する。

今回のテストは掲載した2ファイルのup/downのSQL生成と、属性省略の比較です。DBへ接続しようとすると失敗させるテスト接続で検証し、artisan migrateは実行していません。実データを使う変更・rollback・ロック時間は未検証です。

公式資料: Laravel 13のマイグレーション・カラム変更・rollback（2026年10月確認）。