Migrations

Migrations is a plugin supported by the core team that helps you do schemachanges in your database by writing PHP files that can be tracked using yourversion control system.

It allows you to evolve your database tables over time. Instead of writingschema modifications in SQL, this plugin allows you to use an intuitive set ofmethods to implement your database changes.

This plugin is a wrapper for the database migrations library Phinx.

Installation

By default Migrations is installed with the default application skeleton. Ifyou’ve removed it and want to re-install it, you can do so by running thefollowing from your application’s ROOT directory (where composer.json file islocated):

  1. php composer.phar require cakephp/migrations "@stable"
  2.  
  3. # Or if composer is installed globally
  4. composer require cakephp/migrations "@stable"

To use the plugin you’ll need to load it in your application’sconfig/bootstrap.php file. You can use CakePHP’s Plugin shell toload and unload plugins from your config/bootstrap.php:

  1. bin/cake plugin load Migrations

Or you can load the plugin by editing your src/Application.php file andadding the following statement:

  1. $this->addPlugin('Migrations');
  2.  
  3. // Prior to 3.6.0 you need to use Plugin::load()

Additionally, you will need to configure the default database configuration foryour application in your config/app.php file as explained in the DatabaseConfiguration section.

Overview

A migration is basically a single PHP file that describes the changes to operateto the database. A migration file can create or drop tables, add or removecolumns, create indexes and even insert data into your database.

Here’s an example of a migration:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class CreateProducts extends AbstractMigration
  5. {
  6.     /**
  7.      * Change Method.
  8.      *
  9.      * More information on this method is available here:
  10.      * http://docs.phinx.org/en/latest/migrations.html#the-change-method
  11.      * @return void
  12.      */
  13.     public function change()
  14.     {
  15.         $table = $this->table('products');
  16.         $table->addColumn('name', 'string', [
  17.             'default' => null,
  18.             'limit' => 255,
  19.             'null' => false,
  20.         ]);
  21.         $table->addColumn('description', 'text', [
  22.             'default' => null,
  23.             'null' => false,
  24.         ]);
  25.         $table->addColumn('created', 'datetime', [
  26.             'default' => null,
  27.             'null' => false,
  28.         ]);
  29.         $table->addColumn('modified', 'datetime', [
  30.             'default' => null,
  31.             'null' => false,
  32.         ]);
  33.         $table->create();
  34.     }
  35. }

This migration will add a table to your database named products with thefollowing column definitions:

  • id column of type integer as primary key
  • name column of type string
  • description column of type text
  • created column of type datetime
  • modified column of type datetime

Tip

The primary key column named id will be added implicitly.

Note

Note that this file describes how the database will look afterapplying the migration. At this point no products table exists inyour database, we have merely created a file that is able to both createthe products table with the specified columns as well as drop itwhen a rollback operation of the migration is performed.

Once the file has been created in the config/Migrations folder, you will beable to execute the following migrations command to create the table inyour database:

  1. bin/cake migrations migrate

The following migrations command will perform a rollback and drop thetable from your database:

  1. bin/cake migrations rollback

Creating Migrations

Migration files are stored in the config/Migrations directory of yourapplication. The name of the migration files are prefixed with the date inwhich they were created, in the format YYYYMMDDHHMMSS_MigrationName.php.Here are examples of migration filenames:

  • 20160121163850_CreateProducts.php
  • 20160210133047_AddRatingToProducts.php

The easiest way to create a migrations file is by using bin/cake bakemigration CLI command.

Please make sure you read the officialPhinx documentationin order to know the complete list of methods you can use for writing migrationfiles.

Note

When using the bake option, you can still modify the migration beforerunning them if so desired.

Syntax

The bake command syntax follows the form below:

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

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

  • the name of the migration you will generate (CreateProducts in ourexample)
  • 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 shellcommands.

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

  1. bin/cake migrations create MyCustomMigration

Migrations file name

Migration names can follow any of the following patterns:

  • (/^(Create)(.*)/) Creates the specified table.
  • (/^(Drop)(.*)/) Drops the specified table.Ignores specified field arguments
  • (/^(Add).(?:To)(.)/) Adds fields to the specifiedtable
  • (/^(Remove).(?:From)(.)/) Removes fields from thespecified table
  • (/^(Alter)(.*)/) Alters the specified table. An aliasfor CreateTable and AddField.

You can also use the underscore_form as the name for your migrations i.e.create_products.

New in version cakephp/migrations: 1.5.2

As of v1.5.2 of the migrations plugin,the migration filename will be automatically camelized. This version of theplugin is only available with a release of CakePHP >= to 3.1. Prior to thisversion of the plugin the migration name would be in the underscore form,i.e. 20160121164955_create_products.php.

Warning

Migration names are used as migration class names, and thus may collide withother migrations if the class names are not unique. In this case, it may benecessary to manually override the name at a later date, or simply changethe name you are specifying.

Columns definition

When using columns in the command line, it may be handy to remember that theyfollow the following pattern:

  1. fieldName:fieldType?[length]:indexType:indexName

For instance, the following are all valid ways of specifying an email field:

  • email:string?
  • email:string:unique
  • email:string?[50]
  • email:string:unique:EMAIL_INDEX
  • email:string[120]:unique:EMAIL_INDEX

While defining decimal, the length can be defined to have precision and scale, separated by a comma.

  • amount:decimal[5,2]
  • amount:decimal?[5,2]

The question mark following the fieldType will make the column nullable.

The length parameter for the fieldType is optional and should always bewritten between bracket.

Fields named created and modified, as well as any field with a _atsuffix, will automatically be set to the type datetime.

Field types are those generically made available by the Phinx library. Thosecan be:

  • string
  • text
  • integer
  • biginteger
  • float
  • decimal
  • datetime
  • timestamp
  • time
  • date
  • binary
  • boolean
  • uuid

There are some heuristics to choosing fieldtypes when left unspecified or set toan invalid value. Default field type is string:

  • id: integer
  • created, modified, updated: datetime
  • latitude, longitude: decimal

Creating a table

You can use bake to create a table:

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

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

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class CreateProducts extends AbstractMigration
  5. {
  6.     /**
  7.      * Change Method.
  8.      *
  9.      * More information on this method is available here:
  10.      * http://docs.phinx.org/en/latest/migrations.html#the-change-method
  11.      * @return void
  12.      */
  13.     public function change()
  14.     {
  15.         $table = $this->table('products');
  16.         $table->addColumn('name', 'string', [
  17.             'default' => null,
  18.             'limit' => 255,
  19.             'null' => false,
  20.         ]);
  21.         $table->addColumn('description', 'text', [
  22.             'default' => null,
  23.             'null' => false,
  24.         ]);
  25.         $table->addColumn('created', 'datetime', [
  26.             'default' => null,
  27.             'null' => false,
  28.         ]);
  29.         $table->addColumn('modified', 'datetime', [
  30.             'default' => null,
  31.             'null' => false,
  32.         ]);
  33.         $table->create();
  34.     }
  35. }

Adding columns to an existing table

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

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

Executing the command line above will generate:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class AddPriceToProducts extends AbstractMigration
  5. {
  6.     public function change()
  7.     {
  8.         $table = $this->table('products');
  9.         $table->addColumn('price', 'decimal', [
  10.             'default' => null,
  11.             'null' => false,
  12.             'precision' => 5,
  13.             'scale' => 2,
  14.         ]);
  15.         $table->update();
  16.     }
  17. }

Adding a column as index to a table

It is also possible to add indexes to columns:

  1. bin/cake bake migration AddNameIndexToProducts name:string:index

will generate:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class AddNameIndexToProducts extends AbstractMigration
  5. {
  6.     public function change()
  7.     {
  8.         $table = $this->table('products');
  9.         $table->addColumn('name', 'string')
  10.               ->addIndex(['name'])
  11.               ->update();
  12.     }
  13. }

Specifying field length

New in version cakephp/migrations: 1.4

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

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

Executing the command line above will generate:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class AddFullDescriptionToProducts extends AbstractMigration
  5. {
  6.     public function change()
  7.     {
  8.         $table = $this->table('products');
  9.         $table->addColumn('full_description', 'string', [
  10.             'default' => null,
  11.             'limit' => 60,
  12.             'null' => false,
  13.         ])
  14.         ->update();
  15.     }
  16. }

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

  • string: 255
  • integer: 11
  • biginteger: 20

Removing a column from a table

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

  1. bin/cake bake migration RemovePriceFromProducts price

creates the file:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class RemovePriceFromProducts extends AbstractMigration
  5. {
  6.     public function up()
  7.     {
  8.         $table = $this->table('products');
  9.         $table->removeColumn('price')
  10.               ->save();
  11.     }
  12. }

Note

The removeColumn command is not reversible, so must be called in theup method. A corresponding addColumn call should be added to thedown method.

Generating migrations from an existing database

If you are dealing with a pre-existing database and want to start usingmigrations, or to version control the initial schema of your application’sdatabase, you can run the migration_snapshot command:

  1. bin/cake bake migration_snapshot Initial

It will generate a migration file called YYYYMMDDHHMMSS_Initial.phpcontaining all the create statements for all tables in your database.

By default, the snapshot will be created by connecting to the database definedin the default connection configuration.If you need to bake a snapshot from a different datasource, you can use the—connection option:

  1. bin/cake bake migration_snapshot Initial --connection my_other_connection

You can also make sure the snapshot includes only the tables for which you havedefined the corresponding model classes by using the —require-table flag:

  1. bin/cake bake migration_snapshot Initial --require-table

When using the —require-table flag, the shell will look through yourapplication Table classes and will only add the model tables in the snapshot.

The same logic will be applied implicitly if you wish to bake a snapshot for aplugin. To do so, you need to use the —plugin option:

  1. bin/cake bake migration_snapshot Initial --plugin MyPlugin

Only the tables which have a Table object model class defined will be addedto the snapshot of your plugin.

Note

When baking a snapshot for a plugin, the migration files will be createdin your plugin’s config/Migrations directory.

Be aware that when you bake a snapshot, it is automatically added to the phinxlog table as migrated.

Generating a diff between two database states

New in version cakephp/migrations: 1.6.0

You can generate a migrations file that will group all the differences betweentwo database states using the migration_diff bake template. To do so, youcan use the following command:

  1. bin/cake bake migration_diff NameOfTheMigrations

In order to have a point of comparison from your current database state, themigrations shell will generate a “dump” file after each migrate orrollback call. The dump file is a file containing the full schema state ofyour database at a given point in time.

Once a dump file is generated, every modifications you do directly in yourdatabase management system will be added to the migration file generated whenyou call the bake migration_diff command.

By default, the diff will be created by connecting to the database definedin the default connection configuration.If you need to bake a diff from a different datasource, you can use the—connection option:

  1. bin/cake bake migration_diff NameOfTheMigrations --connection my_other_connection

If you want to use the diff feature on an application that already has amigrations history, you need to manually create the dump file that will be usedas comparison:

  1. bin/cake migrations dump

The database state must be the same as it would be if you just migrated allyour migrations before you create a dump file.Once the dump file is generated, you can start doing changes in your databaseand use the bake migration_diff command whenever you see fit.

Note

The migrations shell can not detect column renamings.

The commands

migrate : Applying Migrations

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

  1. # Run all the migrations
  2. bin/cake migrations migrate
  3.  
  4. # Migrate to a specific version using the ``--target`` option
  5. # or ``-t`` for short.
  6. # The value is the timestamp that is prefixed to the migrations file name::
  7. bin/cake migrations migrate -t 20150103081132
  8.  
  9. # By default, migration files are looked for in the **config/Migrations**
  10. # directory. You can specify the directory using the ``--source`` option
  11. # or ``-s`` for short.
  12. # The following example will run migrations in the **config/Alternate**
  13. # directory
  14. bin/cake migrations migrate -s Alternate
  15.  
  16. # You can run migrations to a different connection than the ``default`` one
  17. # using the ``--connection`` option or ``-c`` for short
  18. bin/cake migrations migrate -c my_custom_connection
  19.  
  20. # Migrations can also be run for plugins. Simply use the ``--plugin`` option
  21. # or ``-p`` for short
  22. bin/cake migrations migrate -p MyAwesomePlugin

rollback : Reverting Migrations

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

  1. # You can rollback to the previous migration by using the
  2. # ``rollback`` command::
  3. bin/cake migrations rollback
  4.  
  5. # You can also pass a migration version number to rollback
  6. # to a specific version::
  7. bin/cake migrations rollback -t 20150103081132

You can also use the —source, —connection and —plugin optionsjust like for the migrate command.

status : Migrations Status

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

  1. bin/cake migrations status

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

  1. bin/cake migrations status --format json

You can also use the —source, —connection and —plugin optionsjust like for the migrate command.

mark_migrated : Marking a migration as migrated

New in version 1.4.0.

It can sometimes be useful to mark a set of migrations as migrated withoutactually 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:

  1. bin/cake migrations mark_migrated

You can also mark all migrations up to a specific version as migrated usingthe —target option:

  1. bin/cake migrations mark_migrated --target=20151016204000

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

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

Finally, if you wish to mark only the targeted migration as migrated, you canuse the —only flag:

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

You can also use the —source, —connection and —plugin optionsjust like for the migrate command.

Note

When you bake a snapshot with the cake bake migration_snapshotcommand, the created migration will automatically be marked as migrated.

Deprecated since version 1.4.0: The following way of using the command has been deprecated. Use it onlyif you are using a version of the plugin < 1.4.0.

This command expects the migration version number as argument:

  1. bin/cake migrations mark_migrated 20150420082532

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

  1. bin/cake migrations mark_migrated all

seed : Seeding your database

As of 1.5.5, you can use the migrations shell to seed your database. Thisleverages the Phinx library seed feature.By default, seed files will be looked for in the config/Seeds directory ofyour application. Please make sure you followPhinx instructions to build your seed files.

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

  1. # This will create a ArticlesSeed.php file in the directory config/Seeds of your application
  2. # By default, the table the seed will try to alter is the "tableized" version of the seed filename
  3. bin/cake bake seed Articles
  4.  
  5. # You specify the name of the table the seed files will alter by using the ``--table`` option
  6. bin/cake bake seed Articles --table my_articles_table
  7.  
  8. # You can specify a plugin to bake into
  9. bin/cake bake seed Articles --plugin PluginName
  10.  
  11. # You can specify an alternative connection when generating a seeder.
  12. bin/cake bake seed Articles --connection connection

New in version cakephp/migrations: 1.6.4

Options —data, —limit and —fields were added to exportdata from your database.

As of 1.6.4, the bake seed command allows you to create a seed file withdata exported from your database by using the —data flag:

  1. bin/cake bake seed --data Articles

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

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

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

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

Tip

Of course you can use both the —limit and —fields options in thesame command call.

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

  1. # Without parameters, the seed subcommand will run all available seeders
  2. # in the target directory, in alphabetical order.
  3. bin/cake migrations seed
  4.  
  5. # You can specify only one seeder to be run using the `--seed` option
  6. bin/cake migrations seed --seed ArticlesSeed
  7.  
  8. # You can run seeders from an alternative directory
  9. bin/cake migrations seed --source AlternativeSeeds
  10.  
  11. # You can run seeders from a plugin
  12. bin/cake migrations seed --plugin PluginName
  13.  
  14. # You can run seeders from a specific connection
  15. bin/cake migrations seed --connection connection

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

Calling a Seeder from another Seeder

New in version cakephp/migrations: 1.6.2

Usually when seeding, the order in which to insert the data must be respectedto not encounter constraints violations. Since Seeders are executed in thealphabetical order by default, you can use the \Migrations\AbstractSeed::call()method to define your own sequence of seeders execution:

  1. use Migrations\AbstractSeed;
  2.  
  3. class DatabaseSeed extends AbstractSeed
  4. {
  5.     public function run()
  6.     {
  7.         $this->call('AnotherSeed');
  8.         $this->call('YetAnotherSeed');
  9.  
  10.         // You can use the plugin dot syntax to call seeders from a plugin
  11.         $this->call('PluginName.FromPluginSeed');
  12.     }
  13. }

Note

Make sure to extend the Migrations plugin AbstractSeed class if you wantto be able to use the call() method. This class was added with release1.6.2.

dump : Generating a dump file for the diff baking feature

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

  1. bin/cake migrations dump

Each generated dump file is specific to the Connection it is generated from (andis suffixed as such). This allows the bake migration_diff command toproperly compute diff in case your application is dealing with multiple databasepossibly 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 optionsjust like for the migrate command.

Using Migrations In Plugins

Plugins can also provide migration files. This makes plugins that are intendedto be distributed much more portable and easy to install. All commands in theMigrations plugin support the —plugin or -p option that will scope theexecution to the migrations relative to that plugin:

  1. bin/cake migrations status -p PluginName
  2.  
  3. bin/cake migrations migrate -p PluginName

Running Migrations in a non-shell environment

New in version cakephp/migrations: 1.2.0

Since the release of version 1.2 of the migrations plugin, you can runmigrations from a non-shell environment, directly from an app, by using the newMigrations class. This can be handy in case you are developing a plugininstaller for a CMS for instance.The Migrations class allows you to run the following commands from themigrations shell:

  • migrate
  • rollback
  • markMigrated
  • status
  • seed

Each of these commands has a method defined in the Migrations class.

Here is how to use it:

  1. use Migrations\Migrations;
  2.  
  3. $migrations = new Migrations();
  4.  
  5. // Will return an array of all migrations and their status
  6. $status = $migrations->status();
  7.  
  8. // Will return true if success. If an error occurred, an exception will be thrown
  9. $migrate = $migrations->migrate();
  10.  
  11. // Will return true if success. If an error occurred, an exception will be thrown
  12. $rollback = $migrations->rollback();
  13.  
  14. // Will return true if success. If an error occurred, an exception will be thrown
  15. $markMigrated = $migrations->markMigrated(20150804222900);
  16.  
  17. // Will return true if success. If an error occurred, an exception will be thrown
  18. $seeded = $migrations->seed();

The methods can accept an array of parameters that should match options fromthe commands:

  1. use Migrations\Migrations;
  2.  
  3. $migrations = new Migrations();
  4.  
  5. // Will return an array of all migrations and their status
  6. $status = $migrations->status(['connection' => 'custom', 'source' => 'MyMigrationsFolder']);

You can pass any options the shell commands would take.The only exception is the markMigrated command which is expecting theversion number of the migrations to mark as migrated as first argument. Passthe array of parameters as the second argument for this method.

Optionally, you can pass these parameters in the constructor of the class.They will be used as default and this will prevent you from having to passthem on each method call:

  1. use Migrations\Migrations;
  2.  
  3. $migrations = new Migrations(['connection' => 'custom', 'source' => 'MyMigrationsFolder']);
  4.  
  5. // All the following calls will be done with the parameters passed to the Migrations class constructor
  6. $status = $migrations->status();
  7. $migrate = $migrations->migrate();

If you need to override one or more default parameters for one call, you canpass them to the method:

  1. use Migrations\Migrations;
  2.  
  3. $migrations = new Migrations(['connection' => 'custom', 'source' => 'MyMigrationsFolder']);
  4.  
  5. // This call will be made with the "custom" connection
  6. $status = $migrations->status();
  7. // This one with the "default" connection
  8. $migrate = $migrations->migrate(['connection' => 'default']);

Tips and tricks

Creating Custom Primary Keys

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

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class CreateProductsTable extends AbstractMigration
  5. {
  6.     public function change()
  7.     {
  8.         $table = $this->table('products', ['id' => false, 'primary_key' => ['id']]);
  9.         $table
  10.               ->addColumn('id', 'uuid')
  11.               ->addColumn('name', 'string')
  12.               ->addColumn('description', 'text')
  13.               ->create();
  14.     }
  15. }

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

Note

When specifying a custom primary key on the command line, you must noteit as the primary key in the id field, otherwise you may get an errorregarding duplicate id fields, i.e.:

  1. 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 wasintroduced. To do so, your migration class should extend the newMigrations\AbstractMigration class.You can specify a autoId property in the Migration class and set it tofalse, which will turn off the automatic id column creation. You willneed to manually create the column that will be used as a primary key and addit to the table declaration:

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class CreateProductsTable extends AbstractMigration
  5. {
  6.  
  7.     public $autoId = false;
  8.  
  9.     public function up()
  10.     {
  11.         $table = $this->table('products');
  12.         $table
  13.             ->addColumn('id', 'integer', [
  14.                 'autoIncrement' => true,
  15.                 'limit' => 11
  16.             ])
  17.             ->addPrimaryKey('id')
  18.             ->addColumn('name', 'string')
  19.             ->addColumn('description', 'text')
  20.             ->create();
  21.     }
  22. }

Compared to the previous way of dealing with primary key, this method gives youthe 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.

Warning

Dealing with primary key can only be done on table creation operations.This is due to limitations for some database servers the plugin supports.

Collations

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

  1. <?php
  2. use Migrations\AbstractMigration;
  3.  
  4. class CreateCategoriesTable extends AbstractMigration
  5. {
  6.     public function change()
  7.     {
  8.         $table = $this
  9.             ->table('categories', [
  10.                 'collation' => 'latin1_german1_ci'
  11.             ])
  12.             ->addColumn('title', 'string', [
  13.                 'default' => null,
  14.                 'limit' => 255,
  15.                 'null' => false,
  16.             ])
  17.             ->create();
  18.     }
  19. }

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

Updating columns name and using Table objects

If you use a CakePHP ORM Table object to manipulate values from your databasealong with renaming or removing a column, make sure you create a new instance ofyour Table object after the update() call. The Table object registry iscleared after an update() call in order to refresh the schema that isreflected 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 ORMcache so it renews the column metadata of your tables. Otherwise, you might endup having errors about columns not existing when performing operations on thosenew columns. The CakePHP Core includes a Schema Cache Shell thatyou can use to perform this operation:

  1. // Prior to 3.6 use orm_cache
  2. 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:

  1. public function up()
  2. {
  3.     $this->table('old_table_name')
  4.         ->rename('new_table_name')
  5.         ->save();
  6. }

Skipping the schema.lock file generation

New in version cakephp/migrations: 1.6.5

In order for the diff feature to work, a .lock file is generated everytimeyou migrate, rollback or bake a snapshot, to keep track of the state of yourdatabase 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:

  1. bin/cake migrations migrate --no-lock
  2.  
  3. bin/cake migrations rollback --no-lock
  4.  
  5. bin/cake bake migration_snapshot MyMigration --no-lock