Laravel 11: migrate and schema commands

This article is for day 15 of the Advent Calendar 2024: Investigating All Artisan Commands in Laravel 11.

This time, I investigated the migrate and schema commands.

I have investigated the migrate command previously, but I re-examined it including options.

Environment

• PHP 8.4.1
• laravel/laravel 11.3.3
• laravel/framework 11.33.2

migrate

Executes migrations.

php artisan migrate

Running this executes pending migrations.

When executed in a production environment (APP_ENV in .env is production), a confirmation message is displayed.

Selecting "Yes" will execute the migrations.

Option	Description
--database[=DATABASE]	Specify the database connection
--force	Force the operation to run when in production
--path[=PATH]	Specify the path(s) to the migration files to be executed
--realpath	Specify the path to the migration files as an absolute path
--schema-path[=SCHEMA-PATH]	Specify the path to the schema dump file
--pretend	Output the SQL queries that would be executed
--seed	Run seeders after migration
--seeder[=SEEDER]	Specify the seeder class
--step	Execute migrations individually
--graceful	Exit successfully even if migrations fail
--isolated[=ISOLATED]	Run migrations in isolation

• You can specify the database connection name defined in config/database.php for --database. If not specified, the migrations are executed on the default database.
• Adding --force in a production environment will execute the command without confirmation.
• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.
• You can specify the path to the schema dump file using --schema-path. If not specified, it defaults to database/schema/{database_connection_name}-schema.sql.
• By adding --pretend, you can check the SQL that would be executed without actually running it. Please refer to this article for more details.
• Adding --seed runs seeders after the migration. You can specify a seeder class using --seeder (if not specified, Database\Seeders\DatabaseSeeder is executed).
• Adding --step executes migrations one by one rather than in a single batch. This is useful for rolling back a single file at a time.
• Adding --graceful allows the command to finish successfully even if a migration fails.
• When running migrations simultaneously on multiple servers, adding --isolated enables mutual exclusion for migrations.

migrate:status

Check the status of migrations.

php artisan migrate:status

When executed, you can confirm whether each migration has been run or is still pending.

advent-calendar-2024 % php artisan migrate:status

  Migration name .................................... Batch / Status
  0001_01_01_000000_create_users_table ..................... [1] Ran
  0001_01_01_000001_create_cache_table ..................... [2] Ran
  0001_01_01_000002_create_jobs_table ...................... Pending

Option	Description
--database[=DATABASE]	Specify the database connection
--pending[=PENDING]	Display only pending migrations
--path[=PATH]	Specify the path(s) to the migration files
--realpath	Specify the path to the migration files as an absolute path

• You can specify the database connection name defined in config/database.php for --database. If not specified, the status is checked against the default database.
• Using --pending allows you to check only unexecuted migrations (defaults to false, checking all migrations).

php artisan migrate:status --pending=true

• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.

migrate:rollback

Roll back the last database migration.

php artisan migrate:rollback

When executed, it rolls back the last batch of migrations.

Just like the migrate command, if executed in a production environment (APP_ENV in .env is production), a confirmation message will be displayed.

Option	Description
--database[=DATABASE]	Specify the database connection
--force	Force the operation to run when in production
--path[=PATH]	Specify the path(s) to the migration files to be executed
--realpath	Specify the path to the migration files as an absolute path
--pretend	Output the SQL queries that would be executed
--step[=STEP]	The number of migrations to be reverted
--batch=BATCH	Specify the batch number to roll back

• You can specify the database connection name defined in config/database.php for --database. If not specified, the command runs on the default database.
• Adding --force in a production environment will execute the command without confirmation. However, if the \Illuminate\Console\Prohibitable trait mentioned earlier is used, it cannot be executed even with --force.
• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.
• By adding --pretend, you can check the SQL that would be executed without actually running it.
• --step and --batch will roll back the specified number of migrations.
  • In the following state:
    • If --step=2, the following two will be rolled back (going back two from the last executed migration):
      0001_01_01_000001_create_cache_table
      0001_01_01_000001_create_cache_table
    • If --batch=2, the following one will be rolled back (reverting migrations with Batch number 2):
      0001_01_01_000001_create_cache_table

    Migration name .................................... Batch / Status
    0001_01_01_000000_create_users_table ..................... [1] Ran
    0001_01_01_000001_create_cache_table ..................... [2] Ran
    0001_01_01_000002_create_jobs_table ...................... [3] Ran
    

migrate:fresh

Drop all tables and then execute migrations.

php artisan migrate:fresh

Running this command uses the db:wipe command to drop all tables, and then executes the migrate command.

Just like the migrate command, if executed in a production environment (APP_ENV in .env is production), a confirmation message will be displayed.

Additionally, from Laravel 11, the \Illuminate\Console\Prohibitable trait is provided for migrate:fresh to stop execution instead of just asking for confirmation. Using this trait prevents execution in a production environment. (Depending on how it's written, you can also stop it in other environments.)

Below is the result of running the command when using the \Illuminate\Console\Prohibitable trait.

advent-calendar-2024 % php artisan migrate:fresh

   WARN  This command is prohibited from running in this environment.

For more details, please read this article.
https://zenn.dev/naopusyu/articles/98ca9732f5c700

Option	Description
--database[=DATABASE]	Specify the database connection
--drop-views	Drop all views
--drop-types	Drop all user-defined types
--force	Force the operation to run when in production
--path[=PATH]	Specify the path(s) to the migration files to be executed
--realpath	Specify the path to the migration files as an absolute path
--schema-path[=SCHEMA-PATH]	Specify the path to the schema dump file
--seed	Run seeders after migration
--seeder[=SEEDER]	Specify the seeder class
--step	Execute migrations individually

• You can specify the database connection name defined in config/database.php for --database. If not specified, the migrations are executed on the default database.
• Adding --drop-views will also drop all views.
• Adding --drop-types will also drop all user-defined types (PostgreSQL only).
• Adding --force in a production environment will execute the command without confirmation. However, if the \Illuminate\Console\Prohibitable trait mentioned earlier is used, it cannot be executed even with --force.

advent-calendar-2024 % php artisan migrate:fresh --force

   WARN  This command is prohibited from running in this environment.

• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.
• You can specify the path to the schema dump file using --schema-path. If not specified, it defaults to database/schema/{database_connection_name}-schema.sql.
• Adding --seed runs seeders after the migration. You can specify a seeder class using --seeder (if not specified, Database\Seeders\DatabaseSeeder is executed).
• Adding --step executes migrations one by one rather than in a single batch. This is useful for rolling back a single file at a time.

migrate:reset

Roll back all database migrations.

php artisan migrate:reset

When executed, it rolls back all migrations.

Just like the migrate command, if executed in a production environment (APP_ENV in .env is production), a confirmation message will be displayed.
Also, similar to the migrate:fresh command, you can prevent execution in a production environment by using the \Illuminate\Console\Prohibitable trait.

Option	Description
--database[=DATABASE]	Specify the database connection
--force	Force the operation to run when in production
--path[=PATH]	Specify the path(s) to the migration files to be executed
--realpath	Specify the path to the migration files as an absolute path
--pretend	Output the SQL queries that would be executed

• You can specify the database connection name defined in config/database.php for --database. If not specified, the command runs on the default database.
• Adding --force in a production environment will execute the command without confirmation. However, if the \Illuminate\Console\Prohibitable trait mentioned earlier is used, it cannot be executed even with --force.
• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.
• By adding --pretend, you can check the SQL that would be executed without actually running it.

migrate:refresh

Reset and re-run all migrations.

php artisan migrate:refresh

When executed, it uses the migrate:reset command to roll back all migrations and then executes the migrate command.

Just like the migrate command, if executed in a production environment (APP_ENV in .env is production), a confirmation message will be displayed.
Also, similar to the migrate:fresh command, you can prevent execution in a production environment by using the \Illuminate\Console\Prohibitable trait.

Option	Description
--database[=DATABASE]	Specify the database connection
--force	Force the operation to run when in production
--path[=PATH]	Specify the path(s) to the migration files to be executed
--realpath	Specify the path to the migration files as an absolute path
--seed	Run seeders after migration
--seeder[=SEEDER]	Specify the seeder class
--step[=STEP]	The number of migrations to be reverted and re-run

• You can specify the database connection name defined in config/database.php for --database. If not specified, the migrations are executed on the default database.
• Adding --force in a production environment will execute the command without confirmation. However, if the \Illuminate\Console\Prohibitable trait mentioned earlier is used, it cannot be executed even with --force.
• You can specify the path to the migration files using --path. *Multiple paths can be specified. The paths should be relative to the application's base path, but you can use absolute paths by adding --realpath.
• Adding --seed runs seeders after the migration. You can specify a seeder class using --seeder (if not specified, Database\\Seeders\\DatabaseSeeder is executed).
• --step rolls back the specified number of migrations before re-running them. In this case, the rollback is performed by the migrate:rollback command.

migrate:install

Create the migration repository.

php artisan migrate:install

Since this command is executed from the migrate command, there is likely no need to run it directly.

When executed, it creates the migrations table.
The table name is specified in config/database.php, so you can change it to a different name.

config/database.php

    'migrations' => [
        'table' => 'migrations', // You can change the table name by rewriting this
        'update_date_on_publish' => true,
    ],

Option	Description
--database[=DATABASE]	Specify the database connection

• You can specify the database connection name defined in config/database.php for --database. If not specified, the command runs on the default database.

schema:dump

Dump the given database's schema to a file.

php artisan schema:dump

When executed, it creates a schema dump file in the database/schema directory based on the contents of the migrations that have already been run.
The file name will be {database_connection_name}-schema.sql, corresponding to the name of the connection's database.

If this schema dump file exists, the migrate command will first execute the contents of the schema dump file and then run any pending migrations.

Option	Description
--database[=DATABASE]	Specify the database connection
--path[=PATH]	Specify the path to the schema dump file
--prune	Delete migration files

• You can specify the database connection name defined in config/database.php for --database. If not specified, the command runs on the default database.
• You can specify the path to the schema dump file using --path. (If not specified, it defaults to database/schema/{database_connection_name}-schema.sql).
• Adding --prune will delete the migration files under database/migrations (the migrations directory itself will also be removed).