Environments and migrations > Write and test migration scripts

    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:

    $ dato new migration 'create article model'
    Created migrations/1591173668_createArticleModel.js

    This will create a file named <TIMESTAMP>_createArticleModel.js inside a migrations directory. If the directory does not exist, it will be created as well.

    Let's take a look a the content of the migration script:

    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',
    apiKey: 'article',
    // Create a Title field (required):
    // https://www.datocms.com/docs/content-management-api/resources/field/create
    const titleField = await client.fields.create(articleModel.id, {
    label: 'Title',
    apiKey: 'title',
    fieldType: 'string',
    validators: {
    required: {},
    appearance: {
    editor: 'single_line',
    parameters: {
    heading: true,
    addons: [],
    // Create an Article record:
    // https://www.datocms.com/docs/content-management-api/resources/item/create
    const article = await client.items.create({
    itemType: articleModel.id,
    title: 'My first article!',

    The script exports an async function with a client argument, which is an already initialized 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.

    If you would like to provide your custom template instead of the default migration template, you can run this command and provide your own:

    $ dato new migration 'testing custom templates' --migrationTemplate=./relative-path-to/template.js

    Running the migration script

    To execute the migration, run the following command:

    $ dato migrate --destination=feature-add-article-model

    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 track which migrations have already run in a specific environment, the CLI creates a special schema_migration model. After each migration script completes, it creates a record referencing the name of the script itself.

    To verify this behaviour, we can re-run the migrations and see the result. Since the sandbox environment feature-add-article-model already exists, the tool will fail:

    $ dato migrate --destination=feature-add-article-model
    ✖ Creating a fork of `original` called `feature-add-article-model`...
    Error: `feature-add-article-model` already exists! If you want to run
    the migrations inside this existing environment you can add the --inPlace flag.

    We can request the tool to run some migrations in an existing sandbox environment passing it as the --source argument, and specifying the --inPlace flag:

    $ dato migrate --source=feature-add-article-model --inPlace
    Migrations will be run in sandbox env `feature-add-article-model`... done!

    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:

    $ dato new migration addAuthors
    Created migrations/1591176768_addAuthors.js

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

    module.exports = async (client) => {
    // Create the `author` model
    const authrModel = await client.itemTypes.create({ name: 'Author', apiKey: 'author' });
    // Add a `name` field to the `author` model
    await client.fields.create('author', {
    label: 'Name',
    apiKey: 'name',
    fieldType: 'string',
    validators: {
    required: {},
    // Add an `author` field to the `article` model
    await client.fields.create('article', {
    label: 'Author',
    apiKey: 'author',
    fieldType: 'link',
    validators: {
    itemItemType: { itemTypes: [authorModel.id] },
    // Create an `author` record
    const authorRecord = await client.items.create({
    itemType: authorModel.id,
    name: 'Mark Smith',
    // Set the `author` field on every existing article
    const allArticles = await client.items.all(
    { filter: { type: 'article' } },
    { allPages: true }
    for (const article of allArticles) {
    await client.items.update(article.id, {
    author: authorRecord.id,

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

    $ dato migrate --source=feature-add-article-model --inPlace
    Migrations will be run in sandbox env `feature-add-article-model`...
    ✖ Running 1591176768_addAuthors.js...
    (node:2207) UnhandledPromiseRejectionWarning: ReferenceError: authorModel is not defined
    at module.exports (/Users/stefanoverna/dato/migrations-example/migrations/1591176768_addAuthors.js:21:35)

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

    module.exports = async (client) => {
    // Create the `author` model
    const authrModel = await client.itemTypes.create({ name: 'Author', apiKey: 'author' });

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

    $ dato migrate --destination=feature-add-article-model
    ✔ Creating a fork of `original` called `feature-add-article-model`...
    ✔ Creating `schema_migration` model...
    ✔ Running 1591173668_createArticleModel.js...
    ✔ Running 1591176768_addAuthors.js...

    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 of the primary one. As an example, if you're using our GraphQL Content Delivery API, you can explicitely read data from a specific environment using one of the following endpoints instead of the regular ones:


    Once everything is working as expected, we move on and ship everything in 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:

    $ dato environment destroy sandbox-name