Migrating Data

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.

Requirements

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

• platformOS Workflow
• Get Started

Steps

Migrating data is a three-step process:

Step 1: Generate empty migration

Generate an empty migration using the pos-cli migrations command:

pos-cli migrations generate ENVIRONMENT MIGRATION_NAME

For example:

pos-cli migrations generate local add_some_books

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

You can use the list command to display all migrations created on an environment:

pos-cli migrations list local

Please note that the name you provide will be prefixed with a UTC timestamp, that looks like this: 20180731120002. In this 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. Do not change this value by hand, and do not skip this step by simply adding a file in the migrations/ directory because it may cause errors.

Step 2: Implement migration

Use the Liquid markup in migration files, that includes executing GraphQL mutations (graphql 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:

{% graphql res = 'create_book', name: "Animal Farm", author: "George Orwell" %}

Step 3: Run migration

The deployment will upload and try to run migrations one by one (ordered by timestamp) and it will fail if one of the migrations fails. In the context of modules, migrations are run when the deployment is done through the Partner Portal or using the pos-cli deploy -p option.

The pos-cli migrations run command starts a background process that runs a single migration:

pos-cli migrations run ENVIRONMENT MIGRATION_TIMESTAMP

For example:

pos-cli 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.

You can check the status of all migrations using the pos-cli migrations list command.

Once a migration is in the done status, it can't be run anymore - 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.

Although migrations are run in a background worker and will not affect the performance of your site, we encourage using Data Import/Export for any larger data processing jobs. Migrations are best for seeding data and doing small changes to a Table.