Ruby Gem for managing your Contentful Migrations

Introducing contentful-migrations.rb

I recently created a gem for managing migrations in Contentful. It works similar to Rails Migrations. For the full docs, view contentful-migrations.rb on github

About Contentful


Contentful is an API-first CMS. It is a great CMS for developers who are trying to push content to multiple environments and apps or developers looking for layout agnostic CMS.

My Contentful Story

I recently had a client that was using a very old version of Radiant CMS as a backend CMS to the customer facing, high traffic website. The original developers had moved all the content into Radiant CMS so the business team could manage it. It was good solution until it wasn’t. The business team and the development team changed over time. There was no training or documentation on how to use the Radiant application. It didn’t help that their version of Radiant did not support any type of search!

Over a period of probably 4 or 5 years, the business stopped using Radiant and when they needed content changed on the site, the developers had to make the change manually in Radiant and at time on multiple environments. The nested structure of the their Radiant CMS content was also very confusing. It would often take developers a non-trivial amount of time to find where a piece of content resided in Radiant.

The developers were very frustrated that they were being asked to update text on the site and the business team was equally annoyed that they had to ask developers to make simple change to the site’s content.

With the company’s Director of Engineering, we began to search for a replacement. One of our main requirements was a CMS that was had no layout opinions. We also wanted a product that would be able to push data that had been changed. As an API-first CMS, Contentful was the winner of a few other products we evaluated. We opened a demo account and did a small proof of concept in a our Rails App using their Contentful.rb Ruby Gem.

Enter Contentful Migrations

As we began migrating our data from the old CMS to Contentful, we ran into coordination and deployment issues. Some of the migrations were done using small rake task and other data was moved in by hand. After storming a bit, I came up with a solution for the team to use a migration pattern similar to Active Record Migration

I used the solution for local development and decided to open source the solution as a gem called contentful-migrations.rb

For Rails developers, the command-line interface should be all too familiar. To generate new migrations, you can do:

rails g contentful_migration my_migration

Running and rolling back the migrations is as simple as:

# forward migrate
rake contentful_migrations:migrate
# rollback migration
rake contentful_migrations:rollback

Shameless Self Promotion

I have sub-contracted with companies that require a integrations across their stack including to a CMS like Contentful. If your company is looking for help from a full stack consultant, get in touch. You can email