60 lines
2.7 KiB
Markdown
60 lines
2.7 KiB
Markdown
# Workspace schema migrations
|
|
|
|
Workspace schema authority belongs to `crates/workspace-server/src/store.rs`. The canonical
|
|
schema, ordered migrations, migration-history validation, startup upgrade path, and explicit
|
|
`yoi-server migrate` command must remain one contract.
|
|
|
|
## Retained migration chain
|
|
|
|
Released or dogfooded schema migrations are retained and composed in version order. Adding a new
|
|
schema version does not authorize deleting the preceding migration. A migration may be removed
|
|
only as an explicit baseline-retirement operation after the supported installations that depend on
|
|
it have been migrated or intentionally discarded.
|
|
|
|
The current retained Workspace chain is:
|
|
|
|
1. schema 50: `workspace schema baseline`
|
|
2. schema 51: `workspace runtime bindings`
|
|
3. schema 52: `workspace Runtime binding revision and audit`
|
|
4. schema 53: `durable Workspace deletion operations`
|
|
|
|
A database may begin at any retained baseline. Its following history rows must be the exact prefix
|
|
of the ordered migration chain from that baseline. This allows both a freshly created current
|
|
database and a database upgraded across several releases while rejecting edited, reordered, or
|
|
unknown histories.
|
|
|
|
## Runtime behavior
|
|
|
|
`SqliteWorkspaceStore::open` computes all pending retained migrations and applies them in order.
|
|
Each migration is transactional and restartable: if a later step fails, completed steps remain a
|
|
valid canonical prefix and the next run resumes from that version.
|
|
|
|
`yoi-server migrate` invokes the same store migration path without starting the Server:
|
|
|
|
```sh
|
|
# Copy the DB into memory and validate the complete pending path without changing the source.
|
|
yoi-server migrate --dry-run
|
|
|
|
# Preflight the complete path, then apply it to the source DB.
|
|
yoi-server migrate
|
|
```
|
|
|
|
Use `--database <PATH>` for a non-default Server DB. Stop `yoi-server` before applying migrations
|
|
and make an external backup before an operational upgrade.
|
|
|
|
## Development workflow
|
|
|
|
When changing the Workspace schema:
|
|
|
|
1. increment `LATEST_SCHEMA_VERSION`;
|
|
2. append one `Migration` entry with the new version, stable name, and apply function;
|
|
3. preserve all migrations at or above `OLDEST_SCHEMA_VERSION`;
|
|
4. update the canonical latest-schema creator for fresh databases;
|
|
5. add a fixture at the oldest retained version and prove migration through every retained step;
|
|
6. prove that `--dry-run` leaves the source DB unchanged;
|
|
7. keep DDL validation and cross-schema foreign-key checks in the shared store preparation path.
|
|
|
|
A deliberate baseline retirement must be a separately reviewed change. It must identify the oldest
|
|
remaining version, provide an operational migration/discard plan for older databases, update tests
|
|
and this document, and must not be inferred merely because a new migration was added.
|