Environments and migrations > Apply migrations to primary environment

    Apply migrations to primary environment

    Once we're done writing and testing our migrations, we need to apply them to the primary environment.

    The first solution that comes to mind would be to simply promote the sandbox environment we were using to test our migrations to primary, but this can be a very dangerous operation, as the primary environment might have diverged from your sandbox environment. That is, some users or webhooks you've set up might have made changes to either the content or the schema of the primary environment after the fork.

    This is instead the safe workflow that we suggest for applying migrations to the primary environment.

    Step 1: Turn on maintenance mode to prevent changes to the primary environment

    The first thing to do is turn on maintenance mode, so that during the process, no one can write new data to the primary environment.

    You can do so either from the DatoCMS interface:

    Or using the CLI:

    $ npx datocms maintenance:on
    Activating maintenance mode... done

    If some users are in the process of editing any record when you launch the command, DatoCMS will warn you and fail the execution of the command. You can force the activation using the --force flag:

    $ npx datocms maintenance:on
    Activating maintenance mode... !
    › Error: Cannot activate maintenance mode as some users are currently editing records
    › Try this: To proceed anyway, use the --force flag

    Step 2: Run the migrations on a newly forked sandbox environment

    You can now call the datocms migrations:run command to make a new copy of the primary environment, and run all the pending migrations:

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

    Notice that, since we're already in Maintenance Mode, we can safely use the --fast-fork flag to run a fast fork, which can be up to 20x faster than the regular fork.

    Step 3: Test your apps pointing them to the new sandbox

    Before promoting the new sandbox as primary, make sure that your website/app is working correctly. All of our integrations offer a way to point to a sandbox instead of the primary environment.

    As an 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 instead of the regular ones:


    Step 4: Promote the sandbox and turn off maintenance mode

    Once everything is ready, you can safely promote the sandbox to be the new primary environment. The old primary environment will be demoted to sandbox, and content editors will immediately see a refresh in the interface. From that moment, they will only be able to see and make changes to the new primary environment.

    From the interface:

    You can also promote an environment to primary via CLI:

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

    When you're ready, you can turn off maintenance mode to allow content editors to return to their regular editorial workflow:

    $ npx datocms maintenance:off
    Deactivating maintenance mode... done

    Handling rollbacks

    In the unfortunate event you deploy some bad code, you can rollback to a prior, known good version of your project simply re-promoting your old primary environment and re-deploying your frontend/apps to the previous state. The effect is immediate, no re-compilation is required.

    Learn more about data migrations

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

    Using scripts to migrate DatoCMS content schema
    Play video »