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.
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.
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.
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.
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!
The Admin GraphQL mutation
tsGetSchemaVersionList will return a list
of schema versions with a summary of their contents. It accepts optional
size to limit the size of your
requests. Sorting schemas it not currently supported.
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
To restore your project's schema to a previous version using the API, we
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.