Datastore Migrations

Like all actively developed software, SpiceDB has new versions of the software released on a regular cadence. Updates are published to the SpiceDB GitHub releases page and announced via Twitter and Discord .

Transitioning between versions is often as simple as executing a new binary or container, but there are times when updates are more complex. Releases that include changes to datastore (for example, adding a new index) can require that users run a command to update the datastore version.

This page explains migrating the schema of a datastore underlying SpiceDB. If you need information about migrating between SpiceDB instances, go here. If you need information about making changes to a SpiceDB schema that result in a migration, go here.

Overview

Before a datastore can be used by SpiceDB or before running a new version of SpiceDB, you must execute all available migrations.

All datastores supported by SpiceDB (CockroachDB, MySQL, etc) support migrations. The only exception is the memdb datastore because it does not persist any data.

For this purpose, the SpiceDB binary contains a migration command, spicedb datastore migrate. To migrate your datastore to the latest revision, run the following command with your desired values:


spicedb datastore migrate head \
    --datastore-engine $DESIRED_ENGINE \
    --datastore-conn-uri $CONNECTION_STRING

In most cases, this command will not actually cause downtime, but one should confirm that’s the case in a non-production environment before executing on production environments with uptime requirements.

Migration Compatibility

On startup, SpiceDB checks to see whether its desired datastore migration tag matches the migration tag held in the datastore itself. If they differ, SpiceDB will error out. SpiceDB only performs this check on startup, which means that a new datastore migration won’t cause existing SpiceDB instances to break (unless they restart for other reasons), provided that the DDL is compatible with the existing instance.

SpiceDB strives to main compatibility across each version and its following minor version. When doing a major version update, we recommend reading the Upgrade Notes of the target release to see if any additional steps are required on your side.

Using the SpiceDB Operator is the easiest way to ensure that all datastore migrations are compatible and applied correctly.

Overriding Migration Compatibility

Under some circumstances, you may want to run a version of SpiceDB against a datastore migration other than the one it’s expecting. If you know that the version of SpiceDB you want to run is compatible with the datastore migration, you can use the --datastore-allowed-migrations flag on spicedb serve to provide a list of compatible DB migrations:


spicedb serve <...> \
  --datastore-allowed-migrations add-expiration-support \
  --datastore-allowed-migrations add-transaction-metadata-table

More information on the use case/motivation is available in this issue .

Recommendations

Managed Service

Rather than handling updates yourself, SpiceDB is offered as a managed service .

AuthZed Dedicated users can select the desired version of SpiceDB

No matter which service you select, zero-downtime migrations are always performed.

Operator

If you are operating SpiceDB yourself, the recommended update workflow is to use the SpiceDB Operator. Please see the operator-specific update docs for various update options.

Sequential Updates

We highly recommend updating sequentially through SpiceDB minor versions (e.g. 1.0.0 -> 1.1.0) to avoid headaches. Jumping many versions at once might cause you to miss instructions for a particular release that could lead to downtime. The SpiceDB Operator automates this process.

Rolling Deployments

We highly recommend a deployment orchestrator to help coordinate rolling out new instances of SpiceDB without dropping traffic. SpiceDB has been developed with an eye towards running on Kubernetes, but other platforms should be well supported.