@relaybus/postgres 0.3.1 → 0.4.1

package/dist/index.d.cts

@@ -70,6 +70,8 @@ interface PostgresNames {
     readonly schema: string;
     readonly quotedSchema: string;
     readonly events: string;
+    /** Unquoted, unqualified name of {@link events}, for catalog lookups. */
+    readonly eventsTableName: string;
     readonly deliveries: string;
     readonly keySequences: string;
     /** Lane lease rows: one per lane, see {@link LANE_COUNT}. */
@@ -110,8 +112,8 @@ declare function resolvePostgresNames(options?: PostgresSchemaOptions): Postgres
 
 /**
  * Statements that create the schema, tables and indexes, in dependency order,
- * and upgrade a 0.1.0 schema in place. Every statement is idempotent
- * (`IF NOT EXISTS`, or guarded by a check for the 0.1.0 columns). Run them in
+ * and upgrade a 0.1.0 schema and the `jsonb` payload columns of schemas before 0.4.1 in place.
+ * Every statement is idempotent (`IF NOT EXISTS`, or guarded by a check for the old columns). Run them in
  * one transaction and serialize concurrent runs (see
  * {@link PostgresEventStore.setup}), or paste {@link createPostgresSchemaSql}
  * into your own migration tool.
@@ -190,7 +192,18 @@ interface PostgresConnectionOptions extends PostgresEventStoreSettings {
 /** Use another database library through an adapter. The store never closes it. */
 interface PostgresExecutorOptions<TTransaction> extends PostgresEventStoreSettings {
     readonly executor: PostgresExecutor<TTransaction>;
-    readonly pool?: never;
+    /**
+     * Optional `pg` pool on the same database, for example the one an ORM's `pg` driver adapter uses
+     * (`new PrismaPg(pool)`, Kysely's `PostgresDialect`, Drizzle's `node-postgres`). The store never
+     * closes it. With it:
+     * - the statements the store sends outside a transaction (the dispatcher's claims, completions and
+     *   lease renewals, maintenance) run on it as prepared statements (`preparedStatements`), which ORM
+     *   raw queries cannot do; statements in a transaction still go through `executor`;
+     * - with `wakeUp: 'notify'` the store listens for wake-ups with its connection settings, so a
+     *   delivery published in an ORM transaction is dispatched right after that transaction commits,
+     *   instead of after a fixed delay or the next poll.
+     */
+    readonly pool?: Pool;
     readonly connectionString?: never;
     readonly poolConfig?: never;
 }
@@ -239,8 +252,8 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * Creates the schema, tables and indexes if they do not exist. Safe to call
      * from many processes at once: a transaction-scoped advisory lock serializes
      * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
-     * When the lane table already carries the marker of the current statements
-     * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+     * When the lane table already carries the schema marker ({@link version040SchemaMarker})
+     * and the payload columns are `json`, nothing runs and no table is locked, so instances
      * that start next to running dispatchers cannot deadlock with their claims.
      * Skip it (`setupStore: false`) when a migration tool applies
      * `createPostgresSchemaSql()` instead.
@@ -330,4 +343,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.d.ts

@@ -70,6 +70,8 @@ interface PostgresNames {
     readonly schema: string;
     readonly quotedSchema: string;
     readonly events: string;
+    /** Unquoted, unqualified name of {@link events}, for catalog lookups. */
+    readonly eventsTableName: string;
     readonly deliveries: string;
     readonly keySequences: string;
     /** Lane lease rows: one per lane, see {@link LANE_COUNT}. */
@@ -110,8 +112,8 @@ declare function resolvePostgresNames(options?: PostgresSchemaOptions): Postgres
 
 /**
  * Statements that create the schema, tables and indexes, in dependency order,
- * and upgrade a 0.1.0 schema in place. Every statement is idempotent
- * (`IF NOT EXISTS`, or guarded by a check for the 0.1.0 columns). Run them in
+ * and upgrade a 0.1.0 schema and the `jsonb` payload columns of schemas before 0.4.1 in place.
+ * Every statement is idempotent (`IF NOT EXISTS`, or guarded by a check for the old columns). Run them in
  * one transaction and serialize concurrent runs (see
  * {@link PostgresEventStore.setup}), or paste {@link createPostgresSchemaSql}
  * into your own migration tool.
@@ -190,7 +192,18 @@ interface PostgresConnectionOptions extends PostgresEventStoreSettings {
 /** Use another database library through an adapter. The store never closes it. */
 interface PostgresExecutorOptions<TTransaction> extends PostgresEventStoreSettings {
     readonly executor: PostgresExecutor<TTransaction>;
-    readonly pool?: never;
+    /**
+     * Optional `pg` pool on the same database, for example the one an ORM's `pg` driver adapter uses
+     * (`new PrismaPg(pool)`, Kysely's `PostgresDialect`, Drizzle's `node-postgres`). The store never
+     * closes it. With it:
+     * - the statements the store sends outside a transaction (the dispatcher's claims, completions and
+     *   lease renewals, maintenance) run on it as prepared statements (`preparedStatements`), which ORM
+     *   raw queries cannot do; statements in a transaction still go through `executor`;
+     * - with `wakeUp: 'notify'` the store listens for wake-ups with its connection settings, so a
+     *   delivery published in an ORM transaction is dispatched right after that transaction commits,
+     *   instead of after a fixed delay or the next poll.
+     */
+    readonly pool?: Pool;
     readonly connectionString?: never;
     readonly poolConfig?: never;
 }
@@ -239,8 +252,8 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * Creates the schema, tables and indexes if they do not exist. Safe to call
      * from many processes at once: a transaction-scoped advisory lock serializes
      * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
-     * When the lane table already carries the marker of the current statements
-     * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+     * When the lane table already carries the schema marker ({@link version040SchemaMarker})
+     * and the payload columns are `json`, nothing runs and no table is locked, so instances
      * that start next to running dispatchers cannot deadlock with their claims.
      * Skip it (`setupStore: false`) when a migration tool applies
      * `createPostgresSchemaSql()` instead.
@@ -330,4 +343,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, type PgExecutorOptions, type PostgresConnectionOptions, PostgresEventStore, type PostgresEventStoreOptions, type PostgresEventStoreSettings, PostgresExecutor, type PostgresExecutorOptions, type PostgresNames, PostgresParameter, type PostgresPoolOptions, PostgresQueryOptions, PostgresRow, type PostgresSchemaOptions, type PostgresWakeUp, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.js

@@ -228,6 +228,7 @@ function resolvePostgresNames(options = {}) {
     schema,
     quotedSchema,
     events: table("events"),
+    eventsTableName: name("events"),
     deliveries: table("deliveries"),
     keySequences: table("key_sequences"),
     lanes: table("lanes"),
@@ -254,8 +255,17 @@ function laneExpression(keyExpression, eventIdExpression) {
 
 // src/schema.ts
 var SCHEMA_MARKER_DIGITS = 32;
+var PAYLOAD_COLUMNS = `  payload json NOT NULL,
+  headers json NOT NULL DEFAULT '{}'::json,`;
+var JSONB_PAYLOAD_COLUMNS = `  payload jsonb NOT NULL,
+  headers jsonb NOT NULL DEFAULT '{}'::jsonb,`;
 function createPostgresSchemaStatements(options = {}) {
   const names = resolvePostgresNames(options);
+  const statements = schemaBodyStatements(names);
+  statements.push(`COMMENT ON TABLE ${names.lanes} IS '${version040Marker(names, statements)}'`);
+  return statements;
+}
+function schemaBodyStatements(names) {
   const statements = [...eventAndDeliveryStatements(names), ...laneAndCompletionStatements(names)];
   if (names.completionHistory) {
     statements.push(...completionHistoryStatements(names));
@@ -263,7 +273,6 @@ function createPostgresSchemaStatements(options = {}) {
   if (names.schema !== "public") {
     statements.unshift(`CREATE SCHEMA IF NOT EXISTS ${names.quotedSchema}`);
   }
-  statements.push(`COMMENT ON TABLE ${names.lanes} IS '${postgresSchemaMarker(statements)}'`);
   return statements;
 }
 function eventAndDeliveryStatements(names) {
@@ -277,14 +286,14 @@ function eventAndKeySequenceStatements(names) {
   source text NOT NULL,
   key text,
   sequence bigint,
-  payload jsonb NOT NULL,
-  headers jsonb NOT NULL DEFAULT '{}'::jsonb,
+${PAYLOAD_COLUMNS}
   correlation_id text,
   causation_id text,
   occurred_at timestamptz NOT NULL,
   created_at timestamptz NOT NULL,
   handlers text[] NOT NULL DEFAULT '{}'
 )`,
+    upgradePayloadToJson(names),
     `CREATE INDEX IF NOT EXISTS ${names.indexes.eventCreated} ON ${names.events} (created_at, id)`,
     `CREATE TABLE IF NOT EXISTS ${names.keySequences} (
   key text PRIMARY KEY,
@@ -380,6 +389,33 @@ BEGIN
 END
 $relaybus_upgrade$`;
 }
+function upgradePayloadToJson(names) {
+  return `DO $relaybus_payload_json$
+BEGIN
+  IF EXISTS (
+    SELECT 1 FROM pg_attribute
+    WHERE attrelid = to_regclass('${names.events}') AND attname IN ('payload', 'headers')
+      AND atttypid = 'jsonb'::regtype AND NOT attisdropped
+  ) THEN
+    ALTER TABLE ${names.events}
+      ALTER COLUMN headers DROP DEFAULT,
+      ALTER COLUMN payload TYPE json USING payload::json,
+      ALTER COLUMN headers TYPE json USING headers::json,
+      ALTER COLUMN headers SET DEFAULT '{}'::json;
+  END IF;
+END
+$relaybus_payload_json$`;
+}
+function version040SchemaMarker(options = {}) {
+  const names = resolvePostgresNames(options);
+  return version040Marker(names, schemaBodyStatements(names));
+}
+function version040Marker(names, statements) {
+  const conversion = upgradePayloadToJson(names);
+  return postgresSchemaMarker(
+    statements.filter((statement) => statement !== conversion).map((statement) => statement.replace(PAYLOAD_COLUMNS, JSONB_PAYLOAD_COLUMNS))
+  );
+}
 function createPostgresSchemaSql(options = {}) {
   return `${createPostgresSchemaStatements(options).join(";\n\n")};
 `;
@@ -491,6 +527,19 @@ var NotificationListener = class {
     await drop?.();
   }
 };
+
+// src/root-pool-executor.ts
+function withRootPool(executor, root) {
+  return {
+    ...executor.sessionTimeouts === void 0 ? {} : { sessionTimeouts: executor.sessionTimeouts },
+    transaction: (work) => executor.transaction(work),
+    ...executor.transactionWithBudget === void 0 ? {} : {
+      transactionWithBudget: (work, timeoutMs) => executor.transactionWithBudget(work, timeoutMs)
+    },
+    // eslint-disable-next-line relaybus/max-two-params -- PostgresExecutor port signature
+    query: (sql, parameters, transaction, options) => transaction === void 0 ? root.query(sql, parameters, void 0, options) : executor.query(sql, parameters, transaction, options)
+  };
+}
 function text(row, column) {
   return row[column];
 }
@@ -1431,10 +1480,71 @@ var PostgresMaintenance = class {
     });
   }
 };
+
+// src/postgres-setup.ts
+var PostgresSetup = class {
+  #state;
+  /** The conversion of `jsonb` payload columns. */
+  #payloadUpgrade;
+  constructor(state, options) {
+    this.#state = state;
+    this.#payloadUpgrade = upgradePayloadToJson(resolvePostgresNames(options));
+  }
+  /** Implements {@link PostgresEventStore.setup}. */
+  async run() {
+    if (isCurrent(await this.#schemaState())) {
+      return;
+    }
+    await this.#underSetupLock(async (transaction) => {
+      await this.#run(this.#payloadUpgrade, transaction);
+    });
+    await this.#underSetupLock(async (transaction, schema) => {
+      if (schema.marked) {
+        await this.#run(this.#payloadUpgrade, transaction);
+        return;
+      }
+      for (const statement of this.#state.schemaStatements) {
+        await this.#run(statement, transaction);
+      }
+    });
+  }
+  /**
+   * Runs `work` in a transaction under the setup lock, unless the schema became current. The
+   * payload conversion goes first in a transaction of its own, so it holds no other table lock
+   * while it waits for the event table (a completion locks deliveries before the event rows).
+   */
+  async #underSetupLock(work) {
+    await this.#state.executor.transaction(async (transaction) => {
+      await this.#state.executor.query(
+        this.#state.statements.setup.setupLock,
+        [this.#state.setupLockKey],
+        transaction
+      );
+      const schema = await this.#schemaState(transaction);
+      if (!isCurrent(schema)) {
+        await work(transaction, schema);
+      }
+    });
+  }
+  async #run(statement, transaction) {
+    await this.#state.executor.query(statement, [], transaction);
+  }
+  async #schemaState(transaction) {
+    const rows = await this.#state.executor.query(
+      this.#state.statements.setup.schemaCurrent,
+      [this.#state.schemaMarker],
+      transaction
+    );
+    return { marked: rows[0]["marked"] === true, payloadJson: rows[0]["payload_json"] === true };
+  }
+};
+function isCurrent(schema) {
+  return schema.marked && schema.payloadJson;
+}
 var WAKE_UPS = ["notify", "poll"];
 var DEFAULT_PURGE_BATCH_SIZE = 1e3;
 function resolveStoreSettings(options) {
-  const sources = [options.pool, options.connectionString, options.executor].filter(
+  const sources = [options.executor ?? options.pool, options.connectionString].filter(
     (source) => source !== void 0
   );
   if (sources.length !== 1) {
@@ -1505,8 +1615,8 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
       reserved.sequence - count(*) OVER (PARTITION BY incoming.key)
         + row_number() OVER (PARTITION BY incoming.key ORDER BY incoming.ordinal)
     END AS sequence
-  FROM jsonb_to_recordset($1::jsonb) AS incoming (
-    ordinal int, id text, type text, source text, key text, payload jsonb, headers jsonb,
+  FROM json_to_recordset($1::json) AS incoming (
+    ordinal int, id text, type text, source text, key text, payload json, headers json,
     correlation_id text, causation_id text, occurred_at timestamptz, handlers text[])
   LEFT JOIN reserved ON reserved.key = incoming.key
 )`;
@@ -1517,7 +1627,7 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
   INSERT INTO ${this.#names.events}
     (id, type, source, key, sequence, payload, headers, correlation_id, causation_id, occurred_at, created_at, handlers)
   SELECT incoming.id, incoming.type, incoming.source, incoming.key, incoming.sequence,
-    COALESCE(incoming.payload, 'null'::jsonb), COALESCE(incoming.headers, '{}'::jsonb),
+    COALESCE(incoming.payload, 'null'::json), COALESCE(incoming.headers, '{}'::json),
     incoming.correlation_id, incoming.causation_id, incoming.occurred_at, $2::timestamptz,
     COALESCE(incoming.handlers, '{}')
   FROM incoming
@@ -1540,9 +1650,13 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
   RETURNING available_at
 )`;
   }
-  /** One wake-up notification on {@link PostgresNames.notificationChannel}, outside any publishing transaction. */
+  /**
+   * One wake-up notification on {@link PostgresNames.notificationChannel}, outside any publishing
+   * transaction. Returns a boolean column rather than the `void` of `pg_notify`, which some libraries
+   * cannot read (Prisma's raw queries reject a `void` column).
+   */
   get notify() {
-    return `SELECT pg_notify('${this.#names.notificationChannel}', '')`;
+    return `SELECT true AS notified FROM pg_notify('${this.#names.notificationChannel}', '')`;
   }
   /**
    * A CTE `woken` that sends one notification on {@link PostgresNames.notificationChannel} when a row of
@@ -1566,11 +1680,11 @@ WHERE (SELECT count(*) FROM woken) >= 0`;
     return `INSERT INTO ${this.#names.events}
   (id, type, source, key, sequence, payload, headers, correlation_id, causation_id, occurred_at, created_at, handlers)
 SELECT incoming.id, incoming.type, incoming.source, incoming.key, incoming.sequence,
-  COALESCE(incoming.payload, 'null'::jsonb), COALESCE(incoming.headers, '{}'::jsonb),
+  COALESCE(incoming.payload, 'null'::json), COALESCE(incoming.headers, '{}'::json),
   incoming.correlation_id, incoming.causation_id, incoming.occurred_at, $2::timestamptz,
   COALESCE(incoming.handlers, '{}')
-FROM jsonb_to_recordset($1::jsonb) AS incoming (
-  id text, type text, source text, key text, sequence bigint, payload jsonb, headers jsonb,
+FROM json_to_recordset($1::json) AS incoming (
+  id text, type text, source text, key text, sequence bigint, payload json, headers json,
   correlation_id text, causation_id text, occurred_at timestamptz, handlers text[])
 ORDER BY incoming.id
 ON CONFLICT (id) DO NOTHING
@@ -2820,8 +2934,10 @@ var SetupStatements = class {
     return `relaybus:${this.#names.schema}`;
   }
   /**
-   * Whether the lane table carries `marker` as its comment, that is whether the schema statements
-   * that produce that marker already ran. Takes no table lock. Parameters: `[marker]`.
+   * The state of the schema, taking no table lock. Parameters: `[marker]`. Columns: `marked`, whether
+   * the lane table carries `marker` as its comment (the schema statements that produce it already
+   * ran), and `payload_json`, whether the payload and headers columns of the event table are both
+   * `json` (the conversion of the `jsonb` columns of schemas before 0.4.1 ran).
    */
   get schemaCurrent() {
     return `SELECT EXISTS (
@@ -2830,10 +2946,21 @@ var SetupStatements = class {
   JOIN pg_catalog.pg_description AS d
     ON d.objoid = c.oid AND d.classoid = 'pg_catalog.pg_class'::regclass AND d.objsubid = 0
   WHERE n.nspname = '${this.#names.schema}' AND c.relname = '${this.#names.lanesTableName}' AND d.description = $1::text
-) AS current`;
+) AS marked, (
+  SELECT count(*) FROM pg_catalog.pg_attribute AS a
+  JOIN pg_catalog.pg_class AS c ON c.oid = a.attrelid
+  JOIN pg_catalog.pg_namespace AS n ON n.oid = c.relnamespace
+  WHERE n.nspname = '${this.#names.schema}' AND c.relname = '${this.#names.eventsTableName}'
+    AND a.attname IN ('payload', 'headers') AND a.atttypid = 'pg_catalog.json'::pg_catalog.regtype
+    AND NOT a.attisdropped
+) = 2 AS payload_json`;
   }
+  /**
+   * Takes the setup lock. Returns a boolean column rather than the `void` of the lock function, which
+   * some libraries cannot read (Prisma's raw queries reject a `void` column).
+   */
   get setupLock() {
-    return "SELECT pg_advisory_xact_lock(hashtextextended($1::text, 0))";
+    return "SELECT true AS locked FROM pg_advisory_xact_lock(hashtextextended($1::text, 0))";
   }
 };
 
@@ -2864,6 +2991,7 @@ var PostgresEventStore = class {
   #claims;
   #completion;
   #maintenance;
+  #setup;
   #owned = new OwnedConnections();
   constructor(options) {
     const { purgeBatchSize, wakeUp, queryOptions } = resolveStoreSettings(options);
@@ -2877,7 +3005,7 @@ var PostgresEventStore = class {
       statements,
       schemaStatements,
       setupLockKey: statements.setup.setupLockKey,
-      schemaMarker: postgresSchemaMarker(schemaStatements.slice(0, -1)),
+      schemaMarker: version040SchemaMarker(options),
       purgeBatchSize,
       completionHistory: names.completionHistory,
       logger,
@@ -2901,42 +3029,20 @@ var PostgresEventStore = class {
     this.#claims = new PostgresClaims(state);
     this.#completion = new PostgresCompletion(state);
     this.#maintenance = new PostgresMaintenance(state);
+    this.#setup = new PostgresSetup(state, options);
   }
   /**
    * Creates the schema, tables and indexes if they do not exist. Safe to call
    * from many processes at once: a transaction-scoped advisory lock serializes
    * the DDL, so racing `CREATE TABLE IF NOT EXISTS` statements cannot collide.
-   * When the lane table already carries the marker of the current statements
-   * ({@link postgresSchemaMarker}) nothing runs and no table is locked, so instances
+   * When the lane table already carries the schema marker ({@link version040SchemaMarker})
+   * and the payload columns are `json`, nothing runs and no table is locked, so instances
    * that start next to running dispatchers cannot deadlock with their claims.
    * Skip it (`setupStore: false`) when a migration tool applies
    * `createPostgresSchemaSql()` instead.
    */
   async setup() {
-    if (await this.#schemaIsCurrent()) {
-      return;
-    }
-    await this.#state.executor.transaction(async (transaction) => {
-      await this.#state.executor.query(
-        this.#state.statements.setup.setupLock,
-        [this.#state.setupLockKey],
-        transaction
-      );
-      if (await this.#schemaIsCurrent(transaction)) {
-        return;
-      }
-      for (const statement of this.#state.schemaStatements) {
-        await this.#state.executor.query(statement, [], transaction);
-      }
-    });
-  }
-  async #schemaIsCurrent(transaction) {
-    const rows = await this.#state.executor.query(
-      this.#state.statements.setup.schemaCurrent,
-      [this.#state.schemaMarker],
-      transaction
-    );
-    return rows[0]["current"] === true;
+    await this.#setup.run();
   }
   /**
    * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
@@ -3102,7 +3208,12 @@ var PostgresEventStore = class {
 };
 function connect(options, { logger, owned }) {
   if (options.executor !== void 0) {
-    return { executor: options.executor, pool: void 0, ownedPool: void 0 };
+    const { executor: executor2, pool: pool2 } = options;
+    return {
+      executor: pool2 === void 0 ? executor2 : withRootPool(executor2, new PgExecutor(pool2, { logger })),
+      pool: pool2,
+      ownedPool: void 0
+    };
   }
   const pool = options.pool ?? new Pool({
     ...options.poolConfig,