const UPGRADE_SEED: usize = 2;Expand description
Seed used to generate the catalog upgrade shard ID.
All state that gets written to persist is tagged with the version of the code that wrote that state. Persist has limited forward compatibility in how many versions in the future a reader can read. Reading from persist updates state and the version that the state is tagged with. As a consequence, reading from persist may unintentionally fence out other readers and writers with a lower version. We use the catalog upgrade shard to track what database version is actively deployed so readers from the future, such as the upgrade checker tool, don’t accidentally fence out the database from persist. Only writable opened catalogs can increment the version in the upgrade shard.
One specific example that we are trying to avoid with the catalog upgrade shard is the following:
- Database is running on version 0.X.0.
- Upgrade checker is run on version 0.X+1.0.
- Upgrade checker is run on version 0.X+2.0.
With the catalog upgrade shard, the upgrade checker in step (3) can see that the database is currently running on v0.X.0 and reading the catalog would cause the database to get fenced out. So instead of reading the catalog it errors out. Without the catalog upgrade shard, the upgrade checker could read the version in the catalog shard, and see that it is v0.X+1.0, but it would be impossible to differentiate between the following two scenarios:
- The database is running on v0.X+1.0 and it’s safe to run the upgrade checker at v0.X+2.0.
- Some other upgrade checker incremented the version to v0.X+1.0, the database is running on version v0.X.0, and it is not safe to run the upgrade checker.
Persist guarantees that the shard versions are non-decreasing, so we don’t need to worry about race conditions where the shard version decreases after reading it.