Module migrations

dwara_core::state

Module migrations 

Source
Expand description

Versioned, transactional SQLite schema migrations (DW-115).

§Model

All schema evolution is expressed as an ordered list of UP migrations (migrations) applied by rusqlite_migration, which records progress in PRAGMA user_version — the same pragma the DW-018 hand-rolled schema used. A database at user_version = 1 with the DW-018 tables IS migration state 1: migration 001 below is that exact baseline DDL (kept idempotent via IF NOT EXISTS), so a fresh database runs 001 to reach state 1, while an existing DW-018 database already reports state 1 and 001 is correctly treated as applied.

§Forward-only

There are NO down migrations. Rolling a gateway binary back onto a newer-schema data directory is refused (see StateStore open: user_version greater than the binary’s latest is a hard error), and downgrading in place is unsupported. The documented rebuild path, since schema v1 content is entirely re-derivable:

  1. Stop the gateway. Every migration takes a backup first — see “Backup before migrate” in crate::state::store — so locate the newest <db>.bak-<version>-<timestamp> file for the version you want.
  2. Replace the live db file with that backup (it is a consistent VACUUM INTO snapshot at the pre-migration version).
  3. Restart. Consumers and credentials are also re-seedable from config via sync_consumers_from_config if no backup exists, so the honest v1 answer is: restore the backup, or recreate the data dir and let config seeding repopulate it.

§Adding a migration

Append ONE M::up entry and bump LATEST_SCHEMA_VERSION. Migrations must be additive (create table/index, add column with a default) so every historical version migrates forward with zero data loss — tests here open a hand-built v1 database through every version to HEAD. Never edit an existing migration: databases in the wild have already recorded it.

Structs§

SchemaInfo
Current vs latest schema version, for the admin surface (DW-022 will expose this via the admin API; current < latest after open should be impossible because StateStore::open migrates automatically — the seam exists for reporting, not gating).

Constants§

LATEST_SCHEMA_VERSION
Latest schema version this build knows how to produce. Equals the number of entries in migrations; asserted by test.

Functions§

migrations
The full forward migration set, in order. See the module docs for the baseline recognition rule and the forward-only policy.