ka2a

ka2a documentation

Upgrade notes

Developer preview. Not yet production ready. This page is rendered from docs/upgrade.md of the ka2a repository at revision 96fb45e5e5f6693e779837998c3aa9581d6a37f2. It describes the behavior of that revision.

Contents

Store schema version 1 to 2

Schema version 2 adds the context owners (implementation decisions, section 19.3). The table records which principal owns each A2A context. ka2a version reports store_schema 2.

What the migration does

  • The owner Open of the new binary migrates the store in its open transaction. A failure rolls the migration back; the store stays at version 1.
  • The migration backfills the owners from the tasks of the store. The owner of the first task in a context (lowest task sequence) owns the context.
  • If two principals have tasks in the same context, the second principal keeps its task. It cannot send more messages that name that context: they fail with identity_conflict.
  • A context that only a message result named is not known after the migration. Its next use claims it.

Compatibility

BinaryStore version 1Store version 2
Schema 1 binary, owner or read-onlyWorksRefused: schema_too_new
Schema 2 binary, ownerMigrates to version 2Works
Schema 2 binary, read-only (observe, doctor, serve-ui, snapshot export)Refused: schema_too_old until an owner migrates itWorks

A read-only command never migrates a store.

Upgrade steps

  1. Stop the owner of the endpoint.
  2. With the old binary, take a backup: ka2a backup --state-dir DIR --out /secure/backups/billing-v1.db. Take this backup with the old binary. The new binary migrates the store at its owner open, so a backup that it writes has schema version 2.
  3. Record the backup ID and the time. Keep the backup until you do not need a rollback.
  4. Install the new binary.
  5. Start the owner with the new binary (ka2a run, or your application with pkg/ka2a). The first owner open migrates the store.
  6. Check the result: ka2a doctor --state-dir DIR. store.open shows schema version 2.

Upgrade one endpoint at a time. The wire profile did not change, so endpoints with schema version 1 and 2 exchange messages.

Rollback with a backup

A schema 1 binary cannot open a version 2 store. A rollback needs the backup of step 2.

  1. Stop the owner.
  2. Install the old binary.
  3. With the old binary, restore the backup: ka2a restore --state-dir DIR --from /secure/backups/billing-v1.db. The command keeps the replaced version 2 database under a new name.
  4. Start the owner with the old binary. The store enters quarantine.
  5. Follow the runbook Quarantine after a restore. Work after the backup time is not in the restored store. Reconcile it with the peers before you release the quarantine.

A rollback never gives exactly-once recovery. Work that the new binary admitted or ran after the backup can be lost or can run again.

All ka2a documents