@relaybus/postgres 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-CfJgktC6.cjs';
-import { RelayBusLogger, EventStore, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
+import { P as PostgresExecutor, a as PostgresIsolatedTransactionOptions, b as PostgresParameter, c as PostgresQueryOptions, d as PostgresRow } from './executor-Bt90w33Q.cjs';
+import { RelayBusLogger, EventStore, TransactionIsolationLevel, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
 import { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
@@ -43,6 +43,11 @@ declare class PgExecutor implements PostgresExecutor<PoolClient> {
      * connection that already keeps this budget only gets `BEGIN`.
      */
     transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+     * with the `BEGIN` of the same simple query, before the budget's first statement.
+     */
+    transactionWithIsolation<T>(work: (transaction: PoolClient) => Promise<T>, { isolationLevel, timeoutMs }: PostgresIsolatedTransactionOptions): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -70,6 +75,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 +117,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.
@@ -250,13 +257,21 @@ 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.
      */
     setup(): Promise<void>;
+    /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+    readonly isolationLevels: readonly TransactionIsolationLevel[];
+    /**
+     * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+     * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+     * test with {@link PostgresExecutor.isSerializationFailure}.
+     */
+    isSerializationFailure(error: unknown): boolean;
     /**
      * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
      * the server holds the transaction to the budget: `statement_timeout`, and for executors with
@@ -264,6 +279,9 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
      * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
      * created they are kept per connection and sent only when the connection does not have them yet.
+     * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+     * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+     * ISOLATION LEVEL ...` before the budget statement.
      */
     transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
@@ -341,5 +359,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresIsolatedTransactionOptions, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
 export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { P as PostgresExecutor, a as PostgresParameter, b as PostgresQueryOptions, c as PostgresRow } from './executor-CfJgktC6.js';
-import { RelayBusLogger, EventStore, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
+import { P as PostgresExecutor, a as PostgresIsolatedTransactionOptions, b as PostgresParameter, c as PostgresQueryOptions, d as PostgresRow } from './executor-Bt90w33Q.js';
+import { RelayBusLogger, EventStore, TransactionIsolationLevel, EventStoreTransactionOptions, AppendEntry, AppendResult, ClaimRequest, ClaimedDelivery, LeaseReference, ErrorInfo, DeliveryQuery, DeliveryRecord, PurgeRequest, PurgeResult, EventStoreStatistics, CloseOptions, RelayBusError } from '@relaybus/core';
 import { PoolClient, Pool, PoolConfig } from 'pg';
 
 interface PgExecutorOptions {
@@ -43,6 +43,11 @@ declare class PgExecutor implements PostgresExecutor<PoolClient> {
      * connection that already keeps this budget only gets `BEGIN`.
      */
     transactionWithBudget<T>(work: (transaction: PoolClient) => Promise<T>, timeoutMs: number): Promise<T>;
+    /**
+     * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+     * with the `BEGIN` of the same simple query, before the budget's first statement.
+     */
+    transactionWithIsolation<T>(work: (transaction: PoolClient) => Promise<T>, { isolationLevel, timeoutMs }: PostgresIsolatedTransactionOptions): Promise<T>;
     query(sql: string, parameters: readonly PostgresParameter[], transaction?: PoolClient, options?: PostgresQueryOptions): Promise<readonly PostgresRow[]>;
 }
 
@@ -70,6 +75,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 +117,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.
@@ -250,13 +257,21 @@ 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.
      */
     setup(): Promise<void>;
+    /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+    readonly isolationLevels: readonly TransactionIsolationLevel[];
+    /**
+     * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+     * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+     * test with {@link PostgresExecutor.isSerializationFailure}.
+     */
+    isSerializationFailure(error: unknown): boolean;
     /**
      * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
      * the server holds the transaction to the budget: `statement_timeout`, and for executors with
@@ -264,6 +279,9 @@ declare class PostgresEventStore<TTransaction = PoolClient> implements EventStor
      * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
      * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
      * created they are kept per connection and sent only when the connection does not have them yet.
+     * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+     * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+     * ISOLATION LEVEL ...` before the budget statement.
      */
     transaction<T>(work: (transaction: TTransaction) => Promise<T>, options?: EventStoreTransactionOptions): Promise<T>;
     /**
@@ -341,5 +359,5 @@ declare class ReconcileFailedError extends RelayBusError {
     readonly code: string;
 }
 
-export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
+export { PgExecutor, PostgresEventStore, PostgresExecutor, PostgresIsolatedTransactionOptions, PostgresParameter, PostgresQueryOptions, PostgresRow, ReconcileFailedError, createPostgresSchemaSql, createPostgresSchemaStatements, resolvePostgresNames };
 export type { PgExecutorOptions, PostgresConnectionOptions, PostgresEventStoreOptions, PostgresEventStoreSettings, PostgresExecutorOptions, PostgresNames, PostgresPoolOptions, PostgresSchemaOptions, PostgresWakeUp };

package/dist/index.js

@@ -1,43 +1,10 @@
+import { isolationKeywords, inIsolatedTransaction } from './chunk-FY65AUUF.js';
+import { SESSION_DEFAULTS_SQL, budgetValue, inBudgetedTransaction, budgetSettingsSql } from './chunk-UDBN4RRV.js';
 import { createHash } from 'crypto';
-import { ConfigurationError, RelayBusError, systemClock } from '@relaybus/core';
+import { ConfigurationError, RelayBusError, TRANSACTION_ISOLATION_LEVELS, systemClock } from '@relaybus/core';
 import { LaneLeaseTokenFormat, HandedOutLedger, PositiveInteger, schedule, OwnerSerializedClaims, LeaseSettlement, CompositeKey, DeliveryLeaseIdentity } from '@relaybus/core/internal';
 import { Client, Pool } from 'pg';
 
-// src/pg-executor.ts
-
-// src/transaction-timeouts.ts
-function budgetSettingsSql({ value, sessionTimeouts, scope }) {
-  const local = scope === "transaction";
-  const statementTimeout = `SELECT set_config('statement_timeout', ${value}, ${local})`;
-  if (!sessionTimeouts) {
-    return statementTimeout;
-  }
-  return `${statementTimeout}, set_config('idle_in_transaction_session_timeout', ${value}, ${local}), CASE WHEN current_setting('server_version_num')::int >= 170000 THEN set_config('transaction_timeout', ${value}, ${local}) END`;
-}
-var SESSION_DEFAULTS_SQL = "SELECT set_config(name, reset_val, false) FROM pg_settings WHERE name IN ('statement_timeout', 'idle_in_transaction_session_timeout', 'transaction_timeout')";
-function budgetValue(timeoutMs) {
-  return `${Math.ceil(timeoutMs)}ms`;
-}
-function inBudgetedTransaction(state, {
-  work,
-  timeoutMs
-}) {
-  const { executor } = state;
-  if (executor.transactionWithBudget !== void 0) {
-    return executor.transactionWithBudget(work, timeoutMs);
-  }
-  const sql = budgetSettingsSql({
-    value: "$1",
-    sessionTimeouts: executor.sessionTimeouts === true,
-    scope: "transaction"
-  });
-  return executor.transaction(async (transaction) => {
-    await state.query({ sql, parameters: [budgetValue(timeoutMs)], transaction });
-    return work(transaction);
-  });
-}
-
-// src/pg-executor.ts
 var FOREIGN_SESSION_ERRORS = /* @__PURE__ */ new Set(["26000", "42P05"]);
 var STATEMENT_NAME_DIGITS = 24;
 var PgExecutor = class {
@@ -67,14 +34,28 @@ var PgExecutor = class {
    * connection that already keeps this budget only gets `BEGIN`.
    */
   transactionWithBudget(work, timeoutMs) {
+    return this.#transaction(work, this.#budgetStart(timeoutMs, "BEGIN"));
+  }
+  /**
+   * Like {@link PgExecutor.transactionWithBudget} with `BEGIN ISOLATION LEVEL ...`: the level is set
+   * with the `BEGIN` of the same simple query, before the budget's first statement.
+   */
+  transactionWithIsolation(work, { isolationLevel, timeoutMs }) {
+    return this.#transaction(
+      work,
+      this.#budgetStart(timeoutMs, `BEGIN ISOLATION LEVEL ${isolationKeywords(isolationLevel)}`)
+    );
+  }
+  /** How a transaction starts on a connection when it is held to `timeoutMs`; `begin` is the `BEGIN` statement. */
+  #budgetStart(timeoutMs, begin) {
     const value = budgetValue(timeoutMs);
     const settings = (scope) => budgetSettingsSql({ value: `'${value}'`, sessionTimeouts: true, scope });
-    return this.#transaction(work, (client) => {
+    return (client) => {
       if (!this.#keepsSessionBudget()) {
-        return { begin: `BEGIN; ${settings("transaction")}` };
+        return { begin: `${begin}; ${settings("transaction")}` };
       }
-      return this.#sessionValues.get(client) === value ? { begin: "BEGIN" } : { begin: `BEGIN; ${settings("session")}`, sessionValue: value };
-    });
+      return this.#sessionValues.get(client) === value ? { begin } : { begin: `${begin}; ${settings("session")}`, sessionValue: value };
+    };
   }
   #recordSession(client, sessionValue) {
     if (sessionValue === null) {
@@ -228,6 +209,7 @@ function resolvePostgresNames(options = {}) {
     schema,
     quotedSchema,
     events: table("events"),
+    eventsTableName: name("events"),
     deliveries: table("deliveries"),
     keySequences: table("key_sequences"),
     lanes: table("lanes"),
@@ -254,8 +236,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 +254,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 +267,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 +370,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")};
 `;
@@ -500,10 +517,38 @@ function withRootPool(executor, root) {
     ...executor.transactionWithBudget === void 0 ? {} : {
       transactionWithBudget: (work, timeoutMs) => executor.transactionWithBudget(work, timeoutMs)
     },
+    ...executor.transactionWithIsolation === void 0 ? {} : {
+      transactionWithIsolation: (work, options) => executor.transactionWithIsolation(work, options)
+    },
+    ...executor.isSerializationFailure === void 0 ? {} : { isSerializationFailure: (error) => executor.isSerializationFailure(error) },
     // 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)
   };
 }
+
+// src/serialization-failure.ts
+var SERIALIZATION_FAILURE = "40001";
+var PRISMA_WRITE_CONFLICT = "P2034";
+var CONFLICT_CODES = /* @__PURE__ */ new Set([
+  SERIALIZATION_FAILURE,
+  PRISMA_WRITE_CONFLICT
+]);
+var MAXIMUM_DEPTH = 6;
+var WRAPPED_ERROR_KEYS = ["cause", "driverError", "originalError"];
+function isPostgresSerializationFailure(error, depth = 0) {
+  if (typeof error !== "object" || error === null || depth > MAXIMUM_DEPTH) {
+    return false;
+  }
+  const shape = error;
+  if (CONFLICT_CODES.has(shape.code) || shape.originalCode === SERIALIZATION_FAILURE) {
+    return true;
+  }
+  const meta = shape.meta;
+  if (isPostgresSerializationFailure(meta, depth + 1) || isPostgresSerializationFailure(meta?.driverAdapterError, depth + 1)) {
+    return true;
+  }
+  return WRAPPED_ERROR_KEYS.some((key) => isPostgresSerializationFailure(shape[key], depth + 1));
+}
 function text(row, column) {
   return row[column];
 }
@@ -1444,6 +1489,67 @@ 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) {
@@ -1518,8 +1624,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
 )`;
@@ -1530,7 +1636,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
@@ -1583,11 +1689,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
@@ -2837,8 +2943,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 (
@@ -2847,7 +2955,14 @@ 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
@@ -2885,6 +3000,7 @@ var PostgresEventStore = class {
   #claims;
   #completion;
   #maintenance;
+  #setup;
   #owned = new OwnedConnections();
   constructor(options) {
     const { purgeBatchSize, wakeUp, queryOptions } = resolveStoreSettings(options);
@@ -2898,7 +3014,7 @@ var PostgresEventStore = class {
       statements,
       schemaStatements,
       setupLockKey: statements.setup.setupLockKey,
-      schemaMarker: postgresSchemaMarker(schemaStatements.slice(0, -1)),
+      schemaMarker: version040SchemaMarker(options),
       purgeBatchSize,
       completionHistory: names.completionHistory,
       logger,
@@ -2922,42 +3038,30 @@ 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);
-      }
-    });
+    await this.#setup.run();
   }
-  async #schemaIsCurrent(transaction) {
-    const rows = await this.#state.executor.query(
-      this.#state.statements.setup.schemaCurrent,
-      [this.#state.schemaMarker],
-      transaction
-    );
-    return rows[0]["current"] === true;
+  /** Every level PostgreSQL has (it runs `read uncommitted` as `read committed`, which the bus does not offer). */
+  isolationLevels = TRANSACTION_ISOLATION_LEVELS;
+  /**
+   * True for a serialization failure (SQLSTATE `40001`) raised through any executor, including
+   * Prisma's `P2034` and the wrappers of TypeORM and Drizzle; a custom executor can add its own
+   * test with {@link PostgresExecutor.isSerializationFailure}.
+   */
+  isSerializationFailure(error) {
+    return isPostgresSerializationFailure(error) || this.#state.executor.isSerializationFailure?.(error) === true;
   }
   /**
    * Runs `work` in a transaction of the executor. With `options.timeoutMs` (from `bus.transaction`)
@@ -2966,6 +3070,9 @@ var PostgresEventStore = class {
    * `transaction_timeout`, all scoped to the transaction. An executor with `transactionWithBudget`
    * (`PgExecutor`) sets them with `BEGIN`, so the budget costs no round trip; on a pool the store
    * created they are kept per connection and sent only when the connection does not have them yet.
+   * With `options.isolationLevel` the transaction runs at that level: `PgExecutor` sends it with
+   * `BEGIN ISOLATION LEVEL ...` (no extra round trip), any other executor as `SET TRANSACTION
+   * ISOLATION LEVEL ...` before the budget statement.
    */
   async transaction(work, options) {
     const own = { wake: false };
@@ -2977,12 +3084,20 @@ var PostgresEventStore = class {
         this.#state.ownTransactions.delete(transaction);
       }
     };
-    const result = await (options === void 0 ? this.#state.executor.transaction(tracked) : inBudgetedTransaction(this.#state, { work: tracked, timeoutMs: options.timeoutMs }));
+    const result = await this.#open(tracked, options);
     if (own.wake) {
       this.#appender.wakeAfterCommit();
     }
     return result;
   }
+  /** Opens the transaction `work` runs in: plain, held to the budget, or at an isolation level too. */
+  #open(work, options) {
+    if (options === void 0) {
+      return this.#state.executor.transaction(work);
+    }
+    const { timeoutMs, isolationLevel } = options;
+    return isolationLevel === void 0 ? inBudgetedTransaction(this.#state, { work, timeoutMs }) : inIsolatedTransaction(this.#state, { work, timeoutMs, isolationLevel });
+  }
   /**
    * Writes the entries in `transaction`, normally with one statement
    * (`AppendStatements.insertFreshEvents`): keyed events reserve their sequence numbers (locking