Environments and migrations > Write and test migration scripts

Creating your first migration script

For this example, we're starting with a blank DatoCMS project, and then progressively add models/records using migrations.

There are two ways to create a migration script:

1. By writing it manually, or

2. By having the CLI automatically generate it for you.

We'll cover both methods in detail below.

Option 1: Write a migration script manually

Let's create an Article model with a simple Title field. With the CLI tool successfully set up, run the following command inside your project:

$ npx datocms migrations:new 'create article model' --api-token=<YOUR-API-TOKEN>
Created migrations/1591173668_createArticleModel.js

This will create inside your migrations directory a new script named <TIMESTAMP>_createArticleModel.js.

Let's take a look at its content:

'use strict';
/** @param client { import("@datocms/cli/lib/cma-client-node").Client } */
module.exports = async (client) => {
  // DatoCMS migration script
  // For more examples, head to our Content Management API docs:
  // https://www.datocms.com/docs/content-management-api
  // Create an Article model:
  // https://www.datocms.com/docs/content-management-api/resources/item-type/create
  const articleModel = await client.itemTypes.create({
    name: 'Article',
    api_key: 'article',
  });
  // Create a Title field (required):
  // https://www.datocms.com/docs/content-management-api/resources/field/create
  const titleField = await client.fields.create(articleModel, {
    label: 'Title',
    api_key: 'title',
    field_type: 'string',
    validators: {
      required: {},
    },
  });
  // Create an Article record:
  // https://www.datocms.com/docs/content-management-api/resources/item/create
  const article = await client.items.create({
    item_type: articleModel,
    title: 'My first article!',
  });
}

The script exports an async function with a client argument, which is an instance of our Content Management API client.

Incidentally, the body of the function is already filled with everything we need for this particular example, but of course, you can rewrite the migration script to your liking using any method available in our Content Management API to produce the desired results.

Running the migration script

To execute the migration, run the following command:

$ npx datocms migrations:run --destination=feature-branch --api-token=<YOUR-API-TOKEN>

Here's the result:

Upon execution, the command does the following:

• Forks the primary environment into a new sandbox environment called feature-branch;

• Runs any pending migrations inside the sandbox environment.

To verify that only pending migrations are executed, we can re-run the same command and see the result:

$ npx datocms migrations:run --destination=feature-branch
Migrations will be run in "feature-branch" sandbox environment
Creating a fork of "main" environment called "feature-branch"... !
 ›   Error: Environment "feature-branch" already exists!
 ›   Try this:
 ›     * To execute the migrations inside the existing environment, run "datocms migrations:run --source=feature-branch --in-place"
 ›     * To delete the environment, run "datocms environments:destroy feature-branch"

Ouch! The sandbox environment feature-branch already exists, so the command failed. We can follow the CLI suggestion to re-run the migrations inside the already existing sandbox environment:

$ npx datocms migrations:run --source=feature-branch --in-place
Migrations will be run in "feature-branch" sandbox environment
No new migration scripts to run, skipping operation

As you can see, no migration gets executed, as our script has already been run in this environment!

Option 2: Autogenerate a migration script

Let's create a new migration script to add a new Author model, and an Author field on the article. This time, we're going to use the --autogenerate flag on the migrations:new command.

The --autogenerate flag takes two environment names as an argument:

$ npx datocms migrations:new --help
[...]
--autogenerate=<value>
    Auto-generates script by diffing the schema of two environments
    Examples:
    * --autogenerate=foo finds changes made to sandbox environment 'foo' and
    applies them to primary environment
    * --autogenerate=foo:bar finds changes made to environment 'foo' and applies
    them to environment 'bar'

So first we need to make a copy of our feature-branch environment (let's call it with-authors):

$ npx datocms environments:fork feature-branch with-authors
Creating a fork of "feature-branch" called "with-authors"... done

Then add our Author and Author field on the with-authors environment using the regular DatoCMS interface, and then run the following command to generate a migration script:

$ npx datocms migrations:new addAuthors --autogenerate=with-authors:feature-branch --api-token=<YOUR-API-TOKEN>
Writing "migrations/1653062813_addAuthors.js"... done

Let's see the result:

/** @param client { import("@datocms/cli/lib/cma-client-node").Client } */
module.exports = async function (client) {
  const newFields = {};
  const newItemTypes = {};
  const newMenuItems = {};
  console.log('Create new models/block models');
  console.log('Create model "Author" (`author`)');
  newItemTypes['531556'] = await client.itemTypes.create(
    {
      name: 'Author',
      api_key: 'author',
      all_locales_required: true,
      collection_appearance: 'table',
    },
    { skip_menu_item_creation: 'true' },
  );
  console.log('Creating new fields/fieldsets');
  console.log('Create Single-line string field "Name" (`name`) in model "Author" (`author`)');
  newFields['2791804'] = await client.fields.create(newItemTypes['531556'], {
    label: 'Name',
    field_type: 'string',
    api_key: 'name',
    validators: { required: {} },
    appearance: {
      addons: [],
      editor: 'single_line',
      parameters: { heading: true },
      type: 'title',
    },
    default_value: '',
  });
  console.log('Create Single link field "Author" (`author`) in model "Blog Post" (`blog_post`)');
  newFields['2791806'] = await client.fields.create('810907', {
    label: 'Author',
    field_type: 'link',
    api_key: 'author',
    validators: {
      item_item_type: {
        on_publish_with_unpublished_references_strategy: 'fail',
        on_reference_unpublish_strategy: 'delete_references',
        on_reference_delete_strategy: 'delete_references',
        item_types: [newItemTypes['531556'].id],
      },
      required: {},
    },
    appearance: { addons: [], editor: 'link_select', parameters: {} },
  });
  console.log('Finalize models/block models');
  console.log('Update model "Author" (`author`)');
  await client.itemTypes.update(newItemTypes['531556'], {
    title_field: newFields['2791804'],
  });
  console.log('Manage menu items');
  console.log('Create menu item "Authors"');
  newMenuItems['265140'] = await client.menuItems.create({
    label: 'Authors',
    item_type: newItemTypes['531556'],
  });
};

Wow! Thanks CLI, that's a lot of code for free! 😀

If we run the migrations again in our feature-branch environment, we can verify that the script is indeed working:

$ npx datocms migrations:run --source=feature-branch --in-place --api-token=<YOUR-API-TOKEN>
Migrations will be run in "feature-add-article-model" sandbox environment
Running migration "1653062813_addAuthors.js"...
Create new models/block models
Create model "Author" (`author`)
Creating new fields/fieldsets
Create Single-line string field "Name" (`name`) in model "Author" (`author`)
Finalize models/block models
Update model "Author" (`author`)
Manage menu items
Create menu item "Authors"
done

Re-applying a migration script

Suppose that you need to make a change to a migration script after running it.

Since we're working on a sandbox, to test the new script, we can simply delete the current sandbox, fork a new one from the primary environment and re-run the migrations again:

$ npx datocms environments:destroy feature-branch
Destroying environment "feature-branch"... done
$ npx datocms migrations:run --destination=feature-branch
Migrations will be run in "feature-branch" sandbox environment
Creating a fork of "main" environment called "feature-branch"... done
Creating "schema_migration" model... done
Running migration "1653061497_createArticleModel.js"... done
Running migration "1653062813_addAuthors.js"... done
Successfully run 2 migration scripts
Done!

Adapt your website/app to the schema changes

It goes without saying that you also need to work on your website/app to adapt it to the changes you just made. We suggest to work on a Git feature branch, and store the the migrations directory in the same repo as your frontend code.

All of our APIs and integrations offer a way to point to a sandbox environment instead of the primary one.

For example, if you're using our GraphQL Content Delivery API, you can explicitly read data from a specific environment using one of the following endpoints:

https://graphql.datocms.com/environments/{ENVIRONMENT-NAME}
https://graphql.datocms.com/environments/{ENVIRONMENT-NAME}/preview

Once everything is working as expected, we can ship everything production.

Deleting a sandbox environment

After you've run your tests you might need to programmatically delete a sandbox environment.

In this case you can simply run:

$ npx datocms environments:destroy <SANDBOX-ENVIRONMENT-NAME>

Using Fast Fork option for large environments

When working with large environments, a fork process can become slow. To address this issue, DatoCMS offers a "fast fork" option that can be up to 20 times faster than a regular fork. However, it's important to note that during the fork process, the source environment will be kept in read-only mode, which means that other users won't be able to make any changes to its content. This is similar to turning on maintenance mode.

To use the fast fork option, you can select it either from the DatoCMS interface or the CLI.

To run a fast fork on the DatoCMS interface, simply select the "Perform a fast fast fork?" option when creating a fork:

On the CLI, both the migrations:run and the environments:fork commands support an additional flag for the fast fork option.

To use the fast fork option with the migrations:run command, you can run the following command:

$ npx datocms migrations:run --destination=new-sandbox-env --fast-fork

Similarly, to use the fast fork option with the environments:fork command, you can run the following command:

$ npx datocms environments:fork source-env destination-env --fast

Forcing a fast fork

The --force option is used in the CLI to force the start of a fast fork process in any case, even if a user is currently making changes to a record.

To use the --force option, you can add it to the end of the command like this:

$ npx datocms environments:fork source-env destination-env --fast --force
$ npx datocms migrations:run --destination=new-sandbox-env --fast-fork --force

By adding the --force option to the end of the command, you're telling the CLI to proceed with the fast fork process even if there are users making changes to records.

It's important to use the --force option with caution, as it can potentially destroy in-progress work made by other users. It's recommended to communicate with other users and coordinate with them before using the --force option to avoid any issue.

Learn more about migrations

Check out this tutorial on how to migrate your content schema using scripts:

Using scripts to migrate DatoCMS content schema

Play video »