Laravel 5.3 Database: Migrations

Introduction

Migrations are like version control for your database, allowing your team to easily modify and share the application's database schema. Migrations are typically paired with Laravel's schema builder to easily 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.

The Laravel Schemafacade provides database agnostic support for creating and manipulating tables across all of Laravel's supported database systems.

Generating 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.

The --table and --create options may also be used to indicate the name of the table and whether the migration will be creating a new table. These options simply pre-fill the generated migration stub file with the specified table:

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

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 simply reverse the operations performed by the up method.

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. For example, this migration example creates a flights table:

Forcing Migrations To Run In Production

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

To rollback 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

You may rollback a limited number of migrations by providing the step option to the rollback command. For example, the following command will rollback the last five migrations:

php artisan migrate:rollback --step=5

The migrate:reset command will roll back all of your application's migrations:

php artisan migrate:reset

Rollback & Migrate In Single Command

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:

You may rollback & re-migrate a limited number of migrations by providing the step option to the refresh command. For example, the following command will rollback & re-migrate the last five migrations:

php artisan migrate:refresh --step=5

Tables

Creating Tables

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:

Renaming / Dropping Tables

To drop an existing table, you may use the drop or dropIfExists methods:

Schema::drop('users');
Schema::dropIfExists('users');

Renaming Tables With Foreign Keys

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

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:

Incrementing ID (primary key) using a "UNSIGNED SMALL INTEGER" equivalent.

$table->smallInteger('votes');

SMALLINT equivalent for the database.

$table->softDeletes();

Adds nullable deleted_at column for soft deletes.

$table->string('email');

VARCHAR equivalent column.

$table->string('name', 100);

VARCHAR equivalent with a length.

$table->text('description');

TEXT equivalent for the database.

$table->time('sunrise');

TIME equivalent for the database.

$table->timeTz('sunrise');

TIME (with timezone) equivalent for the database.

$table->tinyInteger('numbers');

TINYINT equivalent for the database.

$table->timestamp('added_on');

TIMESTAMP equivalent for the database.

$table->timestampTz('added_on');

TIMESTAMP (with timezone) equivalent for the database.

$table->timestamps();

Adds nullable created_at and updated_at columns.

$table->timestampsTz();

Adds nullable created_at and updated_at (with timezone) columns.

$table->unsignedBigInteger('votes');

Unsigned BIGINT equivalent for the database.

$table->unsignedInteger('votes');

Unsigned INT equivalent for the database.

$table->unsignedMediumInteger('votes');

Unsigned MEDIUMINT equivalent for the database.

$table->unsignedSmallInteger('votes');

Unsigned SMALLINT equivalent for the database.

$table->unsignedTinyInteger('votes');

Unsigned TINYINT equivalent for the database.

$table->uuid('id');

UUID equivalent for the database.

Column Modifiers

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:

Below is a list of all the available column modifiers. This list does not include the index modifiers:

Modifier

Description

->after('column')

Place the column "after" another column (MySQL Only)

->comment('my comment')

Add a comment to a column

->default($value)

Specify a "default" value for the column

->first()

Place the column "first" in the table (MySQL Only)

->nullable()

Allow NULL values to be inserted into the column

->storedAs($expression)

Create a stored generated column (MySQL Only)

->unsigned()

Set integer columns to UNSIGNED

->virtualAs($expression)

Create a virtual generated column (MySQL Only)

Modifying Columns

Prerequisites

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 specified adjustments to the column:

composer require doctrine/dbal

Updating Column Attributes

The change method allows you to modify some existing column types to a new type or modify the column's attributes. 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:

Note: Renaming any column in a table that also has a column of type enum is not currently supported.

Dropping Columns

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:

Note: Dropping or modifying multiple columns within a single migration while using a SQLite database is not supported.

Indexes

Creating Indexes

The schema builder supports several types of indexes. First, let's look at an example that specifies a column's values should be unique. To create the index, we can simply 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 index:

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

Laravel will automatically generate a reasonable index name, but you may pass a second argument to the method to specify the name yourself:

$table->index('email', 'my_index_name');

Available Index Types

Command

Description

$table->primary('id');

Add a primary key.

$table->primary(['first', 'last']);

Add composite keys.

$table->unique('email');

Add a unique index.

$table->unique('state', 'my_index_name');

Add a custom index name.

$table->unique(['first', 'last']);

Add a composite unique index.

$table->index('state');

Add a basic index.

Dropping Indexes

To drop an index, you must specify the index's name. By default, Laravel automatically assigns a reasonable name to the indexes. Simply concatenate the table name, the name of the indexed column, and the index type. Here are some examples:

Command

Description

$table->dropPrimary('users_id_primary');

Drop a primary key from the "users" table.

$table->dropUnique('users_email_unique');

Drop a unique index from the "users" table.

$table->dropIndex('geo_state_index');

Drop a basic index from the "geo" table.

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:

Foreign Key Constraints

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:

To drop a foreign key, you may use the dropForeign method. Foreign key constraints use the same naming convention as indexes. So, we will concatenate the table name and the columns in the constraint then suffix the name with "_foreign":

$table->dropForeign('posts_user_id_foreign');

Or, you may pass an array value which will automatically use the conventional constraint name when dropping:

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

You may enable or disable foreign key constraints within your migrations by using the following methods:

English pages are hosted to show original documentations for Japanese translations. Notice they are not the latest. If you want the latest, please read official pages.Licensed by MIT License. Copyright at Tayllor Otwell.