Once we've 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 as primary the sandbox environment we were using to test our migrations, 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.

The safe workflow that DatoCMS suggests to apply migrations to the primary environment is instead the following:

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 on the primary environment. You can do so either from the DatoCMS interface:

Or using the CLI:

$ dato maintenance on
Maintenance mode activated: the primary environment is now read-only

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:

$ dato maintenance on
Cannot activate maintenance mode as some users are currently editing records!
To proceed anyway, please use the --force flag

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

You can now call the dato migrate command to make a new copy of the primary environment, and run all the pending 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...
Done!

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

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

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:

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

Step 4: Promote the sandbox and turn off mainteinance mode

Once everything is ready, you can safely promote the sandbox to be the new primary environment. The old primary environment will be demoted as 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:

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

$ dato maintenance off
Maintenance mode deactivated!

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.