Massive DX improvement: introducing Autogeneration of Migration Scripts

TL;DR Our CLI just became a lot smarter, and can now automatically generate a migration script from the differences between two environments!

Why sandbox environments + migrations are great

Sandbox environments, paired with migration scripts, offer a bullet-proof, predictable and all-encompassing solution to make changes to the structure of your content over time.

They allow your team to safely handle complex and potentally risky scenarios, like developing, testing and then releasing multiple features in parallel on editorial projects that have already been published and are already in use, without disrupting the end-user experience, nor the daily work of the editorial team, and most importantly, with a guarantee that no data will ever be lost.

If you have never tried using them, we strongly suggest you to take a look at the "Safe Iterations Using Environments" page in our docs, which thoroughly explains the risks at stake, and the opportunities they provide.

Problem: writing migration scripts is slow

By manually writing migration scripts though, you loose one of the core strengths of DatoCMS: the convenience of a graphical interface to make changes to content schema.

It is one thing to make changes to the schema by pressing a few buttons, immediately seeing the result in a visual way... and quite another to have to manually write a series of API calls that produce the desired result! 😓

No matter how experienced you can be with our CMA, manually writing migration scripts by hand inevitably takes time.

Let the CLI write migration scripts for you! 🚀

We are thrilled to announce that our CLI can now automatically generate a migration script from the differences between two environments. This is a huge improvement in developer experience that, compounded over the life of a project, can easily save days/weeks of work.

Once you upgrade to the latest version of the CLI, a new --autogenerate option is available on the migrations:new command:

1
$ npm -g update @datocms/cli
2
$ datocms migrations:new --help
3

4
--autogenerate=<value>
5
  Auto-generates script by diffing the schema of two environments
6

7
  Examples:
8

9
  * --autogenerate=foo finds changes made to sandbox environment
10
    'foo' and applies them to primary environment
11

12
  * --autogenerate=foo:bar finds changes made to environment 'foo'
13
    and applies them to environment 'bar'

As the manual suggests, the autogenerate option requires the name of two environments, but if you want to produce a migration script targetting your primary environment — which is often the case — you can just specify the name of the sandbox environment.

A quick tour

To try the new autogenerate option, you can follow these steps:

1. Enter one of your DatoCMS projects, and fork your primary environment (when asked, give the name test to the new sandbox environment);

2. Enter the new sandbox environment, and make some changes through the interface — create a new field, add a validation, delete a model, etc.

3. Run datocms migrations:new 'random changes' --autogenerate=test

In the ./migrations directory of your project, you will find a new migration script containing all the necessary API calls to replicate the changes you made visually during step 2! 🥳

You can verify the result by running the command datocms migrations:run --destination=test2. The command will apply the migration script on a new fork of the primary environment, which in the end of the process should be identical to your test environment.

Docs, gotchas and further development!

Please note that the auto-generation will replicate any change occurred between two environments, with the notable exception of records and uploads, which will be ignored. We might do something about this limitation in future iterations of the tool, after gathering some feedback from the community.

The Environments and Migrations guide has already been rewritten to cover automigrations, so feel free to dig deeper there!

Thank you for your continued support, and see you next time! 👋