@ultimat3/db 22.14.0 → 23.0.0

package/src/catalog-relations.ts

@@ -0,0 +1,184 @@
+// Single responsibility: the catalog queries for what a TABLE is — the relation, its columns, its
+// constraints, its sequences and its indexes — as flat rows. Nothing here folds or sorts:
+// `introspect-catalog.ts` does, in JS, because `order by` on a name follows the server's collation
+// and two servers do not share one.
+
+import type { DbClient } from './client';
+import { raw, type SqlFragment, sql } from './sql';
+
+/**
+ * "No extension owns this object" — `pg_depend`'s `deptype = 'e'` row, the rule `app-relation.ts`
+ * already holds for relations, asked of whichever catalog the object lives in. Both arguments are
+ * literals at every call site, never data.
+ */
+export const notExtensionOwned = (
+  catalog: 'pg_class' | 'pg_type' | 'pg_proc',
+  oid: string,
+): SqlFragment =>
+  raw(
+    `not exists (select 1 from pg_depend e where e.classid = '${catalog}'::regclass ` +
+      `and e.objid = ${oid} and e.refclassid = 'pg_extension'::regclass and e.deptype = 'e')`,
+  );
+
+export interface TableRow {
+  readonly name: string;
+  readonly persistence: string;
+  readonly replica_identity: string;
+  readonly replica_index: string | null;
+  readonly options: string | null;
+}
+
+export interface ColumnRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly position: number;
+  readonly type: string;
+  readonly not_null: boolean;
+  readonly identity: string;
+  readonly generated: string;
+  readonly expression: string | null;
+  readonly collation: string | null;
+}
+
+export interface ConstraintRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly type: string;
+  readonly definition: string;
+}
+
+export interface SequenceRow {
+  readonly name: string;
+  readonly data_type: string;
+  readonly seq_start: string;
+  readonly seq_increment: string;
+  readonly seq_min: string;
+  readonly seq_max: string;
+  readonly seq_cache: string;
+  readonly seq_cycle: boolean;
+  /** `a` — a `serial` column owns it; `i` — an identity column does; `null` — nothing does. */
+  readonly ownership: string | null;
+  readonly owner_table: string | null;
+  readonly owner_column: string | null;
+}
+
+export interface IndexRow {
+  readonly table_name: string;
+  readonly name: string;
+  readonly definition: string;
+}
+
+/**
+ * Plain tables only. A partition, an inheritance child and a partitioned parent are `relkind`
+ * `r`/`p` rows a `create table (…)` cannot rebuild, so they are named by `unrenderedRows`
+ * (`catalog-objects.ts`) instead of rendered wrong here.
+ */
+export const tableRows = (client: DbClient, schema: string): Promise<readonly TableRow[]> =>
+  client.query<TableRow>(sql`
+    select
+      c.relname as name,
+      c.relpersistence as persistence,
+      c.relreplident as replica_identity,
+      (
+        select i.relname
+        from pg_index x
+        join pg_class i on i.oid = x.indexrelid
+        where x.indrelid = c.oid and x.indisreplident
+      ) as replica_index,
+      array_to_string(c.reloptions, ', ') as options
+    from pg_class c
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema}
+      and c.relkind = 'r'
+      and not c.relispartition
+      and not exists (select 1 from pg_inherits h where h.inhrelid = c.oid)
+      and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** `format_type` and `pg_get_expr`, never `information_schema`: that view answers `ARRAY` and `USER-DEFINED`. */
+export const columnRows = (client: DbClient, schema: string): Promise<readonly ColumnRow[]> =>
+  client.query<ColumnRow>(sql`
+    select
+      c.relname as table_name,
+      a.attname as name,
+      a.attnum as position,
+      format_type(a.atttypid, a.atttypmod) as type,
+      a.attnotnull as not_null,
+      a.attidentity as identity,
+      a.attgenerated as generated,
+      pg_get_expr(d.adbin, d.adrelid) as expression,
+      case when a.attcollation <> t.typcollation then co.collname end as collation
+    from pg_attribute a
+    join pg_class c on c.oid = a.attrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    join pg_type t on t.oid = a.atttypid
+    left join pg_attrdef d on d.adrelid = a.attrelid and d.adnum = a.attnum
+    left join pg_collation co on co.oid = a.attcollation
+    where n.nspname = ${schema} and c.relkind = 'r' and a.attnum > 0 and not a.attisdropped
+  `);
+
+/**
+ * Every constraint a table carries, foreign keys included — the fold routes those to their own
+ * directory. `contype = 'n'` (a NOT NULL recorded as a constraint, Postgres 18) is left out: the
+ * column's own `not null` already says it, and reading it would make the dump differ by server.
+ */
+export const constraintRows = (
+  client: DbClient,
+  schema: string,
+): Promise<readonly ConstraintRow[]> =>
+  client.query<ConstraintRow>(sql`
+    select
+      c.relname as table_name,
+      k.conname as name,
+      k.contype as type,
+      pg_get_constraintdef(k.oid) as definition
+    from pg_constraint k
+    join pg_class c on c.oid = k.conrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = ${schema} and k.contype in ('p', 'u', 'c', 'x', 'f')
+  `);
+
+/** `::text` on every bound: a `bigint` is a string on one driver and a number on the other. */
+export const sequenceRows = (client: DbClient, schema: string): Promise<readonly SequenceRow[]> =>
+  client.query<SequenceRow>(sql`
+    select
+      c.relname as name,
+      format_type(s.seqtypid, null) as data_type,
+      s.seqstart::text as seq_start,
+      s.seqincrement::text as seq_increment,
+      s.seqmin::text as seq_min,
+      s.seqmax::text as seq_max,
+      s.seqcache::text as seq_cache,
+      s.seqcycle as seq_cycle,
+      d.deptype as ownership,
+      t.relname as owner_table,
+      a.attname as owner_column
+    from pg_sequence s
+    join pg_class c on c.oid = s.seqrelid
+    join pg_namespace n on n.oid = c.relnamespace
+    left join pg_depend d
+      on d.classid = 'pg_class'::regclass and d.objid = c.oid
+      and d.refclassid = 'pg_class'::regclass and d.deptype in ('a', 'i')
+    left join pg_class t on t.oid = d.refobjid
+    left join pg_attribute a on a.attrelid = d.refobjid and a.attnum = d.refobjsubid
+    where n.nspname = ${schema} and ${notExtensionOwned('pg_class', 'c.oid')}
+  `);
+
+/** Indexes no constraint backs, on a table or a materialized view. */
+export const indexRows = (client: DbClient, schema: string): Promise<readonly IndexRow[]> =>
+  client.query<IndexRow>(sql`
+    select
+      t.relname as table_name,
+      i.relname as name,
+      pg_get_indexdef(x.indexrelid) as definition
+    from pg_index x
+    join pg_class i on i.oid = x.indexrelid
+    join pg_class t on t.oid = x.indrelid
+    join pg_namespace n on n.oid = t.relnamespace
+    where n.nspname = ${schema}
+      and t.relkind in ('r', 'm')
+      and not exists (
+        select 1 from pg_constraint k
+        where k.conindid = x.indexrelid and k.contype in ('p', 'u', 'x')
+      )
+  `);

package/src/catalog.ts

@@ -0,0 +1,166 @@
+// Single responsibility: the SHAPE of a whole schema as the catalog holds it — every object kind
+// the schema dump renders, in Postgres' own spelling. Distinct from `SchemaDescription`
+// (`introspect.ts`) on purpose: that one is the entity vocabulary a snapshot is diffed in, and a
+// catalog spelling can never compare equal to a generated one. This one is only ever compared to
+// itself, which is why it may carry `pg_get_*def` text verbatim.
+
+export interface CatalogExtension {
+  readonly name: string;
+}
+
+export interface CatalogEnum {
+  readonly kind: 'enum';
+  readonly name: string;
+  /** In `enumsortorder` — the order `create type … as enum` must repeat. */
+  readonly labels: readonly string[];
+}
+
+export interface CatalogConstraint {
+  readonly name: string;
+  /** `pg_get_constraintdef` verbatim: `CHECK ((x > 0))`, `PRIMARY KEY (id)`, `FOREIGN KEY …`. */
+  readonly definition: string;
+}
+
+export interface CatalogDomain {
+  readonly kind: 'domain';
+  readonly name: string;
+  readonly baseType: string;
+  readonly notNull: boolean;
+  readonly default: string | null;
+  readonly checks: readonly CatalogConstraint[];
+}
+
+export type CatalogType = CatalogEnum | CatalogDomain;
+
+/** Every option spelled, defaults included: a clause left out is a clause two servers may default apart. */
+export interface CatalogSequence {
+  readonly name: string;
+  readonly dataType: string;
+  readonly start: string;
+  readonly increment: string;
+  readonly min: string;
+  readonly max: string;
+  readonly cache: string;
+  readonly cycle: boolean;
+}
+
+/** A sequence a `serial` column owns: created before its table, tied to the column after. */
+export interface CatalogOwnedSequence extends CatalogSequence {
+  readonly column: string;
+}
+
+export interface CatalogColumn {
+  readonly name: string;
+  /** `format_type` — `character varying(120)`, `numeric(12,2)`, `timestamp with time zone`. */
+  readonly type: string;
+  readonly notNull: boolean;
+  /** `pg_get_expr` of the default; `null` when there is none or the column is generated. */
+  readonly default: string | null;
+  /** The stored generation expression, when `attgenerated` says the column has one. */
+  readonly generated: string | null;
+  /** `always` / `by default`, with the identity sequence's own options. */
+  readonly identity: {
+    readonly mode: 'always' | 'by default';
+    readonly sequence: CatalogSequence;
+  } | null;
+  /** Only when it differs from the type's own collation. */
+  readonly collation: string | null;
+}
+
+export type CatalogReplicaIdentity =
+  | { readonly kind: 'default' | 'full' | 'nothing' }
+  | { readonly kind: 'index'; readonly index: string };
+
+export interface CatalogTable {
+  readonly name: string;
+  readonly unlogged: boolean;
+  /** `reloptions` joined — `fillfactor=70` — or `null`. */
+  readonly options: string | null;
+  /** In `attnum` order. */
+  readonly columns: readonly CatalogColumn[];
+  /** Primary key, unique, check and exclusion constraints — never a foreign key. */
+  readonly constraints: readonly CatalogConstraint[];
+  readonly sequences: readonly CatalogOwnedSequence[];
+  readonly replicaIdentity: CatalogReplicaIdentity;
+}
+
+/** An index no constraint backs; a constraint's own index is created by the constraint. */
+export interface CatalogIndex {
+  /** The relation it is on — a table, or a materialized view. */
+  readonly table: string;
+  readonly name: string;
+  /** `pg_get_indexdef` verbatim. */
+  readonly definition: string;
+}
+
+export interface CatalogForeignKey extends CatalogConstraint {
+  readonly table: string;
+}
+
+export interface CatalogView {
+  readonly name: string;
+  readonly materialized: boolean;
+  readonly options: string | null;
+  /** `pg_get_viewdef` verbatim, trailing `;` and all. */
+  readonly definition: string;
+}
+
+export interface CatalogFunction {
+  readonly name: string;
+  /** `pg_get_function_identity_arguments` — what tells two overloads apart. */
+  readonly arguments: string;
+  /** `pg_get_functiondef` verbatim. */
+  readonly definition: string;
+}
+
+export interface CatalogTrigger {
+  readonly table: string;
+  readonly name: string;
+  /** `pg_get_triggerdef` verbatim. */
+  readonly definition: string;
+  /** `tgenabled`: `O` origin (the default), `D` disabled, `R` replica, `A` always. */
+  readonly enabled: string;
+}
+
+/**
+ * An object in the schema that the dump has no statement for. Named rather than dropped: a dump
+ * that silently omitted a row-security policy would load into a database that is not the one the
+ * migrations build, and the load-equals-replay check could not see it, because both sides of that
+ * comparison would be blind in the same place.
+ */
+export interface CatalogUnrendered {
+  readonly kind: string;
+  readonly name: string;
+  /** The table it hangs off, when it has one. */
+  readonly table: string | null;
+}
+
+export interface CatalogDescription {
+  readonly schema: string;
+  readonly extensions: readonly CatalogExtension[];
+  readonly types: readonly CatalogType[];
+  /** Sequences no column owns. */
+  readonly sequences: readonly CatalogSequence[];
+  readonly tables: readonly CatalogTable[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly foreignKeys: readonly CatalogForeignKey[];
+  readonly views: readonly CatalogView[];
+  readonly functions: readonly CatalogFunction[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly unrendered: readonly CatalogUnrendered[];
+}
+
+/** Every list empty — the base a test or a caller spreads its one interesting object over. */
+export const emptyCatalog = (schema = 'public'): CatalogDescription => ({
+  schema,
+  extensions: [],
+  types: [],
+  sequences: [],
+  tables: [],
+  indexes: [],
+  foreignKeys: [],
+  views: [],
+  functions: [],
+  triggers: [],
+  unrendered: [],
+});

package/src/client.ts

@@ -4,7 +4,7 @@
 // `Bun.SQL` slice in `bun-sql.ts` and the observed statement funnel in `statement-funnel.ts`, so
 // importing this module never opens a socket.
 
-import { type Role, resolveRole } from '@ultimat3/core';
+import { logger, type Role, renderThrowable, resolveRole } from '@ultimat3/core';
 import {
   type BunSqlDriver,
   type BunSqlReserved,
@@ -17,6 +17,13 @@ import { connectionUrl } from './connection-url';
 // module evaluation, and both sides are `function` declarations, so hoisting covers the TDZ.
 import { defaultClient } from './default-client';
 import { DbError, drainTimeout, driverError } from './errors';
+import {
+  assertListenChannel,
+  type DbSubscription,
+  type ListeningClient,
+  listenUnsupported,
+} from './listen';
+import { type PoolDemand, trackPool } from './pool-gauge';
 import { assertPoolProfile, type PoolProfile, poolProfileFor } from './pool-profile';
 import { reserveWithin } from './pool-reserve';
 import { type SqlFragment, sql } from './sql';
@@ -55,7 +62,7 @@ export interface PostgresClientOptions {
   readonly applicationName?: string | undefined;
 }
 
-export interface PostgresClient extends ReservableClient {
+export interface PostgresClient extends ReservableClient, ListeningClient {
   readonly profile: PoolProfile;
   ping(): Promise<void>;
   close(): Promise<void>;
@@ -68,18 +75,28 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
     ...poolProfileFor(role),
     ...(options.profile ?? {}),
   });
-  let driver: BunSqlDriver | undefined;
+  // The driver and what `db_pool_in_use` / `db_pool_waiting` are derived from (`pool-gauge.ts`),
+  // as ONE value: a pool still draining after `close()` settles its own work against its own
+  // counter, never against the pool that replaced it. Built only once the driver exists, so a
+  // connection string that cannot be built registers no pool in `db_pool_max`.
+  let driver: { readonly pool: BunSqlDriver; readonly demand: PoolDemand } | undefined;
 
-  function connect(): BunSqlDriver {
+  function connect(): { readonly pool: BunSqlDriver; readonly demand: PoolDemand } {
     if (driver !== undefined) return driver;
     const url = connectionUrl(options, profile);
     const Factory = bunSqlFactory();
-    driver = new Factory(url, bunSqlPoolOptions(profile));
+    driver = { pool: new Factory(url, bunSqlPoolOptions(profile)), demand: trackPool(profile.max) };
     return driver;
   }
 
   async function run(fragment: SqlFragment): Promise<unknown> {
-    return runOn(connect(), fragment);
+    const { pool, demand } = connect();
+    demand.enter();
+    try {
+      return await runOn(pool, fragment);
+    } finally {
+      demand.leave();
+    }
   }
 
   const client: PostgresClient = {
@@ -99,11 +116,14 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // (`ERR_POSTGRES_UNSAFE_TRANSACTION`), and a BEGIN that landed on a different connection
       // than the statement after it would not be a transaction at all — which is exactly what
       // `withTransaction` and `readOnlyQuery` depend on being true.
-      const pool = connect();
+      const { pool, demand } = connect();
       let reserved: BunSqlReserved;
+      // Counted from the ASK: a pin queued behind a full pool is exactly what `waiting` reports.
+      demand.enter();
       try {
         reserved = await reserveWithin(pool, profile);
       } catch (error) {
+        demand.leave();
         // Acquiring the pin is the one step that runs outside `runOn`, so an exhausted or
         // unreachable pool would escape as an untyped driver error — and `readOnlyQuery` reaches
         // this line before its first statement, which is how MCP ends up returning something
@@ -126,6 +146,7 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       const release = (): void => {
         if (!held) return;
         held = false;
+        demand.leave();
         // Total by construction — `releaseReserved` owns the reason (`bun-sql.ts`).
         releaseReserved(reserved);
       };
@@ -137,6 +158,30 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
         [Symbol.dispose]: release,
       };
     },
+    async listen(channel, onNotify, onListening): Promise<DbSubscription> {
+      assertListenChannel(channel);
+      const { pool } = connect();
+      if (pool.listen === undefined) throw listenUnsupported('this Bun.SQL');
+      let held: { unlisten(): Promise<void> };
+      try {
+        // The driver's own session, never a pin out of the pool: a reserved connection holds the
+        // LISTEN and surfaces no notification, and it would cost the pool a slot for good.
+        held = await pool.listen(channel, onNotify, onListening);
+      } catch (error) {
+        throw driverError(`LISTEN ${channel}`, error);
+      }
+      let ended: Promise<void> | undefined;
+      return {
+        unlisten: () => {
+          // Best-effort, the rule `releaseReserved` states: the session this would end may be
+          // gone with the pool already, and that is the outcome asked for.
+          ended ??= held.unlisten().catch((error: unknown) => {
+            logger.debug('db.unlisten_failed', { error: renderThrowable(error) });
+          });
+          return ended;
+        },
+      };
+    },
     async ping(): Promise<void> {
       await client.query(sql`select 1`);
     },
@@ -146,9 +191,12 @@ export function createPostgresClient(options: PostgresClientOptions = {}): Postg
       // after it would fail for a reason no caller can see. Clearing first also means a
       // `connect()` racing the await opens a fresh pool instead of joining the one draining. The
       // rejection still reaches the caller — a shutdown that could not drain wants to know.
-      const pool = driver;
+      const closing = driver;
       driver = undefined;
-      if (pool === undefined) return;
+      if (closing === undefined) return;
+      // Only THIS pool's counter leaves the totals; its in-flight work settles against it.
+      closing.demand.close();
+      const { pool } = closing;
       // BOUNDED, `As of 2026-08-27`, and through the driver's OWN option rather than a race here.
       // This was a bare `await pool.close()`, and `Bun.SQL`'s `end()` waits on an outstanding
       // reserved connection without ever giving up — measured three runs per case on Bun 1.3.14

package/src/drift-findings.ts

@@ -27,7 +27,10 @@ export type DriftKind =
   | 'changed-index'
   | 'missing-check'
   | 'missing-foreign-key'
-  | 'changed-foreign-key';
+  | 'changed-foreign-key'
+  // Constructed in `object-drift.ts`: a trigger, function, view, type or sequence in the live
+  // database that replaying the migrations does not create.
+  | 'unexpected-object';
 
 export interface DriftDifference {
   readonly kind: DriftKind;

package/src/dump-drift.ts

@@ -0,0 +1,142 @@
+// Single responsibility: `X_SCHEMA_DUMP_DRIFT` — what it means for a committed schema dump to
+// disagree with the one the migrations produce, and how each disagreement reads. Pure: files in,
+// differences out. Which directory the dump lives in is the caller's fact; paths here are relative.
+
+import { DbError } from './errors';
+import type { SchemaDumpFile } from './schema-dump';
+
+export type SchemaDumpDifferenceKind =
+  | 'missing-file'
+  | 'changed-file'
+  | 'unexpected-file'
+  | 'unloadable'
+  | 'reload-differs';
+
+export interface SchemaDumpDifference {
+  readonly kind: SchemaDumpDifferenceKind;
+  /** Relative to the dump directory. */
+  readonly path: string;
+  readonly cause: string;
+  readonly fix: string;
+}
+
+/** Regenerating is the whole repair for a dump that is merely behind. */
+export const SCHEMA_DUMP_FIX = 'x db gen';
+
+/**
+ * For a dump that regenerating cannot repair. It still starts with the command, because the first
+ * thing to rule out is a dump that is merely stale — and it says what the second failure means,
+ * since nothing the app's author can run fixes a statement the dump renders wrong.
+ */
+const roundTripFix = (path: string): string =>
+  `x db gen   # and when the regenerated dump is refused the same way, ${path} holds an object the dump cannot round-trip: report it with that file and the migration that creates it`;
+
+const byPath = (a: SchemaDumpDifference, b: SchemaDumpDifference): number =>
+  a.path < b.path ? -1 : a.path > b.path ? 1 : 0;
+
+/**
+ * The committed files against the rendered ones, byte for byte, in both directions: a file the
+ * migrations produce and nobody committed, one whose bytes differ, and one on disk that nothing
+ * renders. The last matters as much as the first — a stray `04_tables/old.sql` is a table an
+ * agent reading the directory believes exists.
+ */
+export function compareSchemaDump(
+  committed: readonly SchemaDumpFile[],
+  rendered: readonly SchemaDumpFile[],
+): readonly SchemaDumpDifference[] {
+  const onDisk = new Map(committed.map((file) => [file.path, file.content]));
+  const produced = new Set(rendered.map((file) => file.path));
+  const differences: SchemaDumpDifference[] = [];
+  for (const file of rendered) {
+    const held = onDisk.get(file.path);
+    if (held === file.content) continue;
+    differences.push(
+      held === undefined
+        ? {
+            kind: 'missing-file',
+            path: file.path,
+            cause: `schema dump file ${file.path} is what the migrations produce and is not committed`,
+            fix: SCHEMA_DUMP_FIX,
+          }
+        : {
+            kind: 'changed-file',
+            path: file.path,
+            cause: `schema dump file ${file.path} differs from what the migrations produce`,
+            fix: SCHEMA_DUMP_FIX,
+          },
+    );
+  }
+  for (const file of committed) {
+    if (produced.has(file.path)) continue;
+    differences.push({
+      kind: 'unexpected-file',
+      path: file.path,
+      cause: `schema dump file ${file.path} describes nothing the migrations produce`,
+      fix: SCHEMA_DUMP_FIX,
+    });
+  }
+  return differences.sort(byPath);
+}
+
+/**
+ * Load equals replay, as a comparison: the dump of the migrated database against the dump of a
+ * database built by loading that dump. Any difference means the files are not a cache of the
+ * migrations but a second, lossy source. One finding, naming the first file that came back
+ * different — the rest follow from it.
+ *
+ * Asked only of a dump that claims to be whole. One that names objects in `unrendered.sql` has
+ * already said it is not, and its caller does not ask.
+ */
+export function reloadDifferences(
+  replayed: readonly SchemaDumpFile[],
+  reloaded: readonly SchemaDumpFile[],
+): readonly SchemaDumpDifference[] {
+  const first = compareSchemaDump(reloaded, replayed)[0];
+  if (first === undefined) return [];
+  return [
+    {
+      kind: 'reload-differs',
+      path: first.path,
+      cause: `a database loaded from the schema dump is not the one the migrations build: ${first.path} comes back different`,
+      fix: roundTripFix(first.path),
+    },
+  ];
+}
+
+/** A dump file the database refused, with what the database said about it. */
+export const unloadableDump = (path: string, detail: string): SchemaDumpDifference => ({
+  kind: 'unloadable',
+  path,
+  cause: `schema dump file ${path} does not load: ${detail}`,
+  fix: roundTripFix(path),
+});
+
+export const schemaDumpDrift = (difference: SchemaDumpDifference): DbError =>
+  new DbError({
+    code: 'X_SCHEMA_DUMP_DRIFT',
+    cause: difference.cause,
+    fix: difference.fix,
+    meta: { kind: difference.kind, path: difference.path },
+  });
+
+const DIFFERENCE_KINDS: readonly string[] = [
+  'missing-file',
+  'changed-file',
+  'unexpected-file',
+  'unloadable',
+  'reload-differs',
+] satisfies readonly SchemaDumpDifferenceKind[];
+
+/**
+ * The difference a thrown `X_SCHEMA_DUMP_DRIFT` was built from, or `undefined` for anything else.
+ * `loadSchemaDump` throws; a caller that reports findings wants the value back, and reading it
+ * off the error here keeps `meta`'s shape a fact of this file alone.
+ */
+export function schemaDumpDifferenceOf(error: unknown): SchemaDumpDifference | undefined {
+  if (!(error instanceof DbError) || error.code !== 'X_SCHEMA_DUMP_DRIFT') return undefined;
+  const kind = error.meta?.['kind'];
+  const path = error.meta?.['path'];
+  if (typeof kind !== 'string' || typeof path !== 'string') return undefined;
+  if (!DIFFERENCE_KINDS.includes(kind)) return undefined;
+  return { kind: kind as SchemaDumpDifferenceKind, path, cause: error.cause, fix: error.fix };
+}

package/src/errors.ts

@@ -37,6 +37,7 @@ export const DB_OWNED_ERROR_CODES = [
   'X_MIGRATE_CONCURRENT',
   'X_SQL_UNSAFE',
   'X_BRANCH_EXISTS',
+  'X_SCHEMA_DUMP_DRIFT',
 ] as const;
 
 /**
@@ -81,6 +82,7 @@ export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_MIGRATION_VIEW_DEPENDS: 'a view is compiled against a column this migration retypes',
   X_SQL_UNSAFE: 'SQL was built by string interpolation',
   X_BRANCH_EXISTS: 'that branch database already exists',
+  X_SCHEMA_DUMP_DRIFT: 'the committed schema dump is not what the migrations produce',
 };
 
 // Registered unconditionally, in one call, so a second package claiming one of db's codes fails

package/src/index.ts

@@ -112,6 +112,8 @@ export {
   uniqueColumns,
 } from './invariant-ddl';
 export { constraintExpressionUnsafe, constraintNameUnsafe } from './invariant-errors';
+export type { DbSubscription, ListeningClient } from './listen';
+export { canListen } from './listen';
 export type {
   AppliedMigration,
   LedgerRow,
@@ -166,6 +168,8 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
+export type { LinkedExtensions, PgliteExtensionLoader } from './pglite-extensions';
+export { linkPgliteExtensions } from './pglite-extensions';
 export type { PoolProfile } from './pool-profile';
 export { POOL_MAX_ENV, POOL_PROFILES, poolProfileFor } from './pool-profile';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';