Management SDK method for running batch migrations

#Overview

If you have multiple environments, batch migrations let you apply changes directly to production.

This workflow uses Client.getEnvironmentDiff to get the diff, then applies all changes at once. The migration either succeeds completely or fails entirely. This reduces the risk of errors. If any step fails, all changes are undone automatically.

This is the workflow you should follow if you're on the Pro plan, as you only get two environments in total, including master.

Please note that, while this workflow is absolutely fine, it doesn't provide a 100% guarantee against encountering issues because you are applying a new schema to updated content.

#How it works

#Compare environments with getEnvironmentDiff

Use the following method to get the diff:

const diff = client.getEnvironmentDiff("development");

This example considers that you are passing the token of your master environment, and that you are generating a diff comparing it to your development environment. Our Quickstart shows how tokens are passed.

#Apply schema changes using the Management SDK

Use the following method to apply the generated diff to the environment:

client.applySchemaChanges(diff);

#Supported schema elements for batch migrations

The following schema elements are supported:

Models
Components
Locales
Simple fields
Conditional visibility in fields
Relational fields
Enumerations
Enumerable fields
Initial values in enumeration fields
Stages
Union fields
Apps
Custom renderers and app fields
Sidebar elements
Remote fields
Remote type definitions
Remote sources

Not supported yet: UI extensions.

#Limitations of batch migrations in Hygraph

Keep these limitations in mind when using the Management SDK method.

#How schema changes affect the master environment

The Management SDK Method does not merge changes; it replaces them. It first gets a diff to list all the necessary operations to turn the target environment (master) into the source environment (development).to show the operations needed to make the target (master) match the source (development). Then, it applies schema changes by replacing one schema with another. Be aware of this when applying changes to avoid content loss.

If a change in master does not match development, the diff suggests deleting the unrecognized data and creating a new one.

A diff lists operations that make the target schema match the source. Any target changes not in the source will be replaced or overwritten.

This applies to any schema changes to your master environment, such as adding, editing, or deleting models, fields, or sidebar widgets.

Example situation:

Imagine you cloned your master environment last week to create a development environment and have spent some time since then working on development, making changes to the schema. During that time, you also applied schema changes to your master environment, which you did not mirror in development. Later on, when using the Management SDK Method to get the diff and apply the suggested schema changes, the diff will find those differences, and suggest deleting the changes you made to the schema in your master during the last week. Remember it does not merge, but replaces / overwrites.

Once you get the diff, you can apply it as is or, if necessary, edit it manually before applying to avoid content loss in the case of schema changes in the target environment.

Review diff changes before applying them to ensure accuracy. Double-check deletions to prevent content loss.

Suggested workarounds:

Call a content freeze and do not make schema changes to your master.
Every time you make a schema change in your master environment, also add the change to your development environment so the schemas remain the same.
Go over the diff manually and remove all actions deleting models from the schema.