Overview
As our platforms continue to scale internationally, demand for sanity data migrations has increased and has put more pressure on the engineering side as this was previously a technical task.
This tool grants the following benefits:
Brand/region content teams are now able to create, test, and push their own data within Sanity.
Automatically pulls in all references documents and assets preventing failed data migrations due to missing children references.
More tactical than the current implementation wherein we need to move documents by type - meaning if we want to move a single offer, we currently need to move all offer documents and all possible child reference document types.
Time to move data is reduced tremendously. To move one static page to production or QA, it now takes 10 seconds, where it used to take up to 20 mins (depending on dataset size).
Content Managers
For each brand/region, there is one designated “owner” who is responsible for migrating sanity data.
Burger King
...
Primary Owner
...
Secondary Owner
...
Region
...
...
...
US 🇺🇸
...
...
CA 🇨🇦
...
...
CH 🇨🇭
...
...
DE 🇩🇪
...
...
ZA 🇿🇦
...
...
GB 🇬🇧
Popeyes
...
Primary Owner
...
Secondary Owner
...
Region
...
...
...
US 🇺🇸
...
...
TBD
...
CA 🇨🇦
...
...
TBD
...
CH 🇨🇭
Tim Hortons
...
Primary Owner
...
Secondary Owner
...
Region
...
...
TBD
...
US 🇺🇸
...
...
...
CA 🇨🇦
Ground Rules
...
What are Sanity Migrations?
Sanity Migrations allow you to independently migrate content from Staging to different environments. You can therefore implement changes in Staging environment, test them, and afterwards push those changes to QA and Production.
All this is accomplished with some clicks in the User Interface of Sanity.
| Note |
|---|
You will need a write token in order to use this tool. If |
...
don’t have one, request it from |
...
your Customer Success Manager contact. Make sure to save it locally on your computer so you can re-use it |
...
, but please DO NOT SHARE THIS TOKEN, as it is a user-specific token. |
...
There should be one primary point of contact that is in charge of migrations for each brand/region, and one additional fallback migration owner in case the primary owner is out of office.
...
Migrate data first to QA, validate the changes there, then move it from staging to production (the tool will only let you migrate from staging as staging is the source of truth).
Using the Document Action
Content creators are already accustomed to using document actions such as Publish or Delete. The document action works in a similar fashion to these actions:
...
Paste in your token…
...
Select destination dataset (always move QA first and validate before moving to production)…
...
Scroll down and click the migrate button, and wait for the migration to finish. Do not close this window!
...
When the migration is complete you will see a success message, if it errors, please reach out to Posk, Mitchell (Deactivated) in the #sanity-data-migration-owners slack channel.
...
Using the Tool
Content can be migrated in two different ways:
Using a GROQ query in the Migration tool
Individually migrating a document
| Info |
|---|
Staging should always be the source of truth to migrate changes to other environments (e.g. staging → production) |
1. Migration tool
The migration tool can be found on the top navigation menu in Sanity. The Migration tool allows you to migrate multiple documents using a GROQ query, as opposed to only moving the currently viewed document (both tools also move children references). In terms of functionality, the actual migration tool works the same as the document action.
...
If you are unfamiliar with GROQ queries, you can see some of the most used patterns here.
Future Improvements
...
Once you input your token, you’ll be prompted to input a GROQ query that refer to the document you’d like to move:
...
Below you can find the most used queries for your use:
MIGRATES WHOLE MENU BUT DOES NOT INCLUDE OFFERS:
*[_id in ["feature-menu-singleton"]][0..10000]MIGRATES ALL OFFERS:
*[_id in ["feature-offers-singleton"]][0..10000]MIGRATES ALL STATIC PAGES:
*[_type in ["staticPage"]][0..10000]PUSHES WHAT WE SHOW ON THE HOMEPAGE:
*[_id in ["feature-home-page-singleton"]][0..10000]UPDATES ONLY MARKETING TILES:
*[_type in ["marketingTile", "marketingTileGroup"]][0..10000]MIGRATE ALL DOCUMENTS WITH TYPE ‘ITEM’:
*[_type in ["item"]][0..10000]MIGRATES ALL DOCUMENTS WITH TYPE ‘OFFER’:
*[_type in ["offers"]][0..10000]
MIGRATE ALL INFORMATION:
*[]
You can also build your own GROQ queries, more information on GROQ here.
| Info |
|---|
This process will also move children documents associated to the documents you’re migrating |
Once you’ve inputted your query, you’ll need to select your destination dataset – typically prod_[brand]_[country].
...
After that you can click on “Migrate”. When the migration is done, you should get a message indicating "Migration Successfully Complete!”
...
If instead you get an error, please open a ticket following this guide: Reporting Bugs - Service Desk
2. Individual document migration
If you’d like to only migrate a specific document, you can make use of the document migration feature.
| Info |
|---|
This process will also move children documents associated to the document you’re migrating |
Next to the Publish button you’ll find a dropdown menu with the option "Migrate”:
...
Upon clicking on that option, you’ll be prompted to input your token:
...
Similarly to the migration tool process, you’ll need to select the destination dataset.
| Info |
|---|
If there’s no changes to migrate to the destination dataset, the “Migrate” button will be grayed out and instead you will see a message indicating that there’s nothing to migrate. |
...
If there’s changes to migrate, click on the “Migrate” button and wait for the migration to finish. Do not close the pop-up until the migration is complete.
...
After that you can click on “Migrate”. When the migration is done, you should get a message indicating "Migration Successfully Complete!”
...
If instead you get an error, please open a ticket following this guide: Reporting Bugs - Service Desk