@graphcms/migration
v0.0.15
Published
SDK for GraphCMS migrations
Downloads
50
Readme
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
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.comEnvironment URL
endpoint
.Can be retrieved from
Settings > Environments
on https://app.graphcms.comMigration 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.