Migrations

When using multi-database tenancy, migrations for tenant databases are located in database/migrations/tenant. Central (“regular”) migrations are in database/migrations as usual. (See the Getting started page for a visual example.)

Using the --tenants option

Most of the commands listed below support the --tenants option — by default they run for all tenants, but you can narrow the list of tenants to just a few (or even one).

To include multiple tenants using CLI, you can use multiple --tenants=... options. If you’re calling the command using Artisan::call(), --tenants has to be an array.

Usage as a command

php artisan tenants:migrate --tenants=foo
php artisan tenants:migrate --tenants=foo --tenants=bar

Usage in PHP

Artisan::call('tenants:migrate', [
    '--tenants' => ['foo', 'bar'],
]);

Migrate command

To execute tenant migrations, you can use the php artisan tenants:migrate command.

This command supports most of the same options as the regular migrate command, as well as the --tenants option which may be used to provide the tenant keys of the tenants you wish to migrate.

Configuration

If you scroll near the bottom of config/tenancy.php, you’ll see this section:

config/tenancy.php

/**
 * Parameters used by the tenants:migrate command.
 */
'migration_parameters' => [
    '--force' => true, // This needs to be true to run migrations in production.
    '--path' => [database_path('migrations/tenant')],
    '--schema-path' => database_path('schema/tenant-schema.dump'),
    '--realpath' => true,
],

You can see the path for migrations — database/migrations/tenant is specified here using the --path parameter.

Feel free to change this, or add more entries to the array if using a non-standard directory structure. You can also provide this option as part of the command — again since it’s just a command line option — as php artisan tenants:migrate --path ....

Also notice we’re setting --force to true. Normally, you need to pass --force to php artisan migrate in a production environment.

However, since we invoke this command from within the job pipeline (MigrateDatabase job), we need to provide that option here.

Rollback command

To rollback tenant migrations, with the same usage as the regular rollback command, you can use the php artisan tenants:rollback command.

Again, most regular options as well as --tenants may be passed.

Migrate fresh command

For an equivalent for migrate:fresh, you can use the php artisan tenants:migrate-fresh command.

Notably, unlike the two commands mentioned above, this command does not extend an existing Laravel command, instead it reimplements the logic manually so make sure to check out --help for a list of options that may be passed.

Migrate fresh override

You can use the tenancy.database.drop_tenant_databases_on_migrate_fresh config to override the central migrate:fresh command such that it deletes tenants one by one — making sure to delete their databases — rather than just deleting the records. You can find more information on the Database managers page of our documentation, simply search for drop_tenant_databases_on_migrate_fresh to get to the relevant paragraph.

Seed command

You can use php artisan tenants:seed to run the tenant seeders. This command extends the base Seed command, so again you can use most of the regular options as well as --tenants.

Configuration

Just like the migrate command, the seed command also has a dedicated configuration section near the bottom of the config/tenancy.php file:

config/tenancy.php

/**
 * Parameters used by the tenants:seed command.
 */
'seeder_parameters' => [
    '--class' => 'Database\Seeders\DatabaseSeeder', // root seeder class
    // '--force' => true,
],

You can change the seeder class here (e.g. you might want to create a TenantSeeder different from your DatabaseSeeder) and provide any other options the command supports.

Dump command

You can squash tenant migrations using the php artisan tenants:dump command:

$ php artisan tenants:dump
 What tenant do you want to dump the schema for?:
 > 7c27cc0f-8ed6-4d2e-ac86-2ae9ac36acf5
 INFO  Database schema dumped successfully.

This produces a database/schema/tenant-schema.dump file, which is by default passed to the tenants:migrate command as --schema-path. In other words, the tenants:migrate command looks for this file out of the box, with no extra configuration needed on your end.

config/tenancy.php

/**
 * Parameters used by the tenants:migrate command.
 */
'migration_parameters' => [
    '--force' => true, // This needs to be true to run migrations in production.
    '--path' => [database_path('migrations/tenant')],
    '--schema-path' => database_path('schema/tenant-schema.dump'),
    '--realpath' => true,
],

You can also use the --prune argument to delete all of your tenant migrations, while keeping your central migrations untouched. Keep in mind that you should only use this if all of your tenants are fully migrated:

$ php artisan tenants:dump --tenant=7c27cc0f-8ed6-4d2e-ac86-2ae9ac36acf5 --prune
 INFO  Database schema dumped successfully.
 INFO  Tenant migrations pruned.

Parallel commands

Most of these commands that operate on multiple commands support parallel execution. To confirm if an individual command supports that, use --help to see if the --processes option exists.

You can use parallel execution like this:

• php artisan tenants:migrate -p 8 — Run tenants:migrate with 8 processes. It will split up the tenant list into 8 chunks and spawn 8 worker processes that independently operate on each chunk.
• php artisan tenants:migrate -p — Run tenants:migrate with as many processes as you have logical cores. The package attempts to get this information from the operating system. This should work on most operating systems. Note that the number of processes here is capped to 24, in case the core count detection goes wrong, to prevent spawning too many processes.
• php artisan tenants:migrate -P — Same as -p except without the 24 process limit. Can be used with core count autodetect (-P) or a specific process count (-P 32).

The ideal number of processes depends on whether your database server is on the same machine as the machine running this command, the number of logical and perhaps physical cores of each involved machine, and the complexity of your migrations. To get the “best number”, you should set up a staging environment with data and migrations matching your production environment and run actual benchmarks if the execution time of migrations is a big issue for you.

In most cases, using a value that matches the logical core count of the server running the command, or the physical core count of the machine hosting the database, is likely to be optimal.