Laravel 7.x データベース：マイグレーション

イントロダクションIntroduction

マイグレーションとはデータベースのバージョンコントロールのような機能です。アプリケーションデータベースのスキーマの更新をチームで共有できるようにしてくれます。マイグレーションは基本的にLaravelのスキーマビルダと一緒に使い、アプリケーションのデータベーススキーマを作成するために使用します。もしあなたが今まで、チームメイトに彼らのローカルデータベーススキーマに手作業でカラムを追加するよう依頼したことがあるなら、データベースマイグレーションは、そうした問題を解決してくれます。Migrations are like version control for your database, allowing your team to modify and share the application's database schema. Migrations are typically paired with Laravel's schema builder to build your application's database schema. If you have ever had to tell a teammate to manually add a column to their local database schema, you've faced the problem that database migrations solve.

LaravelのSchemaファサードは、テーブルの作成や操作をサポートしてるデータベースシステム全部に対しサポートします。The Laravel Schema facade[/docs/{{version}}/facades] provides database agnostic support for creating and manipulating tables across all of Laravel's supported database systems.

マイグレーション生成Generating Migrations

make:migration Artisanコマンドを使いマイグレーションを生成できます。To create a migration, use the make:migration Artisan command[/docs/{{version}}/artisan]:

php artisan make:migration create_users_table

マイグレーションはdatabase/migrationsフォルダに設置されます。マイグレーションの実行順をフレームワークに知らせるため、名前にタイムスタンプが含まれています。The new migration will be placed in your database/migrations directory. Each migration file name contains a timestamp, which allows Laravel to determine the order of the migrations.

lightbulb">Tip!! Migration stubs may be customized using stub publishing{tip} Migration stubs may be customized using stub publishing[/docs/{{version}}/artisan#stub-customization]

--tableと--createオプションも、テーブル名とマイグレーションで新しいテーブルを生成するかを指定するために使用できます。これらのオプションは生成するマイグレーションスタブの中へ指定したテーブルをあらかじめ埋め込みます。The --table and --create options may also be used to indicate the name of the table and whether or not the migration will be creating a new table. These options pre-fill the generated migration stub file with the specified table:

php artisan make:migration create_users_table --create=users

php artisan make:migration add_votes_to_users_table --table=users

マイグレーションの生成出力先のパスを指定したい場合は、make:migrateコマンドの実行時に--pathオプションを付けてください。パスはアプリケーションのベースパスからの相対位置です。If you would like to specify a custom output path for the generated migration, you may use the --path option when executing the make:migration command. The given path should be relative to your application's base path.

マイグレーション構造Migration Structure

マイグレーションはupとdownの２メソッドを含んでいます。upメソッドは新しいテーブル、カラム、インデックスをデータベースへ追加するために使用し、一方のdownメソッドはupメソッドが行った操作を元に戻します。A migration class contains two methods: up and down. The up method is used to add new tables, columns, or indexes to your database, while the down method should reverse the operations performed by the up method.

両方のメソッドでは、記述的にテーブルを作成したり、変更したりできるLaravelスキーマビルダが使えます。Schemaビルダで使用できる全メソッドは、このドキュメント後半で確認してください。たとえば、次のマイグレーションはflightsテーブルを作成します。Within both of these methods you may use the Laravel schema builder to expressively create and modify tables. To learn about all of the methods available on the Schema builder, check out its documentation[#creating-tables]. For example, the following migration creates a flights table:

<?php

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

class CreateFlightsTable extends Migration
{
    /**
     * マイグレーション実行
     *
     * @return void
     */
    public function up()
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->string('name');
            $table->string('airline');
            $table->timestamps();
        });
    }

    /**
     * マイグレーションを元に戻す
     *
     * @return void
     */
    public function down()
    {
        Schema::drop('flights');
    }
}

マイグレーション実行Running Migrations

アプリケーションで用意したマイグレーションを全部実行するには、migrate Artisanコマンドを使用します。To run all of your outstanding migrations, execute the migrate Artisan command:

php artisan migrate

Note: note Homestead仮想マシンを使用している場合、このコマンドは仮想マシン内で実行してください。{note} If you are using the Homestead virtual machine[/docs/{{version}}/homestead], you should run this command from within your virtual machine.

実働環境でのマイグレーション強制Forcing Migrations To Run In Production

いくつかのマイグレーション操作は破壊的です。つまりデーターを失う可能性があります。実働環境(production)のデータベースに対し、こうしたコマンドが実行されることから保護するために、コマンド実行前に確認のプロンプトが表示されます。コマンド実行時のプロンプトを出さないためには、--forceフラグを指定してください。Some migration operations are destructive, which means they may cause you to lose data. In order to protect you from running these commands against your production database, you will be prompted for confirmation before the commands are executed. To force the commands to run without a prompt, use the --force flag:

php artisan migrate --force

ロールバックRolling Back Migrations

最後のマイグレーション操作をロールバックしたい場合は、rollbackコマンドを使います。このロールバックは、「同時に」実行した最後のマイグレーションをまとめて元に戻します。To roll back the latest migration operation, you may use the rollback command. This command rolls back the last "batch" of migrations, which may include multiple migration files:

php artisan migrate:rollback

rollbackコマンドにstepオプションを付けると、巻き戻す数を限定できます。たとえば、次のコマンドは最後の5マイグレーションをロールバックします。You may roll back a limited number of migrations by providing the step option to the rollback command. For example, the following command will roll back the last five migrations:

php artisan migrate:rollback --step=5

migrate:resetコマンドはアプリケーション全部のマイグレーションをロールバックします。The migrate:reset command will roll back all of your application's migrations:

php artisan migrate:reset

rollbackとmigrateの１コマンド実行Roll Back & Migrate Using A Single Command

migrate:refreshコマンドは全部のデータベースマイグレーションを最初にロールバックし、それからmigrateコマンドを実行します。このコマンドはデータベース全体を作り直すために便利です。The migrate:refresh command will roll back all of your migrations and then execute the migrate command. This command effectively re-creates your entire database:

php artisan migrate:refresh

// データベースをリフレッシュし、全データベースシードを実行
php artisan migrate:refresh --seed

refreshコマンドにstepオプションを付けると、巻き戻してからマイグレーションを再実行する数を限定できます。たとえば、次のコマンドは最後の5マイグレーションをロールバック後にマイグレートします。You may roll back & re-migrate a limited number of migrations by providing the step option to the refresh command. For example, the following command will roll back & re-migrate the last five migrations:

php artisan migrate:refresh --step=5

全テーブル削除後のマイグレーションDrop All Tables & Migrate

migrate:freshコマンドは、データベースから全テーブルをドロップします。次に、migrateコマンドを実行してください。The migrate:fresh command will drop all tables from the database and then execute the migrate command:

php artisan migrate:fresh

php artisan migrate:fresh --seed

テーブルTables

テーブル作成Creating Tables

新しいデータベーステーブルを作成するには、Schemaファサードのcreateメソッドを使用します。createメソッドは引数を２つ取ります。最初はテーブルの名前で、２つ目は新しいテーブルを定義するために使用するBlueprintオブジェクトを受け取る「クロージャ」です。To create a new database table, use the create method on the Schema facade. The create method accepts two arguments: the first is the name of the table, while the second is a Closure which receives a Blueprint object that may be used to define the new table:

Schema::create('users', function (Blueprint $table) {
    $table->id();
});

テーブル作成時には、テーブルのカラムを定義するためにスキーマビルダのカラムメソッドをどれでも利用できます。When creating the table, you may use any of the schema builder's column methods[#creating-columns] to define the table's columns.

テーブル／カラムの存在チェックChecking For Table / Column Existence

hasTableやhasColumnメソッドを使えば、テーブルやカラムの存在をチェックできます。You may check for the existence of a table or column using the hasTable and hasColumn methods:

if (Schema::hasTable('users')) {
    //
}

if (Schema::hasColumn('users', 'email')) {
    //
}

データベース接続とテーブル操作Database Connection & Table Options

デフォルト接続以外のデータベース接続でスキーマ操作を行いたい場合は、connectionメソッドを使ってください。If you want to perform a schema operation on a database connection that is not your default connection, use the connection method:

Schema::connection('foo')->create('users', function (Blueprint $table) {
    $table->id();
});

テーブルのオプションを定義するため、以下のコマンドがスキーマビルダで使用できます。You may use the following commands on the schema builder to define the table's options:

テーブルリネーム／削除Renaming / Dropping Tables

既存のデータベーステーブルの名前を変えたい場合は、renameメソッドを使います。To rename an existing database table, use the rename method:

Schema::rename($from, $to);

存在するテーブルを削除する場合は、dropかdropIfExistsメソッドを使います。To drop an existing table, you may use the drop or dropIfExists methods:

Schema::drop('users');

Schema::dropIfExists('users');

外部キーを持つテーブルのリネームRenaming Tables With Foreign Keys

テーブルのリネームを行う前に、Laravelの規約に基づいた名前の代わりに、マイグレーションファイル中で独自の名前付けた外部キー制約が存在していないか確認してください。そうしないと、外部キー制約名は古いテーブル名を参照してしまいます。Before renaming a table, you should verify that any foreign key constraints on the table have an explicit name in your migration files instead of letting Laravel assign a convention based name. Otherwise, the foreign key constraint name will refer to the old table name.

カラムColumns

カラム作成Creating Columns

存在するテーブルを更新するには、Schemaファサードのtableメソッドを使います。createメソッドと同様に、tableメソッドは２つの引数を取ります。テーブルの名前と、テーブルにカラムを追加するために使用するBlueprintインスタンスを受け取る「クロージャ」です。The table method on the Schema facade may be used to update existing tables. Like the create method, the table method accepts two arguments: the name of the table and a Closure that receives a Blueprint instance you may use to add columns to the table:

Schema::table('users', function (Blueprint $table) {
    $table->string('email');
});

使用できるカラムタイプAvailable Column Types

スキーマビルダは、テーブルを構築する時に使用するさまざまなカラムタイプを持っています。The schema builder contains a variety of column types that you may specify when building your tables:

カラム修飾子Column Modifiers

上記のカラムタイプに付け加え、カラムを追加するときに使用できるさまざまな修飾子もあります。たとえばカラムを「NULL値設定可能(nullable)」にしたい場合は、nullableメソッドを使います。In addition to the column types listed above, there are several column "modifiers" you may use while adding a column to a database table. For example, to make the column "nullable", you may use the nullable method:

Schema::table('users', function (Blueprint $table) {
    $table->string('email')->nullable();
});

下表が使用可能なカラム修飾子の一覧です。インデックス修飾子は含まれていません。The following list contains all available column modifiers. This list does not include the index modifiers[#creating-indexes]:

デフォルトExpressionDefault Expressions

default修飾子は、値か\Illuminate\Database\Query\Expressionインスタンスを引数に取ります。Expressionインスタンスを使えば値をクオートしなくて済みますし、データベース特有の機能を使うこともできます。デフォルト値をJSONカラムに割り付ける必要があるとき、とくに便利です。The default modifier accepts a value or an \Illuminate\Database\Query\Expression instance. Using an Expression instance will prevent wrapping the value in quotes and allow you to use database specific functions. One situation where this is particularly useful is when you need to assign default values to JSON columns:

<?php

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

class CreateFlightsTable extends Migration
{
    /**
     * マイグレーション実行
     *
     * @return void
     */
    public function up()
    {
        Schema::create('flights', function (Blueprint $table) {
            $table->id();
            $table->json('movies')->default(new Expression('(JSON_ARRAY())'));
            $table->timestamps();
        });
    }
}

Note: note デフォルトExpressionのサポートはデータベースドライバ、データベースバージョン、フィールドタイプによります。互換性に関する適切なドキュメントを参照してください。また、データベース固有機能の使用は、特定のドライバーに強く結びついてしまうことにも注意してください。{note} Support for default expressions depends on your database driver, database version, and the field type. Please refer to the appropriate documentation for compatibility. Also note that using database specific functions may tightly couple you to a specific driver.

カラム変更Modifying Columns

動作要件Prerequisites

カラムを変更する前に、composer.jsonファイルでdoctrine/dbalを確実に追加してください。Doctrine DBALライブラリーは現在のカラムの状態を決め、必要な調整を行うSQLクエリを生成するために、使用しています。Before modifying a column, be sure to add the doctrine/dbal dependency to your composer.json file. The Doctrine DBAL library is used to determine the current state of the column and create the SQL queries needed to make the required adjustments:

composer require doctrine/dbal

カラム属性の変更Updating Column Attributes

changeメソッドは存在するカラムのタイプと属性を更新します。たとえばstringカラムの文字長を増やしたい場合です。changeの実例を見てもらうため、nameカラムのサイズを25から50へ増やしてみます。The change method allows you to modify type and attributes of existing columns. For example, you may wish to increase the size of a string column. To see the change method in action, let's increase the size of the name column from 25 to 50:

Schema::table('users', function (Blueprint $table) {
    $table->string('name', 50)->change();
});

さらにカラムをNULL値設定可能にしてみましょう。We could also modify a column to be nullable:

Schema::table('users', function (Blueprint $table) {
    $table->string('name', 50)->nullable()->change();
});

Note: note 以降のカラムタイプのみ変更可能です：bigInteger、binary、boolean、date、dateTime、dateTimeTz、decimal、integer、json、longText、mediumText、smallInteger、string、text、time、unsignedBigInteger、unsignedInteger、unsignedSmallInteger、uuid{note} Only the following column types can be "changed": bigInteger, binary, boolean, date, dateTime, dateTimeTz, decimal, integer, json, longText, mediumText, smallInteger, string, text, time, unsignedBigInteger, unsignedInteger, unsignedSmallInteger and uuid.

カラム名変更Renaming Columns

カラム名を変更するには、renameColumnメソッドをスキーマビルダで使用してください。カラム名を変更する前に、composer.jsonファイルでdoctrine/dbalを依存パッケージとして追加してください。To rename a column, you may use the renameColumn method on the schema builder. Before renaming a column, be sure to add the doctrine/dbal dependency to your composer.json file:

Schema::table('users', function (Blueprint $table) {
    $table->renameColumn('from', 'to');
});

Note: note カラムタイプがenumのテーブル中のカラム名変更は、現在サポートしていません。{note} Renaming any column in a table that also has a column of type enum is not currently supported.

カラム削除Dropping Columns

カラムをドロップするには、スキーマビルダのdropColumnメソッドを使用します。SQLiteデータベースからカラムをドロップする場合は、事前にcomposer.jsonファイルへdoctrine/dbal依存パッケージを追加してください。その後にライブラリーをインストールするため、ターミナルでcomposer updateを実行してください。To drop a column, use the dropColumn method on the schema builder. Before dropping columns from a SQLite database, you will need to add the doctrine/dbal dependency to your composer.json file and run the composer update command in your terminal to install the library:

Schema::table('users', function (Blueprint $table) {
    $table->dropColumn('votes');
});

dropColumnメソッドにカラム名の配列を渡せば、テーブルから複数のカラムをドロップできます。You may drop multiple columns from a table by passing an array of column names to the dropColumn method:

Schema::table('users', function (Blueprint $table) {
    $table->dropColumn(['votes', 'avatar', 'location']);
});

Note: note SQLite使用時に、一つのマイグレーションによる複数カラム削除／変更はサポートされていません。{note} Dropping or modifying multiple columns within a single migration while using a SQLite database is not supported.

利用可能な別名コマンドAvailable Command Aliases

インデックスIndexes

インデックス作成Creating Indexes

Laravelのスキーマビルダはさまざまなインデックスタイプをサポートしています。以下の例は新しくemailカラムを作成し、その値を一意に指定しています。インデックスを作成するには、カラム定義にuniqueメソッドをチェーンで付け加えます。The Laravel schema builder supports several types of indexes. The following example creates a new email column and specifies that its values should be unique. To create the index, we can chain the unique method onto the column definition:

$table->string('email')->unique();

もしくはカラム定義の後でインデックスを作成することも可能です。例を見てください。Alternatively, you may create the index after defining the column. For example:

$table->unique('email');

インデックスメソッドにカラムの配列を渡し、複合インデックスを作成することもできます。You may even pass an array of columns to an index method to create a compound (or composite) index:

$table->index(['account_id', 'created_at']);

Laravelはテーブル名に基づき、インデックス名を付けます。しかしメソッドの第２引数で、名前を指定することもできます。Laravel will automatically generate an index name based on the table, column names, and the index type, but you may pass a second argument to the method to specify the index name yourself:

$table->unique('email', 'unique_email');

使用可能なインデックスタイプAvailable Index Types

各インデックスメソッドは、オプションとして第２引数に、インデックス名を指定できます。省略した場合、テーブルとカラムから名前が決まるのと同様に、インデックスタイプが自動的に指定されます。Each index method accepts an optional second argument to specify the name of the index. If omitted, the name will be derived from the names of the table and column(s) used for the index, as well as the index type.

インデックス長とMySQL／MariaDBIndex Lengths & MySQL / MariaDB

Laravelはデータベース中への「絵文字」保存をサポートするため、デフォルトでutf8mb4文字セットを使っています。バージョン5.7.7より古いMySQLや、バージョン10.2.2より古いMariaDBを使用している場合、マイグレーションにより生成されるデフォルトのインデックス用文字列長を明示的に設定する必要があります。AppServiceProvider中でSchema::defaultStringLengthを呼び出してください。Laravel uses the utf8mb4 character set by default, which includes support for storing "emojis" in the database. If you are running a version of MySQL older than the 5.7.7 release or MariaDB older than the 10.2.2 release, you may need to manually configure the default string length generated by migrations in order for MySQL to create indexes for them. You may configure this by calling the Schema::defaultStringLength method within your AppServiceProvider:

use Illuminate\Support\Facades\Schema;

/**
 * 全アプリケーションサービスの初期起動処理
 *
 * @return void
 */
public function boot()
{
    Schema::defaultStringLength(191);
}

もしくは、データベースのinnodb_large_prefixオプションを有効にする方法もあります。このオプションを個別に有効にする方法は、使用するデータベースのドキュメントを参照してください。Alternatively, you may enable the innodb_large_prefix option for your database. Refer to your database's documentation for instructions on how to properly enable this option.

インデックス名変更Renaming Indexes

インデックス名を変更するためには、renameIndexメソッドを使用します。このメソッドは最初の引数として現在のインデックス名を受け取り、２つ目の引数として変更後の名前を受け取ります。To rename an index, you may use the renameIndex method. This method accepts the current index name as its first argument and the desired new name as its second argument:

$table->renameIndex('from', 'to')

インデックス削除Dropping Indexes

インデックスを削除する場合はインデックスの名前を指定します。Laravelはデフォルトでテーブル名、インデックスしたカラム名、インデックスタイプに基づいて自動的に名前をつけます。いくつか例をご覧ください。To drop an index, you must specify the index's name. By default, Laravel automatically assigns an index name based on the table name, the name of the indexed column, and the index type. Here are some examples:

カラムの配列をインデックス削除メソッドに渡すと、テーブル、カラム、キータイプに基づき、命名規則に従ったインデックス名が生成されます。If you pass an array of columns into a method that drops indexes, the conventional index name will be generated based on the table name, columns and key type:

Schema::table('geo', function (Blueprint $table) {
    $table->dropIndex(['state']); // 'geo_state_index'インデックスを削除
});

外部キー制約Foreign Key Constraints

Laravelはデータベースレベルの整合性を強制するために、テーブルに対する外部キー束縛の追加も提供しています。たとえばusersテーブルのidカラムを参照する、postsテーブルのuser_idカラムを定義してみましょう。Laravel also provides support for creating foreign key constraints, which are used to force referential integrity at the database level. For example, let's define a user_id column on the posts table that references the id column on a users table:

Schema::table('posts', function (Blueprint $table) {
    $table->unsignedBigInteger('user_id');

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

この書き方はやや複雑です。より良い開発イクスピアリエンスを提供するため、Laravelはさらに便利に使用できる簡潔なメソッドを提供しています。上の例は、次のように書き換えられます。Since this syntax is rather verbose, Laravel provides additional, terser methods that use convention to provide a better developer experience. The example above could be written like so:

Schema::table('posts', function (Blueprint $table) {
    $table->foreignId('user_id')->constrained();
});

foreignIdメソッドはunsignedBigIntegerのエイリアスです。一方のconstrainedメソッドはテーブルとカラム名をforeignIdで指定したカラム名をもとに規約により決定します。テーブル名が規約と合っていない場合は、constrainedメソッドの引数にテーブル名を渡してください。The foreignId method is an alias for unsignedBigInteger while the constrained method will use convention to determine the table and column name being referenced. If your table name does not match the convention, you may specify the table name by passing it as an argument to the constrained method:

Schema::table('posts', function (Blueprint $table) {
    $table->foreignId('user_id')->constrained('users');
});

さらに束縛に対して「デリート時(on delete)」と「更新時(on update)」に対する処理をオプションとして指定できます。You may also specify the desired action for the "on delete" and "on update" properties of the constraint:

$table->foreignId('user_id')
      ->constrained()
      ->onDelete('cascade');

追加のカラム修飾子はconstrainedより前で呼び出してください。Any additional column modifiers[#column-modifiers] must be called before constrained:

$table->foreignId('user_id')
      ->nullable()
      ->constrained();

外部キーを削除するには、dropForeignメソッドに削除する外部キー束縛を指定します。インデックスで使用されるものと同じ命名規則が、外部キーにも使用されています。制約するテーブル名とカラム名に基づいて、"_foreign"を最後につけた名前です。To drop a foreign key, you may use the dropForeign method, passing the foreign key constraint to be deleted as an argument. Foreign key constraints use the same naming convention as indexes, based on the table name and the columns in the constraint, followed by a "_foreign" suffix:

$table->dropForeign('posts_user_id_foreign');

もしくは、dropForeignメソッドへ外部キーのカラム名を持つ配列を指定する方法もあります。配列はLaravelのスキームビルダの制約命名規則に従い、自動的に変換されます。Alternatively, you may pass an array containing the column name that holds the foreign key to the dropForeign method. The array will be automatically converted using the constraint name convention used by Laravel's schema builder:

$table->dropForeign(['user_id']);

以下のメソッドにより、マイグレーション中の外部キー制約の有効／無効を変更できます。You may enable or disable foreign key constraints within your migrations by using the following methods:

Schema::enableForeignKeyConstraints();

Schema::disableForeignKeyConstraints();

Note: note デフォルト状態では、SQLiteは外部キー制約が利用できません。SQLiteを使用する場合は、マイグレーションで外部キーを作成する前に、確実に外部キーサポートを有効にしてください。さらに、SQLiteはテーブル生成時のみ外部キーをサポートしており、テーブル変更時ではありません。{note} SQLite disables foreign key constraints by default. When using SQLite, make sure to enable foreign key support[/docs/{{version}}/database#configuration] in your database configuration before attempting to create them in your migrations. In addition, SQLite only supports foreign keys upon creation of the table and not when tables are altered[https://www.sqlite.org/omitted.html].