Environments and migrations > Write and test migration scripts

Creating your first migration

For this example, we're starting with a blank DatoCMS project, and then progressively add models/records using migrations. We'll first 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.

The body of the function is already filled with everything we need for this particular example:

• it creates a Article model,

• it adds a Title field to it, and

• it creates a first Article record.

Running the migration script

To execute the migration, run the following command:

$ npx datocms migrations:run --destination=feature-add-article-model --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-add-article-model;

• 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-add-article-model
Migrations will be run in "feature-add-article-model" sandbox environment
Creating a fork of "main" environment called "feature-add-article-model"... !
 ›   Error: Environment "feature-add-article-model" already exists!
 ›   Try this:
 ›     * To execute the migrations inside the existing environment, run "datocms migrations:run --source=feature-add-article-model --in-place"
 ›     * To delete the environment, run "datocms environments:destroy feature-add-article-model"

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

$ npx datocms migrations:run --source=feature-add-article-model --in-place
Migrations will be run in "feature-add-article-model" 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!

Adding a new migration

Let's create a new migration to add a new Author model, and an Author field on the article:

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

Let's replace the content of the new migration file with the following:

/** @param client { import("@datocms/cli/lib/cma-client-node").Client } */
module.exports = async (client) => {
  // Create the `author` model
  const authrModel = await client.itemTypes.create({
    name: 'Author',
    api_key: 'author',
  });
  // Add a `name` field to the `author` model
  await client.fields.create('author', {
    label: 'Name',
    api_key: 'name',
    field_type: 'string',
    validators: {
      required: {},
    },
  });
  // Add an `author` field to the `article` model
  await client.fields.create('article', {
    label: 'Author',
    api_key: 'author',
    field_type: 'link',
    validators: {
      item_item_type: { item_types: [authorModel.id] },
    },
  });
  // Create an `author` record
  const authorRecord = await client.items.create({
    item_type: authorModel,
    name: 'Mark Smith',
  });
  // Set the `author` field on every existing article
  for await (const article of client.items.listPagedIterator({
    filter: { type: 'article' },
  })) {
    await client.items.update(article, {
      author: authorRecord.id,
    });
  }
};

Then run the new script in our existing feature-add-article-model sandbox environment:

$ npx datocms migrations:run --source=feature-add-article-model --in-place --api-token=<YOUR-API-TOKEN>
Migrations will be run in "feature-add-article-model" sandbox environment
Running migration "1653062813_addAuthors.js"... failed!
----
ReferenceError: authorModel is not defined
    at module.exports (/Users/stefanoverna/dato/cli/packages/cli/migrations/1653062813_addAuthors.js:25:37)
    at processTicksAndRejections (internal/process/task_queues.js:95:5)
    at async Command.runMigrationScript (/Users/stefanoverna/dato/cli/packages/cli/lib/commands/migrations/run.js:103:17)
    at async Command.run (/Users/stefanoverna/dato/cli/packages/cli/lib/commands/migrations/run.js:70:13)
    at async Command._run (/Users/stefanoverna/dato/cli/packages/cli-utils/node_modules/@oclif/core/lib/command.js:67:22)
    at async Config.runCommand (/Users/stefanoverna/dato/cli/packages/cli/node_modules/@oclif/core/lib/config/config.js:268:25)
    at async Object.run (/Users/stefanoverna/dato/cli/packages/cli/node_modules/@oclif/core/lib/main.js:73:5)
----
 ›   Error: Migration "1653062813_addAuthors.js" failed

Ouch, seems that there was a typo in our migration script (authrModel instead of authorModel):

/** @param client { import("@datocms/cli/lib/cma-client-node").Client } */
module.exports = async (client) => {
  // Create the `author` model
  const authorModel = await client.itemTypes.create({
    name: 'Author',
    api_key: 'author',
  });

Since we're working on a sandbox, we can just fix the typo, delete the current sandbox, fork a new one from the primary environment and re-run the migrations:

$ npx datocms environments:destroy feature-add-article-model && \
    datocms migrations:run --destination=feature-add-article-model
Destroying environment "feature-add-article-model"... done
Migrations will be run in "feature-add-article-model" sandbox environment
Creating a fork of "main" environment called "feature-add-article-model"... 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 apps to the 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 feature branch, including in the commits also the migration scripts.

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>

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 »