Skip to main content

Viewing and restoring schema versions

Every time a project schema changes, whether you're adding a single field or completely reworking all your shapes, a new version of the schema is created.

We track the entire history of your project schema and make every version available to view, export, and even restore from.

Here, we'll show how you can view and act upon your schema's history from both the web client and the API.

Web Client#

View your project's schema history#

Your project schema's version history is accessible from the Schema tab. From the Schema tab, navigating to the History link will open your schema history.

On the Schema history page, you'll see a table showing the ten most recent versions. For every version, you'll see its version number, when it was created, the number of objects on it, and how that number has changed since the previous version.

Each schema version also provides two actions: restore and export.

Restoring a schema version#

When you restore a previous schema version, a new version is created that copies the version you're restoring against. Schema versions are immutable, meaning we're never updating an old version of the schema, we're always copying a schema, making necessary changes, and saving the new version. This means all previous  versions of your schema still exist and are accessible.

However, it's important to keep in mind that restoring your schema to a different version can potentially changes to your GraphQL API which may introduce downstream breaking changes to any code you've written that depends on a certain state of your API. That's why, after choosing to restore, you'll be prompted with a warning and confirmation dialog about the change you're about to make.

When you're confident to go ahead, click Restore.

After a moment, your project will reload using the restored version and you'll see a newly created version at the top of the history.

Exporting a schema version#

Using the export action will download the schema file for that version. You can use this exported version to fork a new empty project, edit the schema file directly and upload your changes via the CLI, or whatever else you like to do with files.

API#

Using your project's Admin API, you have access to queries and mutations to view your schema history and restore previous versions. In fact, these are the same exact GraphQL requests that the web client uses!

Query for your project's schema history#

The Admin GraphQL mutation tsGetSchemaVersionList will return a list of schema versions with a summary of their contents. It accepts optional pagination arguments from and size to limit the size of your requests. Sorting schemas it not currently supported.

Request

query {
tsGetSchemaVersionList(size: 10) {
total
items {
updated
version
schemaVersion
mutationCount
queryCount
workflowCount
shapeCount
defaultLocale
}
}
}

Response

{
"data": {
"tsGetSchemaVersionList": {
"total": 54,
"items": [
{
"updated": "2020-12-01T17:33:31.758Z",
"version": 54,
"schemaVersion": "3",
"mutationCount": 9,
"queryCount": 4,
"workflowCount": 0,
"shapeCount": 16,
"defaultLocale": "en"
},
...
]
}
}
}

Query for a specific schema version#

There's a separate query to get the contents of a schema at a given version. For that, use the tsGetSchemaVersion admin query. It requires one argument, a version number.

Request

query {
tsGetSchemaVersion(version: 54) {
schema
}
}

Response

{
"data": {
"tsGetSchemaVersion": {
"schema": {
"workflows": {},
"apiVersion": "2",
"defaultLocale": "en",
"locales": [
"en"
],
"projectId": "73e1dce1-77f0-4c3d-86a0-7e3d0389838a",
"schemaVersion": "3",
"version": 54,
...
}
}
}

Restore a specific schema version#

To restore your project's schema to a previous version using the API, we provide the tsRestoreSchemaVersion admin mutation. This accepts the version number of the schema you'd like to restore—and returns the version number of the newly created schema.

Request

mutation {
tsRestoreSchemaVersion(version: 51) {
version
}
}

Response

{
"data": {
"tsRestoreSchemaVersion": {
"version": 55
}
}
}