Migrations¶

Syntax¶

The bake command syntax follows the form below:

bin/cake bake migration CreateProducts name:string description:text created modified

When using bake to create tables, add columns and so on, to your database, you will usually provide two things:

• the name of the migration you will generate (CreateProducts in our example)

• the columns of the table that will be added or removed in the migration (name:string description:text created modified in our example)

Due to the conventions, not all schema changes can be performed via these shell commands.

Additionally you can create an empty migrations file if you want full control over what needs to be executed, by omitting to specify a columns definition:

bin/cake migrations create MyCustomMigration

fieldName:fieldType?[length]:indexType:indexName

Creating a table¶

You can use bake to create a table:

bin/cake bake migration CreateProducts name:string description:text created modified

The command line above will generate a migration file that resembles:

<?php
use Migrations\BaseMigration;

class CreateProducts extends BaseMigration
{
    /**
     * Change Method.
     *
     * More information on this method is available here:
     * https://book.cakephp.org/migrations/3/en/writing-migrations.html#the-change-method
     * @return void
     */
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string', [
            'default' => null,
            'limit' => 255,
            'null' => false,
        ]);
        $table->addColumn('description', 'text', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('created', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->addColumn('modified', 'datetime', [
            'default' => null,
            'null' => false,
        ]);
        $table->create();
    }
}

Adding columns to an existing table¶

If the migration name in the command line is of the form “AddXXXToYYY” and is followed by a list of column names and types then a migration file containing the code for creating the columns will be generated:

bin/cake bake migration AddPriceToProducts price:decimal[5,2]

Executing the command line above will generate:

<?php
use Migrations\BaseMigration;

class AddPriceToProducts extends BaseMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('price', 'decimal', [
            'default' => null,
            'null' => false,
            'precision' => 5,
            'scale' => 2,
        ]);
        $table->update();
    }
}

Adding a column as index to a table¶

It is also possible to add indexes to columns:

bin/cake bake migration AddNameIndexToProducts name:string:index

will generate:

<?php
use Migrations\BaseMigration;

class AddNameIndexToProducts extends BaseMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('name', 'string')
              ->addColumn('email', 'string')
              ->addIndex(['name'])
              // add a unique index:
              ->addIndex('email', ['unique' => true])
              ->update();
    }
}

Specifying field length¶

If you need to specify a field length, you can do it within brackets in the field type, ie:

bin/cake bake migration AddFullDescriptionToProducts full_description:string[60]

Executing the command line above will generate:

<?php
use Migrations\BaseMigration;

class AddFullDescriptionToProducts extends BaseMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->addColumn('full_description', 'string', [
            'default' => null,
            'limit' => 60,
            'null' => false,
        ])
        ->update();
    }
}

If no length is specified, lengths for certain type of columns are defaulted:

• string: 255

• integer: 11

• biginteger: 20

Alter a column from a table¶

In the same way, you can generate a migration to alter a column by using the command line, if the migration name is of the form “AlterXXXOnYYY”:

bin/cake bake migration AlterPriceOnProducts name:float

will generate:

<?php
use Migrations\BaseMigration;

class AlterPriceOnProducts extends BaseMigration
{
    public function change()
    {
        $table = $this->table('products');
        $table->changeColumn('name', 'float');
        $table->update();
    }
}

Removing a column from a table¶

In the same way, you can generate a migration to remove a column by using the command line, if the migration name is of the form “RemoveXXXFromYYY”:

bin/cake bake migration RemovePriceFromProducts price

creates the file:

<?php
use Migrations\BaseMigration;

class RemovePriceFromProducts extends BaseMigration
{
    public function up()
    {
        $table = $this->table('products');
        $table->removeColumn('price')
              ->save();
    }
}

migrate : Applying Migrations¶

Once you have generated or written your migration file, you need to execute the following command to apply the changes to your database:

# Run all the migrations
bin/cake migrations migrate

# Migrate to a specific version using the ``--target`` option
# or ``-t`` for short.
# The value is the timestamp that is prefixed to the migrations file name::
bin/cake migrations migrate -t 20150103081132

# By default, migration files are looked for in the **config/Migrations**
# directory. You can specify the directory using the ``--source`` option
# or ``-s`` for short.
# The following example will run migrations in the **config/Alternate**
# directory
bin/cake migrations migrate -s Alternate

# You can run migrations to a different connection than the ``default`` one
# using the ``--connection`` option or ``-c`` for short
bin/cake migrations migrate -c my_custom_connection

# Migrations can also be run for plugins. Simply use the ``--plugin`` option
# or ``-p`` for short
bin/cake migrations migrate -p MyAwesomePlugin

rollback : Reverting Migrations¶

The Rollback command is used to undo previous migrations executed by this plugin. It is the reverse action of the migrate command:

# You can rollback to the previous migration by using the
# ``rollback`` command::
bin/cake migrations rollback

# You can also pass a migration version number to rollback
# to a specific version::
bin/cake migrations rollback -t 20150103081132

You can also use the --source, --connection and --plugin options just like for the migrate command.

status : Migrations Status¶

The Status command prints a list of all migrations, along with their current status. You can use this command to determine which migrations have been run:

bin/cake migrations status

You can also output the results as a JSON formatted string using the --format option (or -f for short):

bin/cake migrations status --format json

You can also use the --source, --connection and --plugin options just like for the migrate command.

mark_migrated : Marking a migration as migrated¶

It can sometimes be useful to mark a set of migrations as migrated without actually running them. In order to do this, you can use the mark_migrated command. The command works seamlessly as the other commands.

You can mark all migrations as migrated using this command:

bin/cake migrations mark_migrated

You can also mark all migrations up to a specific version as migrated using the --target option:

bin/cake migrations mark_migrated --target=20151016204000

If you do not want the targeted migration to be marked as migrated during the process, you can use the --exclude flag with it:

bin/cake migrations mark_migrated --target=20151016204000 --exclude

Finally, if you wish to mark only the targeted migration as migrated, you can use the --only flag:

bin/cake migrations mark_migrated --target=20151016204000 --only

You can also use the --source, --connection and --plugin options just like for the migrate command.

This command expects the migration version number as argument:

bin/cake migrations mark_migrated 20150420082532

If you wish to mark all migrations as migrated, you can use the all special value. If you use it, it will mark all found migrations as migrated:

bin/cake migrations mark_migrated all

seed : Seeding your database¶

Seed classes are a good way to populate your database with default or starter data. They are also a great way to generate data for development environments.

By default, seed files will be looked for in the config/Seeds directory of your application. See the Database Seeding for how to build seed classes.

As for migrations, a bake interface is provided for seed files:

# This will create a ArticlesSeed.php file in the directory config/Seeds of your application
# By default, the table the seed will try to alter is the "tableized" version of the seed filename
bin/cake bake seed Articles

# You specify the name of the table the seed files will alter by using the ``--table`` option
bin/cake bake seed Articles --table my_articles_table

# You can specify a plugin to bake into
bin/cake bake seed Articles --plugin PluginName

# You can specify an alternative connection when generating a seeder.
bin/cake bake seed Articles --connection connection

# Include data from the Articles table in your seed.
bin/cake bake seed --data Articles

By default, it will export all the rows found in your table. You can limit the number of rows exported by using the --limit option:

# Will only export the first 10 rows found
bin/cake bake seed --data --limit 10 Articles

If you only want to include a selection of fields from the table in your seed file, you can use the --fields option. It takes the list of fields to include as a comma separated value string:

# Will only export the fields `id`, `title` and `excerpt`
bin/cake bake seed --data --fields id,title,excerpt Articles

To seed your database, you can use the seed subcommand:

# Without parameters, the seed subcommand will run all available seeders
# in the target directory, in alphabetical order.
bin/cake migrations seed

# You can specify only one seeder to be run using the `--seed` option
bin/cake migrations seed --seed ArticlesSeed

# You can run seeders from an alternative directory, relative to config
bin/cake migrations seed --source AlternativeSeeds

# You can run seeders from a plugin
bin/cake migrations seed --plugin PluginName

# You can run seeders from a specific connection
bin/cake migrations seed --connection connection

Be aware that, as opposed to migrations, seeders are not tracked, which means that the same seeder can be applied multiple times.

use Migrations\BaseSeed;

class DatabaseSeed extends BaseSeed
{
    public function run(): void
    {
        $this->call('AnotherSeed');
        $this->call('YetAnotherSeed');

        // You can use the plugin dot syntax to call seeders from a plugin
        $this->call('PluginName.FromPluginSeed');
    }
}

dump : Generating a dump file for the diff baking feature¶

The Dump command creates a file to be used with the migration_diff bake template:

bin/cake migrations dump

Each generated dump file is specific to the Connection it is generated from (and is suffixed as such). This allows the bake migration_diff command to properly compute diff in case your application is dealing with multiple database possibly from different database vendors.

Dump files are created in the same directory as your migrations files.

You can also use the --source, --connection and --plugin options just like for the migrate command.

Creating Custom Primary Keys¶

If you need to avoid the automatic creation of the id primary key when adding new tables to the database, you can use the second argument of the table() method:

<?php
use Migrations\BaseMigration;

class CreateProductsTable extends BaseMigration
{
    public function change()
    {
        $table = $this->table('products', ['id' => false, 'primary_key' => ['id']]);
        $table
              ->addColumn('id', 'uuid')
              ->addColumn('name', 'string')
              ->addColumn('description', 'text')
              ->create();
    }
}

The above will create a CHAR(36) id column that is also the primary key.

bin/cake bake migration CreateProducts id:uuid:primary name:string description:text created modified

Additionally, since Migrations 1.3, a new way to deal with primary key was introduced. To do so, your migration class should extend the new Migrations\BaseMigration class. You can specify a autoId property in the Migration class and set it to false, which will turn off the automatic id column creation. You will need to manually create the column that will be used as a primary key and add it to the table declaration:

<?php
use Migrations\BaseMigration;

class CreateProductsTable extends BaseMigration
{

    public bool $autoId = false;

    public function up()
    {
        $table = $this->table('products');
        $table
            ->addColumn('id', 'integer', [
                'autoIncrement' => true,
                'limit' => 11
            ])
            ->addPrimaryKey('id')
            ->addColumn('name', 'string')
            ->addColumn('description', 'text')
            ->create();
    }
}

Compared to the previous way of dealing with primary key, this method gives you the ability to have more control over the primary key column definition: unsigned or not, limit, comment, etc.

All baked migrations and snapshot will use this new way when necessary.

Collations¶

If you need to create a table with a different collation than the database default one, you can define it with the table() method, as an option:

<?php
use Migrations\BaseMigration;

class CreateCategoriesTable extends BaseMigration
{
    public function change()
    {
        $table = $this
            ->table('categories', [
                'collation' => 'latin1_german1_ci'
            ])
            ->addColumn('title', 'string', [
                'default' => null,
                'limit' => 255,
                'null' => false,
            ])
            ->create();
    }
}

Note however this can only be done on table creation : there is currently no way of adding a column to an existing table with a different collation than the table or the database. Only MySQL and SqlServer supports this configuration key for the time being.

Updating columns name and using Table objects¶

If you use a CakePHP ORM Table object to manipulate values from your database along with renaming or removing a column, make sure you create a new instance of your Table object after the update() call. The Table object registry is cleared after an update() call in order to refresh the schema that is reflected and stored in the Table object upon instantiation.

Migrations and Deployment¶

If you use the plugin when deploying your application, be sure to clear the ORM cache so it renews the column metadata of your tables. Otherwise, you might end up having errors about columns not existing when performing operations on those new columns. The CakePHP Core includes a Schema Cache Shell that you can use to perform this operation:

// Prior to 3.6 use orm_cache
bin/cake schema_cache clear

Renaming a table¶

The plugin gives you the ability to rename a table, using the rename() method. In your migration file, you can do the following:

public function up()
{
    $this->table('old_table_name')
        ->rename('new_table_name')
        ->update();
}

public function down()
{
    $this->table('new_table_name')
        ->rename('old_table_name')
        ->update();
}

Skipping the schema.lock file generation¶

In order for the diff feature to work, a .lock file is generated everytime you migrate, rollback or bake a snapshot, to keep track of the state of your database schema at any given point in time. You can skip this file generation, for instance when deploying on your production environment, by using the --no-lock option for the aforementioned command:

bin/cake migrations migrate --no-lock

bin/cake migrations rollback --no-lock

bin/cake bake migration_snapshot MyMigration --no-lock

Alert of missing migrations¶

You can use the Migrations.PendingMigrations middleware in local development to alert developers about new migrations that have not been applied:

use Migrations\Middleware\PendingMigrationsMiddleware;

$config = [
    'plugins' => [
        ... // Optionally include a list of plugins with migrations to check.
    ],
];

$middlewareQueue
    ... // ErrorHandler middleware
    ->add(new PendingMigrationsMiddleware($config))
    ... // rest

You can add ‘app’ config key set to false if you are only interested in checking plugin migrations.

You can temporarily disable the migration check by adding skip-migration-check=1 to the URL query string

IDE autocomplete support¶

The IdeHelper plugin can help you to get more IDE support for the tables, their column names and possible column types. Specifically PHPStorm understands the meta information and can help you autocomplete those.