@graphcms/migration

migration

GraphCMS Migration SDK.

Usage

// import migration library
const { newMigration, FieldType } = require("@graphcms/migration");

// create a new migration for an environment
// using auth token and environment endpoint url.
const migration = newMigration({ authToken, endpoint });

// create model
const author = migration.createModel({
  apiId: "Author",
  apiIdPlural: "Authors",
  displayName: "Author",
});

// add fields
author.addSimpleField({
  apiId: "firstName",
  displayName: "First Name",
  type: FieldType.String,
});
author.addSimpleField({
  apiId: "lastName",
  displayName: "Last Name",
  type: FieldType.String,
});

// run migration
migration.run();

Table of Contents

• Migration
  • New Migration
  • Running a Migration
  • DryRun a Migration
• Updating an Entity
• Locale
  • Creating a Locale
  • Updating a Locale
  • Deleting a Locale
• Stage
  • Creating a Stage
  • Updating a Stage
  • Deleting a Stage
• Enumerations
  • Creating Enumeration
  • Updating Enumeration
  • Deleting Enumeration
• Remote Type Definitions
  • Creating Remote Type Definition
  • Updating Remote Type Definition
  • Deleting Remote Type Definition
• Models
  • Creating a Model
  • Updating a Model
  • Deleting a Model
  • Fields
    • Creating a Field
    • Updating a Field
    • Deleting a Field

Migration

New Migration

A migration is scoped to an environment. To create a migration, the following parameters are required.

• Authentication Token authToken.

  Can be retrieved from Settings > API Access on https://app.graphcms.com

• Environment URL endpoint.

  Can be retrieved from Settings > Environments on https://app.graphcms.com

• Migration Name name [optional].

  Every migration has a unique name. If unspecified, a name would be generated and will be part of the response of a successful migration.

  Subsequent migrations with same name will fail.

const { newMigration } = require("@graphcms/migration");
const migration = newMigration({
  authToken,
  endpoint,
  name, // optional
});

Running a Migration

The run method runs the migration.

By default, migrations run in the background. Passing an optional boolean argument configures the migration to run in the foreground.

const foreground = true;
const result = migration.run(foreground);
if (result.errors) {
  console.log(result.errors);
} else {
  console.log(result.name);
}

Dry Run a Migration

A migration can be dry run to preview what changes would be applied.

const changes = migration.dryRun();
console.log(changes);

Updating an Entity

To update properties, specify the properties to be updated. All ommitted properties remain unmodified.

As a special case, apiId is a requirement because all entities are uniquely indentified by apiId.

To update the apiId, specify newApiId.

Locale

Creating a Locale

To create a locale

migration.createLocale({
  apiId,
  displayName,
  description,
});

Updating a Locale

To update a locale

migration.updateLocale({
  apiId,
  ... // properties to update
});

Deleting a Locale

To delete a locale

migration.deleteLocale(apiId);

Stage

Creating a Stage

To create a stage

migration.createStage({
  apiId,
  displayName,
  description,
  isDefault,
  allowQueries,
  color,
});

Updating a Stage

To update a stage

migration.updateStage({
  apiId,
  ... // properties to update
});

Deleting a Stage

To delete a Stage

migration.deleteStage(apiId);

Enumerations

Creating an Enumeration

Create an enumeration with values.

const colors = migration.createEnumeration({
  apiId,
  displayName,
  description,
});
// add values
colors.addValue("Red");
colors.addValue("Green");
// or add multiple values at a time.
colors.addValue("Blue", "Yellow");

Updating an Enumeration

Updating an enumeration and it's values.

const colors = migration.updateEnumeration({
  apiId,
  ... // properties to update.
});
colors.addValue("Black"); // add a new value
colors.updateValue("Red", "Dark Red"); // update existing value
colors.deleteValue("Blue"); // delete value

Deleting Enumeration

To delete an enumeration and it's values

migration.deleteEnumeration(apiId);

Remote Type Definitions

Creating a Remote Type Definition

Create a sample Remote Type Definition for Github API.

migration.createRemoteTypeDefinition({
  definition:
    "type Github { id: Int!, login: String!, name: String!, company: String, bio: String, blog: String, location: String }",
  displayName: "Github profile",
  description: "Developer's Github profile",
});

Updating a Remote Type Definition

To update a Remote Type Definition

migration.updateRemoteTypeDefinition({
  apiId:
  ... // properties to update
});

Deleting a Remote Type Definition

To delete a Remote Type Definition

migration.deleteRemoteTypeDefinition(apiId);

Models

Creating a Model

A model can be created by passing in the required parameters.

const modelName = migration.createModel({
  apiId, // must start with upper case letter
  apiIdPlural, // must start with upper case letter
  displayName,
  description,
});

Updating a Model

To update a model

migration.updateModel({
  apiId, // required
  ... // properties to update
});

Deleting a Model

To delete a model

migration.deleteModel(apiId);

Fields

Create Field

To create a simple field.

const { FieldType } = require("@graphcms/migration");
model.addSimpleField({
  apiId,
  displayName,
  type: FieldType.String,
});

To create an enumerable field.

model.addEnumerableField({
  apiId,
  displayName,
  enumerationApiId, // previously created enumeration.
});

To create a relational field.

const { RelationType } = require("@graphcms/migration");
model.addRelationalField({
  apiId,
  displayName,
  relationType: RelationType.OneToOne,
  model, // the related model

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

To create an asset field.

model.addRelationalField({
  apiId,
  displayName,
  model: "Asset", // this is compulsory to indicate Asset field.

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

To create a union field.

const { RelationType } = require("@graphcms/migration");
model.addUnionField({
  apiId,
  displayName,
  relationType: RelationType.OneToOne,
  models, // list of related models

  // optional but can be specified to customize the details.
  reverseField: {
    apiId,
    displayName,
  },
});

To create a remote field.

model.addRemoteField({
  apiId,
  displayName,
  remoteConfig: {
    method, // one of GET (default), POST or PUT.
    payloadFields, // Array<String> of fields to send as part of request payload
    returnType, // previously declared remote type definition
    url, // url to fetch the remote data from
  },
});

Update Field

To update a field, firstly retrieve the model.

const model = migration.updateModel({...}) // to update the model
const model = migration.model(apiId) // to only retrieve the model

Updating simple field

model.updateSimpleField({
  apiId,
  ... // properties to update
})

Updating enumerable field

model.updateEnumerableField({
  apiId,
  ... // properties to update
})

Updating relational field

model.updateRelationalField({
  apiId,
  ... // properties to update
})

Updating union field

model.updateRelationalField({
  apiId,
  models, // list of related models
  ... // properties to update
})

Deleting a Field

To delete a field

model.deleteField(apiId);

API Docs

SDK docs is available at https://graphcms.com/docs/sdk.

The SDK is fully typed with Typescript and IDE intellisense is expected to work as desired.