Skip to main content

migrations

One-time data / index migrations for the pod background cache.

Distinct from the per-type schema migrations (cache/types/<name>/vN/ migrations.py, which are DDL upgrades tied to a version bump): these are one-off migrations that are not tied to a version bump — rewriting stored values, or adding a secondary index the ORM declares but create_all only builds on a freshly-created table. They run once at cache open and are gated by a cache_applied_migrations marker so they never repeat.

Each migration is a module exposing NAME: str and apply(cache) -> int (the number of changes made). Add a new module in this package — index builds go in the indexes subpackage — and register it in _MIGRATIONS; the runner handles gating and recording. Order matters where one migration's output is another's input (see the note on the search index below).

A few of these cannot be marker-gated, because what they build is derived state on another table that a later table rebuild destroys — and a marker would then stop them ever rebuilding it. Those are registered in _RECONCILED instead and re-checked on every open. See its comment.

Module​

Submodules​

Functions​

run_pending​

def run_pending(cache: CacheProtocol) ‑> None:

Apply any not-yet-applied one-time data migrations, once each.

Safe to call on every cache open: once a migration's marker is set it is a single cheap lookup, and each migration's apply is itself idempotent. _RECONCILED entries deliberately have no marker and run every time.

Arguments

  • cache: The cache backend (opened with the pod key bound, so a migration that needs to decrypt can resolve the key).