Migrating from SpiceDB to SpiceDB

This section covers migrating data from one SpiceDB instance to another with minimal downtime. For example, when migrating to AuthZed Cloud .

If you need information about migrating the schema of a datastore underlying SpiceDB, like Postgres or CockroachDB, go here. If you need information about making changes to a SpiceDB schema that result in a migration, go here.

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.

Pre-requisites

Options

With Write Downtime Migration

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

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

With Near Zero Write Downtime Migration

This option involves more complexity than the above option but minimizes the write downtime.

Spin up your new SpiceDB.
Run zed backup create <filename> against your old SpiceDB.
Run zed backup restore <filename> against the new SpiceDB with the backup file generated by the previous command.
Run zed backup parse-revision <filename> to get the zed token that points to the backup revision.
Using the SpiceDB client of your choice, write a script that calls the Watch API continuously and, for every relationship change read from the old SpiceDB, writes them to the new SpiceDB. In the first API call made you should provide the zed token that you obtained in the previous request as the optional_start_cursor in the WatchRequest object. The script needs to run until you are ready to stop writes on the old SpiceDB.
Stop writes to the old SpiceDB.
Wait until the script receives no more changes (this is when write downtime will occur).
Switch reads and writes to the new SpiceDB.