What is batch migration in the Hygraph Management SDK?

Batch migration in the Hygraph Management SDK allows you to apply schema changes across multiple environments, such as moving updates from a development environment directly to production. This workflow uses Client.getEnvironmentDiff to compare environments and then applies all changes at once. The migration is atomic—either all changes succeed, or none are applied, reducing the risk of partial updates and errors. If any step fails, all changes are automatically undone.

How does the batch migration workflow work in Hygraph?

The workflow involves using Client.getEnvironmentDiff to generate a diff between your source (e.g., development) and target (e.g., master/production) environments. You then apply the diff using client.applySchemaChanges(diff). The process is atomic—if any step fails, all changes are rolled back. This method is recommended for users on the Pro plan, which supports two environments.

Which schema elements are supported in batch migrations?

Supported schema elements for batch migrations include: 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, and Remote sources. UI extensions are not supported.

What are the limitations of batch migrations in Hygraph?

The Management SDK method does not merge changes—it replaces the target schema with the source schema. Any changes in the target environment (master) not present in the source (development) will be deleted or overwritten. This can lead to content loss if not carefully managed. It is recommended to review the diff before applying changes and consider workarounds such as content freezes or manually syncing schema changes between environments.

How can I avoid content loss during batch migrations?

To avoid content loss, you should: Call a content freeze and avoid making schema changes to your master environment during migration; Ensure any schema changes made in master are also applied to development so schemas remain in sync; Manually review and edit the diff to remove actions that would delete models or fields from the schema. Always double-check deletions in the diff before applying changes.

What are the key capabilities of Hygraph for content management and migration?

Hygraph offers a GraphQL-native Headless CMS with features such as Smart Edge Cache for fast content delivery, high-performance endpoints, content federation, and a user-friendly interface. The Management SDK enables efficient schema migrations and batch updates, supporting operational efficiency and scalability.

Does Hygraph support granular permissions and security features?

Yes, Hygraph provides granular permissions, SSO integrations, audit logs, encryption (at rest and in transit), and regular backups. Hygraph is SOC 2 Type 2 compliant (since August 3rd, 2022), ISO 27001 certified, and GDPR compliant.

How long does it take to implement Hygraph and start using batch migrations?

Implementation time varies by project scope. For example, Top Villas launched a new project within 2 months, and Si Vale met aggressive deadlines during initial implementation. Hygraph offers a free API playground and a free forever developer account for immediate exploration. Structured onboarding includes introduction calls, account provisioning, and technical/content kickoffs.

What support and training resources are available for Hygraph users?

Hygraph provides 24/7 support via chat, email, and phone, real-time troubleshooting through Intercom chat, a community Slack channel, extensive documentation, webinars, live streams, and how-to videos. Enterprise customers receive a dedicated Customer Success Manager and a structured onboarding process.

Who can benefit from using Hygraph and its batch migration capabilities?

Hygraph is ideal for developers, product managers, and marketing teams in industries such as ecommerce, automotive, technology, food and beverage, and manufacturing. It is especially suited for organizations modernizing legacy tech stacks, global enterprises needing localization and asset management, and businesses aiming to streamline content operations and deliver digital experiences at scale.

What problems does Hygraph solve for content teams?

Hygraph addresses operational inefficiencies (reducing developer dependency, streamlining workflows), financial challenges (lowering operational costs, accelerating speed-to-market), and technical issues (simplifying schema evolution, resolving integration and cache problems, improving localization and asset management).

How does Hygraph ensure high performance for content delivery and migrations?

Hygraph uses Smart Edge Cache for enhanced performance and faster content delivery, high-performance endpoints, and measures GraphQL API performance to help developers optimize usage. These features support reliability and speed for high-traffic, global audiences.

What security and compliance certifications does Hygraph have?

Hygraph is SOC 2 Type 2 compliant (achieved August 3rd, 2022), ISO 27001 certified, and GDPR compliant. These certifications ensure robust security and compliance for enterprise customers.

Can you share some customer success stories with Hygraph?

Yes. Komax achieved a 3X faster time-to-market managing over 20,000 product variations across 40+ markets via a single CMS. Autoweb saw a 20% increase in website monetization. Samsung improved customer engagement by 15% with a scalable member platform. Stobag increased online revenue share from 15% to 70%.

How does Hygraph handle maintenance, upgrades, and troubleshooting?

Hygraph is cloud-based, so all deployment, updates, security, and infrastructure maintenance are managed by Hygraph. Upgrades (such as new endpoints and SDK improvements) are integrated seamlessly. Troubleshooting is supported via 24/7 support, Intercom chat, documentation, and an API Playground for self-service. Enterprise customers receive a dedicated Customer Success Manager.

#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: 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.

Frequently Asked Questions

Batch Migration with Hygraph Management SDK