Migrating Data

Last edit: 


This guide will help you use migrations when you need to change the data or execute a piece of code outside of the regular application running cycle, for example, when you want to seed data on each environment.


This is an advanced tutorial. To follow it, you should be familiar with basic platformOS concepts, and the topics in the Get Started section.


Migrating data is a three-step process:

  1. Generate empty migration
  2. Implement migration
  3. Run migration

Step 1: Generate empty migration

Generate an empty migration using the marketplace-kit migrations command:

marketplace-kit migrations generate ENVIRONMENT MIGRATION_NAME

For example:

marketplace-kit migrations generate local add_some_books

On success, this generates an empty migration in the marketplace_builder/migrations directory.

Please note that the name you provide will be prefixed with a UTC timestamp, that looks like this: 20180731120002. In our example, the file created will be named something like this: 20180909123423_add_some_books.liquid.
This value is used to keep the migrations in order in all environments.

Step 2: Implement migration

Use the Liquid markup in migration files, that includes executing GraphQL mutations (execute_query tag). A migration file can be synced many times.

For example, the following mutation can be put into the file created by the command in step 1:

{% execute_query 'create_book', name: "Animal Farm", author: "George Orwell" %}

Step 3: Run migration

Deployment will try to run migrations one by one (ordered by timestamp) and it will fail if one of the migrations fails.

The marketplace-kit migrations run command runs a single migration:

marketplace-kit migrations run ENVIRONMENT MIGRATION_TIMESTAMP

For example:

marketplace-kit migrations run local 20180909123423

A newly created migration is in pending status for as long as it has not been run. Once it's executed (either through a deploy or using the migrations run command) it progresses to either done (on success) or error status.

Once migration is in done status it can't be run any more - this makes it safer to run the same queue of migrations on all environments.

When an error occurs, the migration can be edited and rerun until it succeeds.


We are always happy to help with any questions you may have. Check out our Help page, or contact us.