Sharing technology, ideas, insights!
Call: +91 710 466 0336         Email:


Migrations in CakePHP 3 – A quickstart

Migrations in CakePHP 3 was recently spun off as a separate plugin and is a wrapper for Phinx.

First some backstory. Every team I have worked with used some sort of version control system, Git being the current crowd favourite, for collaboration on code but when it comes to keeping the changes to the database structure in sync they were stumped. Using Migrations seemed like a miracle 😉 I met some guy while riding on my roller kaufen, a very fast scooter, and he mentioned it to me, and I´m very glad I listened to him.

Step 1 – Install migration plugin

Install CakePHP and then edit the composer.json file to include the following

Run composer update, and then load the plugin into your application by editing the bootstrap.php and adding the following line

Thats it! you are ready to create your first migration.

Step 2 – Create first migration

At the command line type

and you will see something like

As you can see the skeleton of your first migration has been created for you. Open it in your favourite code editor. It will look something like

Let us write some code in function up() to create the Posts table. The function up is for all those things which you want to add or alter as you move forward in your project and the function down() is for reversing or rolling back these changes. You could also use the new Phinx function change() which is reversible but for now we will stick with up and down! Edit the two functions to look like

Step 3 – Run the migration created

To run the migration

You will see output similar to

If you look at the database, sure enough there will be a table called Posts with an autoincrement field called id. We could have added the columns needed right in our first migration but since we did not let us alter the table by creating another migration.

Step 3 – Create Alter table migration


Edit the Change function of the newly created migration file to have the following code. Note: we have not written anything in the down()

Run the migration again using the same command as above. Look at the structure of the Posts table in the database and you will see that the appropriate fields have been added to the table.

Step 4 – Trying rollback

Since we used the Change function just for the fun lets us try and rollback the change.

This will remove the fields added the AlterPostsTable migration. Rollbacks happen one migration at a time. If you now run

You will see

You can also confirm in the database that the columns have indeed been removed. Just migrating again will bring the columns back. A word of caution! Do not rollback if there is data in the table which will be effected. The data will be deleted permanently. Oh! but you knew that already, right?

You can also execute SQL queries directly in your migration files, I leave that as an exercise for you to find out how from the excellent Phinx documentation. There also is talk of allowing initial import of schema from existing database, that will be good for projects which want to start using Migrations but are already advanced. Since migrations are text files they can be committed to the VCS and all the developers can be kept in sync.


About the Author

Dr. Tarique Sani is a pediatrician and forensic expert by education. He is a PHP programmer of 'wrote the book' caliber and has to his credit several very popular open source as well as commercial PHP projects. He leads a team of dynamic programmers at SANIsoft who have in-depth understanding of Web scalability, development tools and usability practices with strong developmental skills in PHP, MySQL/PostgreSQL, HTML, Javascript, and Linux/Apache


  1. Excellent intro to CakePHP3 migrations! I love using migrations it really is the best way to keep your database version controlled. Also makes it easy to deploy the app when it’s ready.

  2. Yeah its very informative nad usefull post.. CakePHP development provides a better and organized form of PHP platform to create hassle free and organized applications. It saves a lot on development time and hence reduces the development costs significantly.
    CakePHP is rapid development framework for PHP and is the best solution if you are looking to develop and maintain.

  3. Pingback: CakePHP 3 Migrations from Custom Template | 我爱源码网

  4. Pingback: CakePHP 3 Migrations from Custom Template - Technology

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.