npm package: @graphcms/migration
Description: SDK for GraphCMS migrations
Author: GraphCMS
Latest version: 0.0.15

# migration

GraphCMS Migration SDK.

## Usage

```js
// 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](#migration)
  - [New Migration](#newMigration)
  - [Running a Migration](#runMigration)
  - [DryRun a Migration](#dryRunMigration)
- [Updating an Entity](#updatingEntity)
- [Locale](#locale)
  - [Creating a Locale](#createLocale)
  - [Updating a Locale](#updateLocale)
  - [Deleting a Locale](#deleteLocale)
- [Stage](#stage)
  - [Creating a Stage](#createStage)
  - [Updating a Stage](#updateStage)
  - [Deleting a Stage](#deleteStage)
- [Enumerations](#enumerations)
  - [Creating Enumeration](#createEnumeration)
  - [Updating Enumeration](#updateEnumeration)
  - [Deleting Enumeration](#deleteEnumeration)
- [Remote Type Definitions](#remoteTypeDef)
  - [Creating Remote Type Definition](#createRemoteTypeDef)
  - [Updating Remote Type Definition](#createRemoteTypeDef)
  - [Deleting Remote Type Definition](#createRemoteTypeDef)
- [Models](#models)
  - [Creating a Model](#createModel)
  - [Updating a Model](#editModel)
  - [Deleting a Model](#deleteModel)
  - [Fields](#fields)
    - [Creating a Field](#createField)
    - [Updating a Field](#updateField)
    - [Deleting a Field](#deleteField)

<a name="migration"></a>

## Migration

<a name="newMigration"></a>

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

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

<a name="runMigration"></a>

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

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

<a name="dryRunMigration"></a>

### Dry Run a Migration

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

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

<a name="updatingEntity"></a>

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

<a name="locale"></a>

## Locale

<a name="createLocale"></a>

### Creating a Locale

To create a locale

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

<a name="updateLocale"></a>

### Updating a Locale

To update a locale

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

<a name="deleteLocale"></a>

### Deleting a Locale

To delete a locale

```js
migration.deleteLocale(apiId);
```

## Stage

<a name="createStage"></a>

### Creating a Stage

To create a stage

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

<a name="updateStage"></a>

### Updating a Stage

To update a stage

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

<a name="deleteStage"></a>

### Deleting a Stage

To delete a Stage

```js
migration.deleteStage(apiId);
```

<a name="enumerations"></a>

## Enumerations

<a name="createEnumeration"></a>

### Creating an Enumeration

Create an enumeration with values.

```js
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");
```

<a name="updateEnumeration"></a>

### Updating an Enumeration

Updating an enumeration and it's values.

```js
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
```

<a name="deleteEnumeration"></a>

### Deleting Enumeration

To delete an enumeration and it's values

```js
migration.deleteEnumeration(apiId);
```

<a name="remoteTypeDef"></a>

## Remote Type Definitions

<a name="createRemoteTypeDef"></a>

### Creating a Remote Type Definition

Create a sample Remote Type Definition for Github API.

```js
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",
});
```

<a name="updateRemoteTypeDef"></a>

### Updating a Remote Type Definition

To update a Remote Type Definition

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

<a name="deleteRemoteTypeDef"></a>

### Deleting a Remote Type Definition

To delete a Remote Type Definition

```js
migration.deleteRemoteTypeDefinition(apiId);
```

<a name="models"></a>

## Models

<a name="createModel"></a>

### Creating a Model

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

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

<a name="updateModel"></a>

### Updating a Model

To update a model

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

<a name="deleteModel"></a>

### Deleting a Model

To delete a model

```js
migration.deleteModel(apiId);
```

<a name="fields"></a>

### Fields

<a name="createField"></a>

#### Create Field

To create a simple field.

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

To create an enumerable field.

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

To create a relational field.

```js
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.

```js
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.

```js
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.

```js
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
  },
});
```

<a name="updateField"></a>

#### Update Field

To update a field, firstly retrieve the model.

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

Updating simple field

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

Updating enumerable field

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

Updating relational field

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

Updating union field

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

<a name="deleteField"></a>

#### Deleting a Field

To delete a field

```js
model.deleteField(apiId);
```

## API Docs

SDK docs is available at [https://graphcms.com/docs/sdk](https://graphcms.com/docs/sdk).

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