Data migrations are a fact of life for any application. Requirements change, features are added or removed, services are merged together or split apart. As the application evolves, so too must the data behind it. In this regard, the permissions information you store in SpiceDB is no different from any other data in any other database.
If you’re unfamiliar with online migration strategies in general, there are a few good resources online that cover the general topic; we’re going to focus just on SpiceDB and how to perform migrations against the data and schema it holds.
But first, let’s highlight a couple of scenarios where SpiceDB shines because no migrations are needed:
If the services that talk to SpiceDB are being refactored (i.e. a monolith is being split into a service oriented architecture), there is likely nothing you need to do with SpiceDB.
Because SpiceDB runs as a separate service, any new services that talk to it just need to connect and make the necessary queries. There’s peace of mind knowing that authorization (typically a challenging part of changing architecture at this layer) won’t be a burden or a bottleneck.
With SpiceDB, you write relationships, but you check permissions. Permissions are computed over the relationships that are already stored. This means that any changes you wish to make to how permissions are computed can be done without any migrations at all: simply update the schema.
For example, with this schema:
definition user {}
definition organization {
relation administrator: user
relation direct_member: user
permission member = direct_member
}
You can include administrators as members and create a new “admin” permission without any migrations at all:
definition user {}
definition organization {
relation administrator: user
relation direct_member: user
permission admin = administrator
permission member = direct_member + administrator
}
There will always be cases where a migration is required, and when that happens you will need to plan out the migration steps. Here are some patterns to help with your online migration plan:
All Schema writes are fully consistent. This means that any relationship writes that occur after the schema has been written will be evaluated under that new schema.
Any relationship reads, however, will use the revision of the schema that matches the revision of the read request. This ensures that checks evaluate with the correct schema to avoid new enemy problems.
SpiceDB enforces some rules to ensure migrations are safe:
With these in mind, all you need to get started is an appropriate API client.
The following examples will assume this is the schema we’re starting out with:
definition user {}
definition document {
relation writer: user
relation reader: user
permission edit = writer
permission view = reader + edit
}
(Jump back to the initial schema for reference)
definition user {}
definition document {
relation writer: user
relation reader: user
relation owner: user -- step 1
permission edit = writer + owner -- step 4
permission view = reader + edit
}
owner
relation when updating spicedb.(Jump back to the initial schema for reference)
1definition user {}
2
3definition document {
4 relation writer: user
5 -- step 5: removed `relation reader: user`
6
7 permission edit = writer
8 permission view = edit -- step 1: removed `reader +`
9}
(Jump back to the initial schema for reference)
definition user {}
definition group { -- step 1
relation member: user -- step 1
} -- step 1
definition document {
relation writer: user | group#member -- step 4
relation reader: user | group#member -- step 4
permission edit = writer
permission view = reader + edit
}
Now that we have worked through some examples, it’s clear that migrations in SpiceDB are no more challenging than migrations in a general purpose DBMS, and in some cases much simpler.
But there is no reason to stop there! We’ve seen how SpiceDB’s focus on permission calculations makes a certain class of hard migration problems go away. We think that there are more ways we can simplify migrations in SpiceDB. If you’re interested in discussing those with us (or you have a question about your own migrations), why not drop by our discord and have a chat?