The new year brought some new cool features to
zed, specifically to backup and restore functionality, so we thought it was a good opportunity to showcase how to use it with your SpiceDB and what the new features look like.
Let's dive right in! 🏊♂️
How SpiceDB Backup / Restore Works
The SpiceDB API exposes two APIs designed to support the ingestion and retrieval of large amounts of data, in addition to the existing CRUD APIs. These APIs are better optimized to support bulk import and export of system data and enable things like disaster recovery or bootstrapping new instances.
You can use the exposed gRPC APIs BulkImportRelationships and BulkExportRelationships to build any functionality you'd like on top of it, but if all you are looking for is a simple backup/restore CLI command to integrate into your workflows, we've got your covered: the
zed CLI tool conveniently exposes functionality to create, restore, extract, and redact backups.
zed keeps all the data in an Apache Avro container which efficiently stores the schema, the snapshot revision of the backup, and relationships at that revision.
Your entry point to the wonders of SpiceDB backups is
zed backup, which will show you the existing sub-commands
Create, restore, and inspect Permissions System backups
zed backup <filename> [flags]
zed backup [command]
create Backup a permission system to a file
parse-relationships Extract the relationships from a backup file
parse-revision Extract the revision from a backup file
parse-schema Extract the schema from a backup file
redact Redact a backup file to remove sensitive information
restore Restore a permission system from a file
createwill start the creation of a backup
restorewill restore the backup into SpiceDB, including schema and relationships
parse-*command allows you to extract data from the backup file. You can pipe it into other processes!
redactwill take a zed backup file, and redact schema definitions, relations, permissions, caveats, and relationship data
How to create a SpiceDB Backup
Creating a SpiceDB backup starts by installing
zed on your machine, which is described here.
Once the command is in place, you should define a "zed context", which defines the connection parameters to a SpiceDB instance. Let's say you have a local SpiceDB instance running:
zed context set dev localhost:50051 my_very_secret_preshared_key --insecure
zed use dev
Make sure everything is working as intended by issuing a
read schema request:
zed schema read
Then creating a backup is as simple as running
zed backup create mybackup
How to restore a SpiceDB Backup
You probably already guessed it, but restoring a SpiceDB backup is pretty simple!
zed backup restore mybackup
The restore command will slice and write the backup data in batches of configurable size, and once it completes, it will show stats of the operation:
Restoring a backup is a write-heavy operation, so zed provides some options to handle errors and conflicts
New Options In SpiceDB Backup Restore
Depending on the type and provisioned capacity of the datastore, restoring a very large SpiceDB backup can take some time, so in the face of a network error, we may lose precious time. Not only that but it can be a hassle to deal with all the relationships provisioned on the initial run, with the system refusing to restore the backup due to the conflicting relationships.
While a restore operation can be done on a live SpiceDB system, the most common scenarios we've seen are:
- seeding a brand new SpiceDB instance
- restoring a snapshot in a different instance for troubleshooting or migration purposes
To help with these tasks,
zed has now some new tricks up its sleeve to help you in your endeavor:
- Handle Conflicts:
--conflict-strategyallows you to define how to handle the conflict that arises when trying to restore a relationship that already exists. The default until now has been to fail the restore operation, but you can now also skip those over, or write them with
touchsemantics instead of
create. The default continues to be
failto honor the original behavior.
- Automatic Retries: Retries on serialization errors are now enabled by default. When the backing datastore returns serialization errors,
zedwill now retry with a backoff by default. It's now enabled by default, but you can go back to the original behavior of failing fast with
- Restore Subsets of a Backup: You can now restore a portion of your backup SpiceDB instance with a prefix filter. This is useful if you have multiple teams working on the same schema and their namespaces are separated by a prefix.
zed backup restore --help
Restore a permission system from a file
zed backup restore <filename> [flags]
--conflict-strategy string strategy used when a conflicting relationship is found. Possible values: fail, skip, touch (default fail)
--disable-retries retries when an errors is determined to be retryable (e.g. serialization errors)
--prefix-filter string include only schema and relationships with a given prefix
As a bonus,
zed backup create also supports the
--prefix-filter, so it will only create a backup of a specific subset of relationships!
How To Obfuscate / Redact A SpiceDB Backup
Sometimes a certain issue can only be reproduced with the state of production data. If only we could use it for your tests or benchmarking. Well, you now can! The new Backup Redaction, available from
zed v0.16.X takes an unredacted backup and obfuscates all the data present in it so you can:
- share it with anyone
- check it into your SCM and use it as part of your CI
- use it for load-testing
- mirror production data in a different system without concerns over customer data
zed backup redact --help
Redact a backup file to remove sensitive information
zed backup redact <filename> [flags]
--redact-definitions redact definitions (default true)
--redact-object-ids redact object IDs (default true)
--redact-relations redact relations (default true)
How To Extract Information From A SpiceDB Backup
Once you have a SpiceDB backup file, you can inspect its contents using
zed tool, and pipe its output into whatever shell workflows you may have built, as it's built with Unix program design principles in mind:
How to extract the schema out of a SpiceDB backup
To print the schema of a SpiceDB backup, run the following command
zed backup parse-schema mybackup
How to extract the snapshot revision out of a SpiceDB backup
To print the snapshot revision of a SpiceDB backup, run the following command
zed backup parse-revision mybackup
How to extract all relationships out of a SpiceDB backup
To print all the relationships present in a SpiceDB backup, run the following command:
zed backup parse-relationships mybackup
Bonus Feature! ⭐ Context-Aware Shell Completion
This is a new backup-adjacent but cool feature that made it's way in the 0.16.0 release.
zed already supports shell completion for the static parts of the CLI, mainly commands and subcommands. But now it also supports shell completion of certain dynamic parts:
zed context usewill autocomplete the various context defined
zed relationshipwill autocomplete resource types, permission names of that resource, and subject types by querying the currently configured
This allows user more effectively construct commands based on the existing schema in your schema. No more back and forth between terminal and schema file!