Skip to content

Make awa migrate own the default queue-storage schema before 0.6 #308

@hardbyte

Description

@hardbyte

Context

The historical split was:

  • awa-model/migrations/v*.sql owns the canonical awa.* namespace.
  • QueueStorage::prepare_schema() owns {queue_storage_schema}.* because the queue-storage schema name was dynamic.

That boundary made sense while queue storage was clearly separate / dynamic, but the 0.6 default queue-storage schema is now awa. In the default path, prepare_schema() is creating first-class awa.* objects after awa migrate has already reported the schema as current.

Why this matters before 0.6

The current split leaks into operator and release behavior:

  • awa migrate can leave the default queue-storage substrate absent, so a fresh install relies on the first worker doing DDL.
  • awa migrate --sql / --extract-to cannot reproduce the full default runtime schema if queue-storage substrate DDL only lives in Rust prepare_schema().
  • Recent migrations already need defensive boot-window logic when a queue-storage table such as queue_terminal_live_counts might not exist yet.
  • awa storage prepare-queue-storage-schema --schema awa --reset currently means DROP SCHEMA IF EXISTS awa CASCADE, which is dangerous now that the default queue-storage schema is also the canonical schema.

Proposed direction

Before shipping 0.6, make the default contract explicit:

  1. awa migrate owns the default awa install: canonical schema plus the default queue-storage substrate.
  2. awa migrate remains activation-neutral: it should create the objects, but not flip routing / storage-transition state by itself.
  3. QueueStorage::prepare_schema() remains idempotent for custom queue-storage schemas, repair, tests, and worker safety, but it is no longer the normal source of default awa.* object creation.
  4. Extracted migration SQL must include the default queue-storage install story, either as generated SQL or a SQL helper, so external migration tooling is not incomplete.
  5. Destructive reset paths must be guarded for schema == 'awa' or made to rerun canonical migrations consistently.

Acceptance criteria

  • Fresh awa migrate creates all default queue-storage objects needed by 0.6 queue-storage runtime startup, including the job id sequence, hot tables, partitions, helper functions, and live terminal counter/indexes.
  • Fresh awa migrate does not activate queue storage by itself; existing fresh-install auto-finalize / worker startup semantics remain deliberate.
  • awa migrate --sql and awa migrate --extract-to include enough SQL for an external migration system to produce the same default schema as awa migrate.
  • Custom queue_storage_schema deployments still work via explicit schema preparation.
  • prepare-queue-storage-schema --schema awa --reset / Python reset paths cannot accidentally drop the canonical schema without restoring it, or are rejected with a clear error.
  • Docs describe the final ownership boundary: migrations own default awa.*; explicit schema preparation owns non-default queue-storage schemas.

Metadata

Metadata

Assignees

No one assigned

    Labels

    correctnessFormal verification and protocol correctnessoperationalOperational tooling and configuration

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions