The Hygraph Management SDK is a JavaScript-based toolkit that allows users to programmatically manage Hygraph projects, including schema migrations, model creation, field management, and more. It is designed to work with the Management API, enabling code-driven development and CI/CD workflows. See official documentation.
What can I do with the Hygraph Management SDK?
With the Management SDK, you can perform schema changes, create and update models, add various field types (simple, rich text, enumeration, relational, asset, union, remote), run migrations, and automate project scaffolding. It supports dry runs for testing migrations and foreground/background execution modes for deployment. Learn more.
How do I get started with the Hygraph Management SDK?
To get started, install the SDK via NPM (npm install @hygraph/management). You will need your API endpoint and a permanent auth token (PAT) with Management API permissions, which can be found in your project settings. For full instructions, see the Getting Started guide.
What types of fields and models can I create with the Management SDK?
You can create models and add a variety of field types, including simple fields (e.g., strings), rich text fields, enumerations, relational fields, asset fields, union fields, and remote fields. Enumerations must be declared before adding them to models. The SDK supports creating, updating, and deleting models and fields. See examples.
Can I automate schema migrations and CI/CD workflows with the Management SDK?
Yes, the Management SDK is designed for teams embracing CI/CD deployment strategies. You can define schema migrations in code, track changes via version control, and deploy updates programmatically, ensuring consistency and safety across environments. The SDK supports dry runs and foreground/background execution for migration scripts. Read more.
What are the main use cases for the Management SDK?
Main use cases include automating schema migrations for CI/CD, creating reusable agency templates for common content structures, deploying identical feature changes across multiple projects, and bulk content operations such as scaffolding, importing, and updating content. These capabilities help teams save time and reduce manual work. See use cases.
How does the Management SDK improve developer workflows?
The SDK enables code-driven schema management, reducing manual UI work and supporting up/down migration functions for feature development and testing. Developers can automate repetitive tasks, avoid naming collisions, and maintain cleaner version control over schema changes. See migration script example.
Where can I find documentation and examples for the Management SDK?
Comprehensive documentation and examples are available on GitHub and in the Hygraph Documentation. You can also find quickstart guides and migration instructions in the official docs.
Features & Capabilities
Does Hygraph support programmatic schema management?
Yes, Hygraph supports programmatic schema management via the Management SDK, allowing developers to manage entire project schemas through migrations, integrate with CI/CD processes, and automate schema changes directly from their code editor. Learn more.
Can I use the Management SDK with my existing CI/CD pipeline?
Yes, the Management SDK is designed to integrate with existing CI/CD pipelines, enabling automated schema migrations and project management as part of your deployment workflow. See engineering resources.
What is the role of the Management SDK in Hygraph?
The Management SDK allows you to create and manage schemas programmatically, offering flexibility beyond the UI. It is ideal for teams that require repeatable, automated schema changes and want to avoid manual configuration. See how it works.
How do I migrate from the previous SDK to the Management SDK?
Migration instructions are available in the Hygraph API Reference. The documentation provides step-by-step guidance on transitioning from the previous SDK to the Management SDK.
Technical Requirements
What permissions do I need to use the Management SDK?
You need a permanent auth token (PAT) with Management API permissions, which can be generated in your project settings. For some operations, you may also need Environment Read permissions. See setup details.
Is the Management SDK type-safe?
Yes, the Management SDK leverages the type-safe ecosystem, ensuring that schema changes and migrations are validated against your project configuration, reducing errors and improving deployment safety. Learn more.
Support & Implementation
What support and resources are available for Management SDK users?
Hygraph provides extensive documentation, quickstart guides, and migration instructions for the Management SDK. Users can also access 24/7 support via chat, email, and phone, and participate in the community Slack channel for peer assistance. Contact support.
Where can I find examples of using the Management SDK?
Examples are available at Management SDK Examples and in the official documentation. These resources provide practical code samples and migration scripts for common use cases.
Use Cases & Benefits
Who can benefit from using the Hygraph Management SDK?
Developers, agencies, and teams managing complex or multi-market projects benefit most from the Management SDK. It is ideal for those seeking automation, repeatable schema changes, and integration with CI/CD workflows. Agencies can create schema templates for client projects, and enterprises can deploy consistent changes across multiple environments. See use cases.
How does the Management SDK help with multi-market or multi-project deployments?
The SDK enables companies to deploy identical feature changes across multiple projects without manual admin interface work, ensuring consistency and saving time for teams managing content across regions or brands. Learn more.
Pricing & Plans
Is the Management SDK available on all Hygraph plans?
The Management SDK is available to all Hygraph users with access to the Management API. For details on plan features and pricing, visit the Hygraph Pricing page.
Security & Compliance
Is the Management SDK secure and compliant with industry standards?
Hygraph ensures enterprise-grade security and compliance, including SOC 2 Type 2, ISO 27001, and GDPR certifications. The Management SDK operates within these standards, leveraging secure authentication and permissions. See security features.
Every Hygraph user has access to two APIs, the Management API is for managing projects, content models, fields, and all their associated settings. The Content API is for content management, creating, updating, deleting, and reading content out of a specific project.
Written by Michael, Abiola & Jamie
on Dec 10, 2020
Every Hygraph user has access to two APIs, the Management API is for managing projects, content models, fields and all associated settings. The Content API is for content management, creating, updating, deleting, and reading content out of a specific project.
The interface for these APIs is GraphQL. For as flexible as GraphQL is, many teams prefer to work with code driven development where changes to a schema are tracked via version controlled migration statements.
To assist in this style of development, we are rolling out the Hygraph Management Software Development Kit (SDK) - which allows you to define schema migrations using JavaScript and apply those changes programmatically.
The management SDK works with permanent auth tokens scoped to individual projects. Currently, you can use the SDK to perform schema changes to your project. Further additions such as user provisioning will follow.
In short, the primary use-case is teams embracing CI/CD deployment strategies. Leveraging the larger type-safe ecosystem and a code driven development approach, you can ship features to market with more safety guaranteed because all your content will be checked against schema changes you plan to deploy with the code.
But the use cases extend beyond just CI/CD. You can also define agency templates where you repeat a common set of use-cases such as author/post relations, product catalogs and more, and simply migrate them into a new project much as you would a plugin eco-system, removing most of the manual work involved.
Companies running multi-market projects where collocating content was not allowed for one reason or another can also deploy identical feature changes across multiple projects without having to touch the admin interface.
Combined with our existing mutation and query Content APIs, you can leverage powerful automation to scaffold projects, import sample content, make bulk changes en masse and so much more.
We need to import, instantiate the Management SDK and pass in the management API token along with the endpoint from your project. In the next sections, we’ll add creation of a model, fields, and relationships.
Models follow the same type declaration of the underlying GraphQL schema.
The required fields are the apiId, apiIdPlural and the displayName. We can name this instance for attaching fields to it.
const author = migration.createModel({
apiId:"Author",
apiIdPlural:"Authors",
displayName:"Author",
});
Models support creating, updating, and deleting.
Tip: Run Configuration
The SDK supports running migrations in two additional configurations. Running a “dryRun” will simulate the behavior without executing the changes. You can invoke dryRun with migration.dryRun() instead of migration.run().
The second optional is passing the {foreground: true} configuration object to the run mode. Foreground behaviour polls the Hygraph migration status for a success or error message. The default background behavior simply initiates the migration but doesn’t wait for a response.
You can add several types of fields to the models. You can add enumerable fields (which required first creating an enumeration - see the docs), union fields, relation fields, asset fields, simple fields, and remote fields.
Let’s add a name to our Author. Note, we need to import the FieldType object from the SDK.
author.addSimpleField({
apiId:'name',
displayName:'Name',
type:FieldType.String,
});
Tip: What is Up, What is Down
In software driven migrations, it is common to write “up” migrations where you mutate your data, and a “down” migration where you roll those changes back. This is most commonly used for feature development / testing where removing having to touch the interface would improve the developer workflow and the down migration cleans up after yourself, reducing the chances of naming collisions in the database.
This is typically done by creating two functions called “up” and “down”, where creation/mutation statements reside in the up function and deletion methods reside in the down function.
Let’s add another model and a simple field to our schema to add some more dynamics to our content structure. We’ll add a Model called book and a field called Title.
Let’s add a toggle to our Book to determine if it’s available or unavailable, potentially relevant if we are tracking individual books in a catalog system.
We’ll need to import another object from the SDK, the “RelationType” configurations. We can define the type of relation (cardinality) and the names of the API Id’s on both sides of the relation. Model here is the API Id of the model we created.
book.addRelationalField({
apiId:"author",
displayName:"Author",
relationType:RelationType.ManyToOne,
model:"Author",// the related model
// optional but can be specified to customize the details.
reverseField:{
apiId:"books",
displayName:"Books",
},
});
Finally, run the migration with either the wrapping up/down functions or calling migration.run() and deploy your changes to your live project!