@kairos-es/feed-postgres 0.0.0-stage → 1.0.0-alpha.6

package/dist/esm/internal/ddl.js

@@ -0,0 +1,136 @@
+/** The default schema, identical to the event store's and the read side's. */
+export const DEFAULT_SCHEMA = 'public';
+/** The default table prefix, identical to the event store's and the read side's. */
+export const DEFAULT_TABLE_PREFIX = 'dcb_events';
+const MAX_IDENTIFIER_BYTES = 63;
+const utf8ByteLength = value => new TextEncoder().encode(value).length;
+const suffixes = {
+  rows: '_feed_rows',
+  rowsSeqIndex: '_feed_rows_seq_idx',
+  sequence: '_feed_seq',
+  generations: '_feed_generations',
+  cursors: '_feed_cursors',
+  parked: '_feed_parked'
+};
+/**
+ * The single-atom identifiers Postgres materialises for a config. The index is
+ * measured, unlike a primary key's implicit one, because it is named explicitly
+ * and `CREATE INDEX IF NOT EXISTS` would skip a truncated name that collides with
+ * another prefix's index instead of reporting it.
+ */
+const derivedAtoms = config => {
+  const schema = config.schema ?? DEFAULT_SCHEMA;
+  const prefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX;
+  return [['schema', schema], ['feed rows table', `${prefix}${suffixes.rows}`], ['feed rows index', `${prefix}${suffixes.rowsSeqIndex}`], ['feed sequence', `${prefix}${suffixes.sequence}`], ['feed generations table', `${prefix}${suffixes.generations}`], ['feed cursors table', `${prefix}${suffixes.cursors}`], ['feed parked table', `${prefix}${suffixes.parked}`]];
+};
+/**
+ * The first derived identifier over Postgres's 63-byte limit, as a message, or
+ * `undefined` when every name fits. Postgres truncates an over-long identifier
+ * with only a notice, so two prefixes sharing a 63-byte stem would silently share
+ * one feed table; refusing at the boundary beats that.
+ */
+export const oversizedIdentifier = config => {
+  for (const [label, atom] of derivedAtoms(config)) {
+    const bytes = utf8ByteLength(atom);
+    if (bytes > MAX_IDENTIFIER_BYTES) {
+      return `the ${label} identifier "${atom}" is ${bytes} bytes, over Postgres's ${MAX_IDENTIFIER_BYTES}-byte limit; it would be silently truncated, letting two prefixes share one feed object`;
+    }
+  }
+  return undefined;
+};
+/** Derive every name from the pair; throws on an over-long identifier. */
+export const resolveFeedNames = config => {
+  const problem = oversizedIdentifier(config);
+  if (problem !== undefined) {
+    throw new Error(`resolveFeedNames: ${problem}`);
+  }
+  const schema = config.schema ?? DEFAULT_SCHEMA;
+  const tablePrefix = config.tablePrefix ?? DEFAULT_TABLE_PREFIX;
+  const qualified = suffix => `${schema}.${tablePrefix}${suffix}`;
+  return {
+    schema,
+    tablePrefix,
+    rowsTable: qualified(suffixes.rows),
+    rowsSeqIndex: `${tablePrefix}${suffixes.rowsSeqIndex}`,
+    sequence: qualified(suffixes.sequence),
+    generationsTable: qualified(suffixes.generations),
+    cursorsTable: qualified(suffixes.cursors),
+    parkedTable: qualified(suffixes.parked)
+  };
+};
+/** Quote a possibly qualified identifier, atom by atom, for literal SQL text. */
+export const quoteQualified = name => name.split('.').map(atom => quoteAtom(atom)).join('.');
+/** Quote one identifier atom, doubling any embedded `"`. */
+export const quoteAtom = name => `"${name.replace(/"/g, '""')}"`;
+/**
+ * The quoted sequence name as a SQL string LITERAL, for `nextval('…')`. The
+ * literal is parsed as a `regclass`, which honours the double quotes inside it, so
+ * an awkward prefix resolves to exactly the object the DDL created; any `'` in it
+ * is doubled so the literal cannot be closed early.
+ */
+export const sequenceLiteral = names => `'${quoteQualified(names.sequence).replace(/'/g, "''")}'`;
+/**
+ * The ordered, idempotent DDL. Every statement is `IF NOT EXISTS`, so a second
+ * run against existing objects is a no-op that keeps every row.
+ *
+ * Shapes that are load-bearing:
+ *
+ * - `_feed_rows` is keyed `(feed, key)`: one row per record, which is what
+ *   "coalesced, latest wins" means in storage, and the arbiter the writer's
+ *   `ON CONFLICT` names. `doc` is NULL for a tombstone; a document that encodes to
+ *   JSON `null` is the jsonb value `null`, which is not SQL NULL, so the two
+ *   cannot be confused.
+ * - The `(feed, seq)` index is what `changesAfter` pages by.
+ * - ONE sequence serves every feed in the prefix. A feed's `seq` values therefore
+ *   have gaps, which the cursor never minds: it compares, never counts.
+ * - `_feed_cursors` holds the cursor AND the lease, so the cursor's
+ *   compare-and-set can fence on the lease holder in the same row it moves. The
+ *   cursor is `(generation, seq)`, both NULL before a sink's first sync and never
+ *   one without the other, which the `CHECK` holds. `last_advance_at` is when
+ *   the cursor last moved, NULL until it first does; taking a lease leaves it
+ *   alone, so a sink registered and never run shows as one.
+ * - `_feed_generations` holds the checkpoint key a feed is bound to, so binding
+ *   one feed to two materialisations is refused across processes, not only within
+ *   one.
+ */
+export const feedDdlStatements = names => {
+  const rows = quoteQualified(names.rowsTable);
+  const generations = quoteQualified(names.generationsTable);
+  const cursors = quoteQualified(names.cursorsTable);
+  const parked = quoteQualified(names.parkedTable);
+  return [`CREATE SCHEMA IF NOT EXISTS ${quoteAtom(names.schema)};`, `CREATE SEQUENCE IF NOT EXISTS ${quoteQualified(names.sequence)};`, `CREATE TABLE IF NOT EXISTS ${rows} (
+       "feed" text NOT NULL,
+       "key" text NOT NULL,
+       "doc" jsonb NULL,
+       "seq" bigint NOT NULL,
+       "event_position" bigint NOT NULL,
+       PRIMARY KEY ("feed", "key")
+     );`, `CREATE INDEX IF NOT EXISTS ${quoteAtom(names.rowsSeqIndex)}
+       ON ${rows} ("feed", "seq");`, `CREATE TABLE IF NOT EXISTS ${generations} (
+       "feed" text PRIMARY KEY,
+       "generation" bigint NOT NULL,
+       "checkpoint_projection" text NULL,
+       "checkpoint_partition" text NULL
+     );`, `CREATE TABLE IF NOT EXISTS ${cursors} (
+       "feed" text NOT NULL,
+       "sink" text NOT NULL,
+       "generation" bigint NULL,
+       "seq" bigint NULL,
+       "lease_holder" text NULL,
+       "lease_expires_at" timestamptz NULL,
+       "last_advance_at" timestamptz NULL,
+       PRIMARY KEY ("feed", "sink"),
+       CHECK (("generation" IS NULL) = ("seq" IS NULL))
+     );`, `CREATE TABLE IF NOT EXISTS ${parked} (
+       "feed" text NOT NULL,
+       "sink" text NOT NULL,
+       "key" text NOT NULL,
+       "seq" bigint NOT NULL,
+       "reason" text NOT NULL,
+       "parked_at" timestamptz NOT NULL,
+       PRIMARY KEY ("feed", "sink", "key")
+     );`];
+};
+/** The DDL as statements on `sql`, one `sql.unsafe` each, in order. */
+export const runFeedDdl = (sql, names) => feedDdlStatements(names).map(statement => sql.unsafe(statement));
+//# sourceMappingURL=ddl.js.map

package/dist/esm/internal/ddl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ddl.js","names":["DEFAULT_SCHEMA","DEFAULT_TABLE_PREFIX","MAX_IDENTIFIER_BYTES","utf8ByteLength","value","TextEncoder","encode","length","suffixes","rows","rowsSeqIndex","sequence","generations","cursors","parked","derivedAtoms","config","schema","prefix","tablePrefix","oversizedIdentifier","label","atom","bytes","undefined","resolveFeedNames","problem","Error","qualified","suffix","rowsTable","generationsTable","cursorsTable","parkedTable","quoteQualified","name","split","map","quoteAtom","join","replace","sequenceLiteral","names","feedDdlStatements","runFeedDdl","sql","statement","unsafe"],"sources":["../../../src/internal/ddl.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/esm/internal/statements.js

@@ -0,0 +1,262 @@
+/**
+ * Every runtime statement text the Postgres change feed issues, compiled once per
+ * name set, and the conventions their parameters follow.
+ *
+ * One module, so what the feed sends to the database is auditable in one file.
+ * The Effect wiring that issues them lives in `feed.ts`, `syncStore.ts`, `lease.ts`
+ * and `withFeed.ts`; none of those writes SQL of its own.
+ *
+ * ## Parameter conventions
+ *
+ * - Every 64-bit value (`seq`, `generation`, `event_position`) is bound as a
+ *   decimal STRING and cast (`$n::bigint`), and read back as text and turned into
+ *   a `bigint`, so no value ever passes through a JS `number` and no driver's
+ *   integer handling can round one.
+ * - A batch of rows is bound as ONE `jsonb` parameter and unpacked server-side
+ *   (`jsonb_to_recordset`, `jsonb_array_elements_text`), so a batch is one
+ *   statement whatever its size and no array-binding support is asked of the
+ *   driver.
+ * - A timestamp is bound as epoch MILLISECONDS from Effect's `Clock`, and read back
+ *   the same way. Lease expiry is judged against the worker's Clock rather than the
+ *   database's `now()`, so a `TestClock` governs it in tests as it governs every
+ *   other time in this repository; the cost is that workers on several hosts must
+ *   keep their clocks within a small fraction of the lease length of each other.
+ * - A document is read back as `doc::text` and parsed here, so a consumer's JSON
+ *   parsing or name transforms cannot reshape it on the way.
+ * - A column read back as text is ALIASED to its own name, so every `ORDER BY`
+ *   qualifies the column with its table alias: an unqualified name in `ORDER BY`
+ *   resolves to the output column first, and `seq` would then sort as text, with
+ *   `10` before `4`.
+ *
+ * ## The feed lock
+ *
+ * The generations row of a feed doubles as its WRITE LOCK. A feed's `seq` is
+ * ascending in commit order only while one transaction at a time takes `seq`
+ * values for that feed, and the subscribe machine silently loses a row whose `seq`
+ * commits below one already read (ADR-0009). The materialisation is one writer, but
+ * two other things take `seq` values for a feed outside its commit: `retryParked`
+ * re-stamps a row, and a reset empties the feed. So the writer takes the row
+ * `FOR SHARE` before it takes any `seq`, `retryParked` takes it `FOR UPDATE`, and
+ * the reset UPDATEs it; each waits for the others to commit, and `seq` order is
+ * commit order for all three.
+ */
+import { quoteQualified, sequenceLiteral } from "./ddl.js";
+/** Compile every statement for `names`. */
+export const compileFeedStatements = names => {
+  const rows = quoteQualified(names.rowsTable);
+  const generations = quoteQualified(names.generationsTable);
+  const cursors = quoteQualified(names.cursorsTable);
+  const parked = quoteQualified(names.parkedTable);
+  const nextSeq = `nextval(${sequenceLiteral(names)})`;
+  const msToTimestamp = param => `to_timestamp(${param}::double precision / 1000)`;
+  const timestampToMs = column => `round(extract(epoch from ${column}) * 1000)::bigint::text`;
+  const advisoryKeyOf = param => `hashtextextended(${param}, 0)`;
+  const advisoryKey = advisoryKeyOf('$1');
+  // Whether THIS session holds the advisory lock named by `param`. A bigint
+  // advisory key is stored in `pg_locks` split into two 32-bit halves, `classid`
+  // the high and `objid` the low, with `objsubid` 1.
+  const sessionHoldsLock = param => `EXISTS (
+                          SELECT 1 FROM pg_locks l
+                          WHERE l.locktype = 'advisory'
+                            AND l.pid = pg_backend_pid()
+                            AND l.granted
+                            AND l.objsubid = 1
+                            AND l.classid = ((${advisoryKeyOf(param)} >> 32) & 4294967295)::oid
+                            AND l.objid = (${advisoryKeyOf(param)} & 4294967295)::oid
+                        )`;
+  return {
+    ensureGeneration: `INSERT INTO ${generations} ("feed", "generation")
+                       VALUES ($1, 0)
+                       ON CONFLICT ("feed") DO NOTHING`,
+    lockFeedShared: `SELECT 1 AS locked FROM ${generations}
+                     WHERE "feed" = $1 FOR SHARE`,
+    // One `nextval` per INSERTED candidate, kept by the update arm through
+    // `excluded.seq`, so an unchanged document burns a value and writes nothing:
+    // the `WHERE … IS DISTINCT FROM` arm compares the normalised jsonb, so key
+    // order is no change.
+    upsertRows: `INSERT INTO ${rows} AS r ("feed", "key", "doc", "seq", "event_position")
+                 SELECT $1, t."key", t."doc", ${nextSeq}, $2::bigint
+                 FROM jsonb_to_recordset($3::jsonb) AS t("key" text, "doc" jsonb)
+                 ON CONFLICT ("feed", "key") DO UPDATE
+                 SET "doc" = excluded."doc",
+                     "seq" = excluded."seq",
+                     "event_position" = excluded."event_position"
+                 WHERE r."doc" IS DISTINCT FROM excluded."doc"`,
+    // An UPDATE, never an insert: a remove of an absent key writes nothing, and
+    // neither does a remove of a key that is already a tombstone.
+    tombstoneRows: `UPDATE ${rows} AS r
+                    SET "doc" = NULL, "seq" = ${nextSeq}, "event_position" = $2::bigint
+                    FROM jsonb_array_elements_text($3::jsonb) AS t("key")
+                    WHERE r."feed" = $1 AND r."key" = t."key" AND r."doc" IS NOT NULL`,
+    selectGeneration: `SELECT "generation"::text AS generation
+                       FROM ${generations} WHERE "feed" = $1`,
+    changesAfter: `SELECT "key" AS key, "doc"::text AS doc, "seq"::text AS seq,
+                          "event_position"::text AS event_position
+                   FROM ${rows} AS r
+                   WHERE r."feed" = $1 AND r."seq" > $2::bigint
+                   ORDER BY r."seq"
+                   LIMIT $3`,
+    selectCursor: `SELECT "generation"::text AS generation, "seq"::text AS seq
+                   FROM ${cursors} WHERE "feed" = $1 AND "sink" = $2`,
+    // Guarded like a checkpoint AND fenced on the holder: zero rows means the
+    // stored cursor was not the expected one, or the lease is somebody else's.
+    casCursor: `UPDATE ${cursors}
+                SET "generation" = $4::bigint, "seq" = $5::bigint,
+                    "last_advance_at" = ${msToTimestamp('$8')}
+                WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3
+                  AND "generation" IS NOT DISTINCT FROM $6::bigint
+                  AND "seq" IS NOT DISTINCT FROM $7::bigint
+                RETURNING 1 AS landed`,
+    clearParked: `DELETE FROM ${parked} WHERE "feed" = $1 AND "sink" = $2`,
+    unparkKeys: `DELETE FROM ${parked}
+                 WHERE "feed" = $1 AND "sink" = $2
+                   AND "key" IN (SELECT jsonb_array_elements_text($3::jsonb))`,
+    parkKeys: `INSERT INTO ${parked} ("feed", "sink", "key", "seq", "reason", "parked_at")
+               SELECT $1, $2, t."key", t."seq"::bigint, t."reason", ${msToTimestamp('t."parked_at_ms"')}
+               FROM jsonb_to_recordset($3::jsonb)
+                 AS t("key" text, "seq" text, "reason" text, "parked_at_ms" text)
+               ON CONFLICT ("feed", "sink", "key") DO UPDATE
+               SET "seq" = excluded."seq", "reason" = excluded."reason",
+                   "parked_at" = excluded."parked_at"`,
+    selectParked: `SELECT "key" AS key, "seq"::text AS seq, "reason" AS reason,
+                          ${timestampToMs('"parked_at"')} AS parked_at_ms
+                   FROM ${parked} AS p
+                   WHERE p."feed" = $1 AND p."sink" = $2
+                   ORDER BY p."seq", p."key"`,
+    lockFeedExclusive: `SELECT 1 AS locked FROM ${generations}
+                        WHERE "feed" = $1 FOR UPDATE`,
+    unparkOne: `DELETE FROM ${parked}
+                WHERE "feed" = $1 AND "sink" = $2 AND "key" = $3
+                RETURNING 1 AS unparked`,
+    restampRow: `UPDATE ${rows} SET "seq" = ${nextSeq}
+                 WHERE "feed" = $1 AND "key" = $2`,
+    // Every sink REGISTERED on the feed counts — every cursor row, whatever
+    // generation its cursor was saved at — and the lowest of their cursors bounds
+    // what goes. A cursor at an older generation needs no arm of its own:
+    // `FeedSyncStore.ts`'s tombstone section owns why the minimum already holds it
+    // below every row, and this store keeps that section's premise, since a reset
+    // (`withFeed.ts`) moves the generation and empties the feed in one
+    // transaction and the one sequence never goes back. A sink with no cursor is
+    // resyncing from the origin and blocks collection outright, which `bool_or`
+    // says. No cursor row at all leaves both aggregates NULL, so the guard is NULL
+    // and nothing goes. The cursors are read in the delete's own statement
+    // snapshot, so a cursor saved after it can only be one that blocked here
+    // (nothing deleted) or one that moved up. A sink whose cursor row is CREATED
+    // after the snapshot is not counted, and need not be: that row is made when
+    // the sink takes its lease, before it reads the feed, and a feed holds one row
+    // per key, so a tombstone this collects had replaced its key's live row before
+    // such a sink could read anything.
+    collectTombstones: `WITH "low" AS (
+                          SELECT min(c."seq") AS "seq",
+                                 bool_or(c."seq" IS NULL) AS "blocked"
+                          FROM ${cursors} c
+                          WHERE c."feed" = $1
+                        )
+                        DELETE FROM ${rows} r USING "low"
+                        WHERE r."feed" = $1 AND r."doc" IS NULL
+                          AND NOT "low"."blocked" AND r."seq" <= "low"."seq"
+                        RETURNING 1 AS collected`,
+    // The transaction-scoped twin of `tryAdvisoryLock`, on the same key, so it
+    // conflicts with a session lock any advisory worker holds and is let go at
+    // commit or rollback without an unlock of its own.
+    tryAdvisoryXactLock: `SELECT pg_try_advisory_xact_lock(${advisoryKey}) AS taken`,
+    // A row whose expiry is later than the caller's now is a live lease row and
+    // stays. A holder with no expiry is an advisory one, and is deleted only
+    // because the caller holds the advisory lock, which proves its session gone.
+    // The test is in the delete itself, so a lease row taken after an earlier
+    // read is still refused here rather than deleted from under its worker.
+    deleteCursorUnlessLeased: `DELETE FROM ${cursors}
+                               WHERE "feed" = $1 AND "sink" = $2
+                                 AND ("lease_expires_at" IS NULL
+                                      OR "lease_expires_at" <= ${msToTimestamp('$3')})
+                               RETURNING 1 AS removed`,
+    cursorExists: `SELECT 1 AS present FROM ${cursors}
+                   WHERE "feed" = $1 AND "sink" = $2`,
+    deleteSinkParked: `DELETE FROM ${parked} WHERE "feed" = $1 AND "sink" = $2
+                       RETURNING 1 AS removed`,
+    selectHead: `SELECT COALESCE(max("seq"), 0)::text AS head
+                 FROM ${rows} WHERE "feed" = $1`,
+    describeSinks: `SELECT c."sink" AS sink,
+                           c."generation"::text AS generation,
+                           c."seq"::text AS seq,
+                           c."lease_holder" AS lease_holder,
+                           ${timestampToMs('c."lease_expires_at"')} AS lease_expires_at_ms,
+                           ${timestampToMs('c."last_advance_at"')} AS last_advance_at_ms,
+                           (SELECT count(*) FROM ${rows} r
+                            WHERE r."feed" = c."feed"
+                              AND CASE WHEN c."seq" IS NULL THEN r."doc" IS NOT NULL
+                                       ELSE r."seq" > c."seq" END)::text AS pending
+                    FROM ${cursors} c
+                    WHERE c."feed" = $1
+                    ORDER BY c."sink"`,
+    describeParked: `SELECT "sink" AS sink, "key" AS key, "seq"::text AS seq,
+                            "reason" AS reason,
+                            ${timestampToMs('"parked_at"')} AS parked_at_ms
+                     FROM ${parked} AS p
+                     WHERE p."feed" = $1
+                     ORDER BY p."sink", p."seq", p."key"`,
+    // Taken when nobody holds it, when the holder's expiry has passed, or when the
+    // holder has no expiry — an ADVISORY holder — and the caller holds that
+    // sink's advisory lock for its own transaction (`$6`), which an advisory
+    // worker's live session would have refused, so the session that recorded the
+    // holder is gone. The caller holds that lock until this statement commits, so
+    // no advisory worker can take the lock and record itself in between.
+    takeLeaseRow: `INSERT INTO ${cursors} AS c ("feed", "sink", "lease_holder", "lease_expires_at")
+                   VALUES ($1, $2, $3, ${msToTimestamp('$4')})
+                   ON CONFLICT ("feed", "sink") DO UPDATE
+                   SET "lease_holder" = excluded."lease_holder",
+                       "lease_expires_at" = excluded."lease_expires_at"
+                   WHERE c."lease_holder" IS NULL
+                      OR (c."lease_expires_at" IS NOT NULL
+                          AND c."lease_expires_at" <= ${msToTimestamp('$5')})
+                      OR (c."lease_expires_at" IS NULL AND $6::boolean)
+                   RETURNING 1 AS taken`,
+    // Never moves the expiry back: a renewal the worker abandoned at its timeout
+    // can still land after a later one, if its cancel came too late, and must not
+    // shorten the lease the later one recorded, which the worker's `ensureHeld`
+    // already counts on.
+    renewLeaseRow: `UPDATE ${cursors}
+                    SET "lease_expires_at" = GREATEST("lease_expires_at", ${msToTimestamp('$4')})
+                    WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3
+                    RETURNING 1 AS renewed`,
+    releaseLease: `UPDATE ${cursors}
+                   SET "lease_holder" = NULL, "lease_expires_at" = NULL
+                   WHERE "feed" = $1 AND "sink" = $2 AND "lease_holder" = $3`,
+    // Run on the SESSION that took the advisory lock, and proposes its row only
+    // while that session still holds the lock, so a claim from a session that has
+    // died — or let the lock go — since its try-lock records nothing, and cannot
+    // overwrite a successor that took the lock in between. Holding the lock proves
+    // that any ADVISORY holder recorded here (one with no expiry) is a dead
+    // session's, so that one is taken over. A lease-row holder whose expiry has not
+    // passed is live and is never taken over, as `takeLeaseRow` takes over an
+    // advisory holder only once its lock is free: whichever kind took the row
+    // first keeps it while it lives.
+    claimAdvisoryHolder: `INSERT INTO ${cursors} AS c ("feed", "sink", "lease_holder", "lease_expires_at")
+                          SELECT $1::text, $2::text, $3::text, NULL::timestamptz
+                          WHERE ${sessionHoldsLock('$5')}
+                          ON CONFLICT ("feed", "sink") DO UPDATE
+                          SET "lease_holder" = excluded."lease_holder",
+                              "lease_expires_at" = NULL
+                          WHERE c."lease_holder" IS NULL
+                             OR c."lease_expires_at" IS NULL
+                             OR c."lease_expires_at" <= ${msToTimestamp('$4')}
+                          RETURNING 1 AS claimed`,
+    tryAdvisoryLock: `SELECT pg_try_advisory_lock(${advisoryKey}) AS taken`,
+    holdsAdvisoryLock: `SELECT ${sessionHoldsLock('$1')} AS held`,
+    advisoryUnlock: `SELECT pg_advisory_unlock(${advisoryKey}) AS released`,
+    bindFeed: `INSERT INTO ${generations} AS g
+                 ("feed", "generation", "checkpoint_projection", "checkpoint_partition")
+               VALUES ($1, 0, $2, $3)
+               ON CONFLICT ("feed") DO UPDATE
+               SET "checkpoint_projection" = COALESCE(g."checkpoint_projection", excluded."checkpoint_projection"),
+                   "checkpoint_partition" = COALESCE(g."checkpoint_partition", excluded."checkpoint_partition")
+               RETURNING "checkpoint_projection" AS projection,
+                         "checkpoint_partition" AS partition`,
+    bumpGeneration: `INSERT INTO ${generations} AS g ("feed", "generation")
+                     VALUES ($1, 1)
+                     ON CONFLICT ("feed") DO UPDATE
+                     SET "generation" = g."generation" + 1`,
+    deleteFeedRows: `DELETE FROM ${rows} WHERE "feed" = $1`
+  };
+};
+//# sourceMappingURL=statements.js.map

package/dist/esm/internal/statements.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"statements.js","names":["quoteQualified","sequenceLiteral","compileFeedStatements","names","rows","rowsTable","generations","generationsTable","cursors","cursorsTable","parked","parkedTable","nextSeq","msToTimestamp","param","timestampToMs","column","advisoryKeyOf","advisoryKey","sessionHoldsLock","ensureGeneration","lockFeedShared","upsertRows","tombstoneRows","selectGeneration","changesAfter","selectCursor","casCursor","clearParked","unparkKeys","parkKeys","selectParked","lockFeedExclusive","unparkOne","restampRow","collectTombstones","tryAdvisoryXactLock","deleteCursorUnlessLeased","cursorExists","deleteSinkParked","selectHead","describeSinks","describeParked","takeLeaseRow","renewLeaseRow","releaseLease","claimAdvisoryHolder","tryAdvisoryLock","holdsAdvisoryLock","advisoryUnlock","bindFeed","bumpGeneration","deleteFeedRows"],"sources":["../../../src/internal/statements.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}