Everything you need to know about CakePHP Migrations

Migrations is a powerful feature in CakePHP. It gives you a tool to create or import database structure and data through command line interface. CakePHP Migrations is installed by default when you install CakePHP.

Database migrations creates , updates or deletes MySQL tables using through PHP code which can be run via CLI or through scripts. You can manage database updates in versions which help to track changes and make it easier to run database updates in the system.

It is also useful in plugins where a plugin has MSQL tables which are initially required to be created and to be deleted when uninstalling the plugin. All in all migrations automates the database related operations in an easier and convenient way through developer friendly code and conventions.

1. Using Phinx

Phinx is a standalone command line tool for managing database Migrations. The official Migrations plugin for CakePHP is based on this tool.

If you have got a phinx.yml file at the root of your CakePHP installation if is already installed. If it is not there you can install it. Type:

And then

to initiate the phinx which will create a phinx.yml configuration file in the root of your app.

Also, you need to create folders in your project following the structure db/migrations with adequate writable permissions. It is where your migration files will live. You can change this location in phinx.yml file.

Creating CakePHP Migrations

Create your first migration. I name it CreateUsersTable.

It will generate a php file named something like 20191119100625_create_users_table.php with following code:

Note: Generated file format is YYYYMMDDHHMMSS_your_migration_name.php after camel-case YourMigrationName is converted into lowercase characters separate by underscore(_).

Now,  since the create operation has created a skeleton file lets place some table creation logic inside the change function so that it looks like:

Running Migrations

Once we have updated the change method in migration file lets run it to create the table.

In the console, type:

It should create two new tables, users and phinx where later is used to record log of all migration operations run within the system.

In case you are doing this for a plugin, you may need to set the –path parameter so the migration files are generated at correct location. For example

Here, since we are creating a migration in a different location than the default db/migrations location we have to tell phinx to include it while looking up for a migration to be run.

To do this edit the phinx.yml file to include this location. So the paths configuration, from


Running vendor/bin/phinx migrate next time would scan the new directory for available migrations to be run.

2. Using CakePHP Migrations plugin

Although Migrations plugin uses phinx in the background it can also be run using bin/cake CLI too. The examples below demonstrate the operations via bin/cake if the phinx is not available.

To check whether migrations is installed in your CakePHP application, type:

It should print something like:

If it is not installed type to install it

After installation there should be an entry in the composer.json, as following

If you just installed it type composer dumpautoload to regenerate file auto-load script files.

Once migration are installed and working do the following to generate your first migration script.

It will create a 20191119090031_CreateUsersTable.php file with the following contents:

Note: Generated file format is YYYYMMDDHHMMSS_CreateUsersTable.php

Since the create operation above created a skelelton file let place some table creation logic inside the change function so that it looks like

The code above creates a users table with a full_name field along with created and modified fields which are of type, string, datetime and datetime respecively.

Not lets run it to create a table.

After running it go and check your database. It should have a new users table*

Alternatively CakePHP comes with a Phinx wrapper using which you can run same migration commands with little bit different syntax. For example

It will generate a php file with following code:

Cakephp 3 uses Phinx command line tool for database migrations which makes this process easier. It give additional configuration mechanism which uses [root]/phinx.yml file a configuration file to be used for migrations and seeds paths. Alter this file to change paths to your migrations and seeds folder.

Running Migrations

To run a migration created earlier using steps above do:

You can see the migrations history in phinxlog database table. Above is the brief explanation of how migrations work. Hope it will help you to get started with database migrations. For any queries related to this topic you can comment here J

* – Also notice that there is a phinxlog table as well, if you phinx wrapper enabled. In fact . This is very useful table and it tracks all the migration operations ran on the system as a log.

Leave a Reply