content-migrations.md

Content Migrations

If your Craft project is being developed by multiple people, or has been deployed in multiple environments, managing structural changes can become a little cumbersome, as you try to keep all environments in sync with each other.

Enter content migrations. Content migrations are migrations that are written and managed for your Craft project, rather than for Craft the application, or for a plugin.

Creating Migrations

To create a new migration, open up your terminal and go to a Craft project that your plugin is installed in:

cd /path/to/project

Then run the following command to generate a new content migration file (replacing MIGRATION_NAME with your migration name):

./craft migrate/create MIGRATION_NAME

{tip} If your Craft install is running from a Vagrant box, you will need to SSH into the box to run this command.

{note} Migration names must be valid PHP class names, though we recommend sticking with snake_case rather than StudlyCase as a convention.

Enter yes at the prompt, and a new migration file will be created in a migrations/ folder in your project root.

The migration file contains a class with two methods: safeUp() and safeDown(). safeUp() is where you should put the main migration code. If you want to make it possible to revert your migration, safeDown() is where the reversion code goes.

Logging

If you want to log any messages in your migration code, echo it out rather than calling Craft::info():

echo "    > some note\n";

If the migration is being run from a console request, this will ensure the message is seen by whoever is executing the migration, as the message will be output into the terminal. If it’s a web request, Craft will capture it and log it to storage/logs/ just as if you had used Craft::info().

Executing Migrations

There are two ways to execute content migrations: from the terminal, and from the Migrations utility in the Control Panel.

To execute migrations from the terminal, go to your Craft project and run this command:

./craft migrate/up

To execute migrations from the Migrations utility, go to Utilities → Migrations in the Control Panel and click the “Apply new migrations” button.