Skip to main content

MIGRATION_1

Constant MIGRATION_1 

pub const MIGRATION_1: &str = "-- Migration 1 \u{2014} the event log.\n--\n-- Applied by `include_str!` and one `execute`, not by `sqlx::migrate!`; the\n-- manifest records why. It is idempotent (`IF NOT EXISTS` throughout) so that\n-- applying it twice to one schema is a no-op rather than an error, because the\n-- alternative \u{2014} a fixture that fails on its second `connect()` \u{2014} reports a\n-- broken environment as an adapter defect.\n--\n-- The visibility mechanism is `xid8` + `pg_snapshot_xmin` -- the arm ADR-0013\'s\n-- phase-2 experiment measured at 0.99-1.03x baseline while the two serialising\n-- arms cost 16x and 30x at 64 writers, and the tag-keyed advisory lock bought a\n-- per-boundary invariant where ES-10 states a global one\n-- (`experiments/position-visibility/README.md`). It is wired here on that prior\n-- authority; the *choice*, its structural bill and a re-measurement against this\n-- adapter belong to the story that owns them, and nothing in this file cites a\n-- decision record that does not exist yet.\n--\n-- `position` still carries NO column default. The sequence is real and is read\n-- explicitly by the INSERT, which keeps `information_schema` reporting\n-- `column_default IS NULL` and `is_identity = \'NO\'` -- so \"position is not\n-- bigserial\" stays a checkable fact rather than a turn of phrase, and the guard\n-- that asserts it survives the mechanism landing.\n\nCREATE TABLE IF NOT EXISTS event (\n    -- Deliberately not `bigserial`, and the distinction is not cosmetic even\n    -- though the allocator is the same. `nextval()` DOES allocate outside the\n    -- transaction, and that IS where position order stops being commit order --\n    -- arm C does not deny it, it stops treating position order as VISIBILITY\n    -- order and puts the frontier predicate on the read side instead. Keeping\n    -- the default off the column is what makes the allocation site explicit at\n    -- the one INSERT that performs it, rather than implicit in the DDL.\n    position        bigint  PRIMARY KEY,\n    event_type      text    NOT NULL,\n    -- Payloads are opaque bytes. The contract crate never sees them decoded\n    -- (ADR-0003), so neither does this schema.\n    data            bytea   NOT NULL,\n    -- Nullable on purpose: `None` and `Some(empty)` are different values and the\n    -- suite has a rule that says so. A `NOT NULL DEFAULT \'\'` here would collapse\n    -- them and pass every other rule.\n    metadata        bytea,\n    -- `Tags` is canonically sorted, which is what keeps the containment operator\n    -- `@>` available against the GIN index below.\n    tags            text[]  NOT NULL,\n    -- The two halves of `EventId`, which is `(StoreId, SequencePosition)`.\n    -- `StoreId` is `[u8; 16]`, and the CHECK is what makes that a fact about the\n    -- table rather than a convention in the encoder. Nullable because a\n    -- replication ingest may hold rows minted elsewhere before this store stamps\n    -- its own.\n    origin_store    bytea   CONSTRAINT event_origin_store_is_16_bytes\n                            CHECK (origin_store IS NULL OR octet_length(origin_store) = 16),\n    origin_position bigint,\n    -- Milliseconds since the epoch, and signed because `RecordedAt` is `i64` and\n    -- admits times *before* it \u{2014} there is a core test named for that case. A\n    -- `timestamptz` column would be a lossy conversion the port never asked for.\n    recorded_at     bigint  NOT NULL,\n    -- The mechanism. The appending transaction stamps its own id, and a reader\n    -- admits only rows beneath `pg_snapshot_xmin(pg_current_snapshot())` -- the\n    -- frontier below which no transaction can still be in flight. Writers never\n    -- serialise; the cost is paid on the read side and it is structural rather\n    -- than incremental: `head` reports a frontier rather than a maximum,\n    -- read-your-own-writes does not hold, and staleness is bounded by the\n    -- longest open write transaction anywhere in the cluster.\n    --\n    -- A DEFAULT rather than an explicit value in the INSERT, and the asymmetry\n    -- with `position` above is deliberate: `pg_current_xact_id()` must be\n    -- evaluated by the writing transaction itself, so a default is the one\n    -- spelling that cannot be got wrong by a caller assembling the statement.\n    xact_id         xid8    NOT NULL DEFAULT pg_current_xact_id()\n);\n\n-- Read explicitly by the INSERT, never as a column default. `OWNED BY` ties its\n-- lifetime to the column so a dropped table does not leave it behind.\nCREATE SEQUENCE IF NOT EXISTS event_position_seq OWNED BY event.position;\n\n-- Tag matching. `text[]` + GIN was chosen over a join table and over `jsonb`:\n-- it is the shape the crate\'s own prose schema already leaned to, it is the\n-- shape `experiments/position-visibility/` ran its numbers against, and `@>`\n-- expresses a query item\'s \"tags are AND, and a superset matches\" directly\n-- rather than as a self-join per tag.\nCREATE INDEX IF NOT EXISTS event_tags_idx ON event USING gin (tags);\n\n-- Type-and-position, in that order, so a query item that names types is a range\n-- scan rather than a filter over one.\nCREATE INDEX IF NOT EXISTS event_type_idx ON event (event_type, position);\n\n-- One store never mints one `EventId` twice, and this is where that is a fact\n-- rather than an intention: `event_ids_are_unique_within_a_store` is a\n-- conformance rule, and an adapter that enforces it only in Rust enforces it\n-- only until two connections race. A partial index because the pair is nullable\n-- until a row is stamped, and `NULL`s do not collide in a plain unique index \u{2014}\n-- which would make the constraint quietly weaker than it reads.\nCREATE UNIQUE INDEX IF NOT EXISTS event_origin_idx\n    ON event (origin_store, origin_position)\n    WHERE origin_store IS NOT NULL AND origin_position IS NOT NULL;\n\n-- The frontier predicate\'s own index. Without it every read is a sequential\n-- scan, which would charge the mechanism for the absence of an index rather\n-- than for what it actually costs -- the experiment\'s schema says so in the same\n-- words, and its numbers were taken with this index present.\nCREATE INDEX IF NOT EXISTS event_xact_idx ON event (xact_id);\n\n-- The store\'s own identity, which is the `StoreId` half of every `EventId` this\n-- store mints. One row, inserted once and never updated by the adapter.\n--\n-- `gen_random_uuid()` rather than an extension: it is core since PostgreSQL 13\n-- and gives exactly the sixteen bytes `StoreId` holds, so `uuid_send` is a\n-- reinterpretation rather than a conversion. `ON CONFLICT DO NOTHING` makes the\n-- insert idempotent, which is what lets two handles race a first `connect()` and\n-- both end up agreeing about who this store is -- the loser reads the winner\'s\n-- row rather than keeping the id it generated.\nCREATE TABLE IF NOT EXISTS store_meta (\n    k text  PRIMARY KEY,\n    v bytea NOT NULL\n);\n\nINSERT INTO store_meta (k, v)\nVALUES (\'store_id\', uuid_send(gen_random_uuid()))\nON CONFLICT (k) DO NOTHING;\n";
Available on crate feature event-store and (crate features event-store or projection-store) only.
Expand description

The event log’s first migration, as SQL; MIGRATION_3 follows it.

Exposed rather than private because a consumer running their own migration tooling needs the text, and the alternative is that they copy it out of the repository and it drifts. Applying both is apply.

Idempotent: every object is created IF NOT EXISTS, so applying it to a schema that has it is a no-op. Frozen since first publish: a change is a new one.