Migrating Data

This document guides you in using migrations when you need to change the data or execute a piece of code outside of the regular application running cycle. An example use case is when you want to seed data on different environments.

Prerequisites

To be able to follow the steps in this tutorial, you must understand basic Insites concepts, and the topics in the 'Get Started' section.

• Development Workflow
• Get Started

Steps

Migrating data is a three-step process:

• Step 1: Generate an empty migration
• Step 2: Implement the migration
• Step 3: Run the migration

Step 1: Generate an empty migration

Generate an empty migration using the command:

For example:

On success, this generates an empty migration in the directory. You can use the command to display all migrations created on an environment:

Please note that the name you provide will be prefixed with a UTC timestamp that looks like this: . In this example, the file created will be named something like this: .
This value is used to keep the migrations in order in all environments. Please do not change this value by hand; do not skip this step by simply adding a file in the directory because it may cause errors.

Step 2: Implement the migration

Use the Liquid markup in migration files, which includes executing GraphQL mutations (graphql tag). You can sync a migration file many times. For example, you can put the following mutation into the file created by the command in step 1:

Step 3: Run the migration

The deployment will upload and try to run migrations one by one (ordered by timestamp). 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 option. The command starts a background process that runs a single migration:

For example:

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 the command), it progresses to either done (on success) or error status.

You can check the status of all migrations using the command.

Once a migration is in the done status, you can't run it 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 your site's performance, we encourage using LINK Data Import/Export for any larger data processing jobs. Migrations are best for seeding data and making minor changes to a Table.