This quickstart shows how to install the Hygraph Management SDK, authenticate against your project, and apply schema changes programmatically.

You will start with a simple schema change, then learn how to group changes using a batch migration, which is the recommended approach for most production workflows.

By the end of this guide, you will learn how to:

• Install the Management SDK
• Create a Management SDK client
• Apply a schema change
• Apply multiple changes using a batch migration

#Prerequisites

Before you begin, make sure you have:

• A Hygraph project
• A Permanent Auth Token with Management API permissions
• Node.js 18 or later

#Install the SDK

Install the Management SDK package via npm:

npm install @hygraph/management-sdk

#Create a Management SDK client

Create a new file, for example management.ts, and initialize the client with the following parameters:

import { Client } from '@hygraph/management-sdk';

const client = new Client({
  authToken,
  endpoint,
  name, // optional
});

For more information, read this document.

#Add a model

The Management SDK schedules changes when methods are called. Changes are applied when you call run().

The following example creates a simple content model:

client.createModel({
  apiId: 'Product',
  apiIdPlural: 'Products',
  displayName: 'Product'
})

If the model already exists, this call will fail.

#Add a field to the model

Next, add a field to the model:

client.createSimpleField({
  parentApiId: 'Product',
  apiId: 'name',
  displayName: 'Name',
  type: SimpleFieldType.STRING,
  isRequired: true
})

#Dry run a migration

The SDK supports a dryRun mode. We highly recommend using this to inspect the changes array and validate your logic before committing changes to a production environment. A migration can be dry run to preview what changes would be applied.

const changes = client.dryRun();

console.log(changes);

Inspect the changes array and validate the list of operations that will be applied to the target environment.

#Run a migration in production

The run() method submits all scheduled operations. It collects operations from createModel(), createSimpleField(), applySchemaChanges(), and submits them as a batch. The run() method executes all operations atomically. All operations succeed or fail together.

async run(foreground: boolean = true): Promise<MigrationInfo>

Returns a MigrationInfo object with the following properties:

You can call the run() method only once per client instance. A subsequent call returns an error: Migration has already been executed.

#Full example

import { Client, SimpleFieldType } from '@hygraph/management-sdk';

const client = new Client({
  authToken: '<Permanent auth token>',
  endpoint: '<Content API endpoint>',
});

client.createModel({
    apiId: 'Product',
    apiIdPlural: 'Products',
    displayName: 'Product',
  });

client.createSimpleField({
    parentApiId: 'Product',
    apiId: 'name',
    displayName: 'Name',
    type: SimpleFieldType.STRING,
    isRequired: true,
  });

const result = await client.run(true);
if (result.errors) {
  throw new Error(result.errors);
}

console.log(result);

#Check migration status

1. Navigate to the API Playground in your Hygraph project.
2. In the API selector dropdown, select the Management API.
3. Run the following query to check migration status:

query MyQuery {
  viewer {
    project(id: "<project-id>") {
      environment(name: "<environment-name>") {
        migrations {
          id
          status
          name
          errors
          createdAt
        }
      }
    }
  }
}

#Verify changes in Studio

After running the script, to verify the changes:

1. Open your Hygraph project.
2. Navigate to Schema.
3. Confirm that the Product model with the name field exists.

#Supported operations

All operations that can be executed by the SDK are listed in the TypeScript Type Definitions, Client.d.ts file.

#Migrate from the previous SDK

To migrate from the previous SDK, which can be found here, there are a couple of changes that need to be made in order to use it with existing migration scripts.

The old SDK has been deprecated but won't be removed from NPM, so old scripts using it will still work in the future. New features, though, will only be available in the new SDK.

First of all the import of the NPM package has to be changed. For this, the package name needs to be changed to @hygraph/management-sdk. In the previous version, the SDK offered a named export newMigration that could be used to create a new migration. This changed with the new version, so a new migration must be created as follows:

import { Client } from '@hygraph/management-sdk';

const migration = new Client({
  authToken: '...',
  endpoint: '...',
});

The general methods on the migration class stayed the same. So running or performing a dryRun will still work as before.

The major change are the operations that are supported to actually execute changes:

Before, the SDK was built in a fluent API style. This means you could chain operations like the following:

migration
  .createModel({
    apiId: 'Author',
    apiIdPlural: 'Authors',
    displayName: 'Author',
  })
  .addSimpleField({
    apiId: 'firstName',
    displayName: 'First Name',
    type: FieldType.String,
  });

The new SDK version no longer supports chaining. The reason behind that is that the SDK is now fully generated by the schema it is using to execute the migration. The previous example needs to be changed as follows:

migration.createModel({
  apiId: 'Post',
  apiIdPlural: 'Posts',
  displayName: 'Post',
});
migration.createSimpleField({
  apiId: 'firstName',
  displayName: 'First Name',
  type: SimpleFieldType.STRING,
  modelApiId: 'Post',
});

To link the second operation to the first one, that is, to create the field on the created model in the first operation, you need to pass the modelApiId into the operation.