The right way to migrate your content using the Contentful Migration CLI
What is the best way to automate your release process? That’s a question that many developers face. Our answer is the Contentful Migration Command Line Interface (CLI).
With the Contentful Migration CLI, we offer a framework that makes migrations easy and that also makes it possible for developers to script changes to their content model in a fine-grained way. All in the name of making your development process with Contentful as easy as possible.
You can, for example, use this tool together with a continuous integration service, like , to run migration scripts on a predefined test space as part of a test suite. This is so that you can validate the deployment before it gets pushed into production.
Not using Contentful yet? Sign up for your free account and start building in minutes.
How the Contentful Migration CLI works
You can use the new Contentful migrations framework for every step of the process: like for creating a new content type, adding a field, or changing validations on a field.
Using JavaScript, you can utilize the Contentful Migration CLI to create migration scripts describing changes to a content model, and then run these scripts on a given Contentful space by using the command line.
Upon execution, the migration CLI does the following:
Parses your script
Validates your script for syntax or consistency issues
Shows you an execution plan, that you then accept if everything looks ok
Applies the migration to the space that you specified, once the input has been validated and approved
How to install the Contentful Migration CLI
To install the contentful migration CLI, you need to have Node.js installed, and run the following command:
npm install -g contentful-migration-cli
After the installation is complete, you’ll need to set up and export the following environment variables:
CONTENTFUL_MANAGEMENT_ACCESS_TOKEN–– The personal access token for accessing the CMA.HTTP_PROXYorhttp_proxy(optional) –– The settings for the HTTP proxy in the shape ofhttp://[user:password@]<host>[:port].HTTPS_PROXYorhttps_proxy(optional) –– The settings for the HTTPS proxy in the shape ofhttps://[user:password@]<host>[:port].
If you have previously installed the Contentful CLI then these will be automatically picked up from your ~/.contentfulrc.json configuration file.
Please note that the environment variables will take precedence over the ~/.contentfulrc.json configuration.
An example of content model migration
Consider the following content model:
You can download and import this as an example space by using contentful-import:
Imagine an application which uses this data model, and you decide you want to add an Author field — which is defined in a separate content type. The data model, once migrated, will look like so:
So let’s say we create a migration script called 01-add-author.js with the following content:
For more information about the available functions, see the contentful-migration reference documentation.
We then kick off the migration:
contentful-migration --space-id $YOUR_SPACE_ID 01-add-author.js
What we will then see is the following migration plan:
Since everything looks the way we want it to, we’ll go ahead with the migration:
How to validate migrations
In order to prevent as many errors as possible, the migration executor performs some sanity checks on migration files. The sanity checks include:
Syntax: typos, invalid properties, wrong types
Consistency: create a content type or field that already exists, delete a field or edit a content type that doesn’t exist, etc.
All types of validation errors are listed in the reference documentation.
Whenever a validation issue is detected, the contentful-migration command displays details of the error, including the line number within the script where the problem originates from:
What’s next
The Contentful Migration CLI is still in its early stages. And we will expand the framework in the near future to also cover content transformation, and integrate it in our main CLI.
We’re always keen to get your feedback, so feel free to reach out if you have ideas, remarks or if you are experiencing issues. You can connect with us via our Slack community channel at contentful.com/slack or by writing to devrel@contentful.com.
And if you enjoy using Contentful, tell your friends so they can benefit too. Anyone can sign up for a free Contentful account and start building in minutes.
