Skip to content

Operator's guide: rolling deployment migration #91

@pathosDev

Description

@pathosDev

The framework now ships rolling-deploy-friendly migration tooling (#7 `writeVersion` + #8 master-key rotation + #9 wrap-legacy + #6 schema registry). These compose into a real operational pattern but the README only documents each piece in isolation.

Scope:

  • New file `docs/operations/rolling-migration.md`.
  • Walk through the canonical 4-phase deploy:
    1. Code-first: ship the new code with both old + new schemas registered, but `writeVersion = old`. Old + new readers coexist; everyone writes the old shape.
    2. Reader rollout: observation period. Verify all instances are running the new code.
    3. Writer flip: redeploy with `writeVersion = new`. New writes use the new shape; existing data is upcast on read.
    4. Cleanup: optional one-shot `migrateInMemoryJournal` (or backend-equivalent) to actively rewrite historical data; finally drop the old version's upcaster from the registry.
  • Same shape for master-key rotation: ship the new key as `active` + old key in `retired`, observe, optional re-encryption sweep (Re-encryption sweep helper for master-key rotation #70), drop old key.

Estimate: 1 day (documentation + a small worked-example diagram).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentationpriority: mediumUseful, not urgent

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions