Developers · Data

Migrating Data

Last updated 7 November 2026

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.

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:

[user@host] $ | insites-cli migrations generate ENVIRONMENT MIGRATION_NAME

For example:

[user@host] $ | insites-cli migrations generate local add_some_books

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

[user@host] $ | insites-cli migrations list local

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:

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

Note

Be careful about using deploys with migrations that are not ready, because deployment runs all migrations that are in pending status.

Step 3: Run the migration

Note

You can use deploy or sync, but the migration you want to execute has to be delivered to the target environment first.

The deployment will upload and try to run migrations one by one (ordered by timestamp). It will fail if one of the migrations fails. The command starts a background process that runs a single migration:

[user@host] $ | insites-cli migrations run MIGRATION_TIMESTAMP ENVIRONMENT

For example:

[user@host] $ | insites-cli migrations run 20180909123423 local

Note

For the command, you have to provide the timestamp, not the full name, for example: 20180731120002

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 again - this makes it safer to run the same queue of migrations on all environments.

When an error occurs, check the migration's state and error messages with :

[user@host] $ | insites-cli migrations status 20180909123423 local

Fix the migration file, sync or deploy it, then run it again with . It shows the state first, then runs the migration:

[user@host] $ | insites-cli migrations retry 20180909123423 local

You can edit and rerun a failed migration until it succeeds.

Although migrations are run in a background worker and will not affect your site's performance, we encourage using Data Import/Export for larger data jobs. Migrations are best for seeding data and making minor changes to a Table.