SpiceDB is 100% open source. Please help us by starring our GitHub repo. ↗
SpiceDB Documentation
Managing Data
Migrations

Migrations

Migrating from SpiceDB to SpiceDB

⚠️

Migrating data at the underlying database level is not recommended and impossible in some cases. Using tools like pg_dump/pg_restore will break SpiceDB MVCC. Additionally, if you are migrating to a SpiceDB with a different datastore type (e.g. Postgres -> CockroachDB), you must use the SpiceDB APIs (exportBulk/importBulk or zed backup) to backup and restore.

The options provided below enable you to consistently migrate between datastores with minimal downtime.

All options utilize the Zed CLI tool (opens in a new tab).

Write Downtime Migration

A simple migration that will incur write downtime (not read downtime) for the duration between starting the export and finishing the import.

  1. Spin up your new SpiceDB.
  2. Stop writes to your old SpiceDB.
  3. Run zed backup create <filename> against the old SpiceDB.
  4. Run zed backup restore <filename> against the new SpiceDB with the backup file generated by the previous command.
  5. Switch reads to the new SpiceDB.
  6. Start writing to the new SpiceDB.

Near Zero Downtime Migration

This option involves more complexity than the above option.

  1. Spin up your new SpiceDB.
  2. Run zed backup create <filename> against your old SpiceDB.
  3. Run zed backup restore <filename> against the new SpiceDB with the backup file generated by the previous command.
  4. Obtain the zed token that points to the backup revision with zed backup parse-revision <filename>.
  5. Using the watch API (opens in a new tab), consume relationship changes from the old SpiceDB and write them to the new SpiceDB. You should provide the zed token that you obtained in the previous request as the optional_start_cursor in the WatchRequest. You will need to build a small worker to consume changes and write them to the new SpiceDB. The worker needs to continuously consume changes until you are ready to turn off writes on the old SpiceDB.
  6. Stop writes to the old SpiceDB.
  7. Wait for the worker to process all changes. (this is when write downtime will occur)
  8. Switch reads and writes to the new SpiceDB.
Bulk Importing RelationshipsgRPC API Reference
© 2025 AuthZed.