Skip to content

armgit / qm

Public Imported from GitHub
0

Multiplayer agent harness for work.

4.5 KB
Raw Blame

Runtime upgrade compatibility

Pin the runtime source or image digest and deployment CLI together. Run migrations before serving traffic, then qualify that exact candidate against an isolated copy of the existing database. Keep the previous images and deployment configuration available until the new revision has passed operational checks.

Configuration changes

  • qm sandbox publish and the sandbox.image runtime pin are retired. qm sandbox build remains available for validating local layer builds; sandbox.baseImage identifies their build input. Supply sandbox tools through deployment layers and configure the selected backend through its supported settings.
  • SANDBOX_SECONDARY_BACKEND is retired. SANDBOX_BACKEND selects the primary backend; additional configured backends become available through their credentials and backend settings. Remove the old secondary setting.
  • The sandbox_routing table, SANDBOX_RESOURCES_ENABLED, and the sandbox migration endpoints and agent action are retired. Sandbox resources are always on; scoped execution uses the selected sandbox resource. Disposable computers use that resource's provider, or the installation provider when no resource is selected. On upgrade, existing routes and SANDBOX_SCOPE_BACKENDS mappings are imported once as sandbox records so existing computers are preserved; afterwards SANDBOX_SCOPE_BACKENDS has no runtime effect. To move a scope to another provider, create a sandbox there, copy durable work via git or Files, and set it as the default. Keep credentials and provider settings for all legacy mappings until the import completes; an unconfigured provider needed by the import stops startup before any adoption state is written.
  • Reach-denied Slack notifications are retired. Consult the audit log for denied requests.

Database upgrades and rollback

Migration identifiers and SQL checksums retain their original meaning. An existing checksum mismatch stops the upgrade; do not clear the migration ledger or edit its checksums to bypass this check. A previously completed legacy webhook sweep is adopted into the checksum ledger without disabling webhooks that an operator has subsequently re-enabled.

The cron journal imports existing cron_fire_log history into cron_fires and continues importing writes from older workers during a rolling upgrade. History retention also removes expired entries from the legacy table, preventing a later restart from importing them again. The legacy table remains available for older binaries.

Upgrading from a release that predates the items table copies session history into items during startup migrations, then drops session_entries, session_tape and the old search table. Stop every older core and worker first: they cannot run against the new schema. src/sessions/legacy-history-migrations.ts keeps those released migrations verbatim; delete it once every supported deployment has applied sessions/store/0036-items-cutover. Upgrading from a release that still writes session_tape first copies its step metadata into legacy_tape_steps, then drops the tape. Stop every older core and worker before starting the new release: a tape write after the copy starts makes the drop refuse, and that startup fails with the reset to run. The copy runs on the direct migration connection without a statement timeout and resumes after an interrupted startup. It walks every session at roughly 30 sessions per second, so a few thousand sessions take a couple of minutes; above that, run node src/migrate-main.ts with the release's configuration before starting the servers so readiness checks do not time out. Instances that start meanwhile wait for the copy on the migration lock.

Sessions created before QM recorded each session's origin get origin and origin_id from their thread reference during startup migrations. The backfill commits 5,000 sessions at a time, resumes after an interrupted startup, and fills roughly 10,000 sessions per second; with more than a few hundred thousand such sessions, run node src/migrate-main.ts with the release's configuration before starting the servers so readiness checks do not time out.

Rolling back the runtime restores code and configuration, not database contents. Older binaries do not display cron history written only to the new journal; those records remain stored in cron_fires. Validate both old and new readers against the candidate database before promotion, and retain a database recovery point for any rollback that requires restoring data as well as code.