@ultimat3/db 1.2.0 → 3.0.0

package/src/index.ts

@@ -2,6 +2,7 @@
 // `@ultimat3/auth`, `@ultimat3/entity`, `@ultimat3/jobs` and the CLI are written against this
 // list, so anything not here is an implementation detail and may change.
 
+export { statementAttribution, withStatementAttribution } from './attribution';
 export type { BranchInfo, BranchOptions, DropBranchOptions, ReapOptions } from './branch';
 export {
   assertBranchName,
@@ -26,17 +27,29 @@ export {
   createPostgresClient,
   db,
   isReservable,
+  POOL_MAX_ENV,
   POOL_PROFILES,
   poolProfileFor,
   setDbClient,
 } from './client';
+export type { DestructiveKind, DestructiveStatement } from './destructive';
+export {
+  DESTRUCTIVE_CAUSE,
+  DESTRUCTIVE_MARKER,
+  destructiveStatements,
+  hasDestructiveMarker,
+  isDestructive,
+} from './destructive';
 export type { DriftDifference, DriftKind, DriftOptions, DriftReport } from './drift';
 export {
+  appTables,
   assertNoDrift,
   checkDrift,
+  declaredSchema,
   diffSchema,
   driftError,
   expectedSchema,
+  FRAMEWORK_TABLE_PREFIX,
 } from './drift';
 export type { DbErrorCode, DbErrorInit } from './errors';
 export {
@@ -48,12 +61,21 @@ export {
   dbDrift,
   dbNotImplemented,
   dbUnavailable,
+  driverError,
   identifierUnsafe,
+  migrateConcurrent,
   migrationConflict,
+  migrationDestructive,
   migrationIrreversible,
-  readonlyViolation,
+  migrationSnapshotMissing,
+  multipleStatements,
+  poolAcquireTimeout,
+  poolMaxInvalid,
+  rollbackStepsInvalid,
+  serializationExhausted,
   sqlUnsafe,
 } from './errors';
+export { expectedQueryLoop, expectedQueryLoopReason } from './expected-loop';
 export type { RecordedStatement, RecordingClient, StubResponse } from './fake';
 export { createRecordingClient } from './fake';
 export type {
@@ -61,15 +83,9 @@ export type {
   EntityDescriptionLike,
   GeneratedMigration,
   GenerateOptions,
-  ParsedIndex,
-} from './generate';
-export {
-  generateMigration,
-  migrationStamp,
-  parseIndexName,
-  slugify,
-  snapshotOf,
+  IndexDescriptionLike,
 } from './generate';
+export { generateMigration, migrationStamp, slugify, snapshotOf } from './generate';
 export type {
   ColumnDescription,
   ForeignKeyDescription,
@@ -91,8 +107,11 @@ export {
   auditLedger,
   checksumOf,
   ensureLedger,
+  isLedgerMissing,
   LEDGER_TABLE,
   MIGRATION_LOCK_KEY,
+  MIGRATION_LOCK_POLL_MS,
+  MIGRATION_LOCK_WAIT_MS,
   migrate,
   migrationChecksum,
   pendingMigrations,
@@ -100,6 +119,8 @@ export {
   rollback,
   runningAppVersion,
 } from './migrate';
+export type { StatementAttribution, StatementEvent, StatementObserver } from './observe';
+export { setStatementObserver, statementObserver } from './observe';
 export type {
   PgliteClient,
   PgliteDriver,
@@ -117,13 +138,19 @@ export {
 } from './pglite';
 export type { PgliteBranchInfo, PgliteBranchOptions } from './pglite-branch';
 export { branchPglite, pgliteBranchDir } from './pglite-branch';
-export type { MutationVerdict, ReadOnlyOptions } from './readonly';
-export { assertReadOnly, inspectStatement, readOnly, stripSqlNoise } from './readonly';
 export type { ReadOnlyQueryOptions, ReadOnlyQueryResult } from './readonly-query';
 export { READONLY_TIMEOUT_MS, readOnlyQuery } from './readonly-query';
 export type { ReadOnlyRoleOptions } from './readonly-role';
 export { ensureReadOnlyRole, grantReadOnlySql, READONLY_ROLE } from './readonly-role';
+export { snapshotJson } from './snapshot-json';
+export { parseSnapshot } from './snapshot-parse';
 export type { SqlFragment } from './sql';
 export { identifier, isSqlFragment, join, literal, raw, sql } from './sql';
+export { stripSqlNoise } from './sql-noise';
+export type { DbSqlStateCode } from './sqlstate';
+export { DB_SQLSTATE_CODES, isRetryableState, SQLSTATE, sqlState, sqlStateCode } from './sqlstate';
+export { statementFingerprint, statementKind, statementVerb } from './statement-shape';
+export { STATEMENT_ATTRIBUTE } from './statement-span';
+export { statementsOf } from './statement-split';
 export type { DbTx, IsolationLevel, TransactionOptions } from './transaction';
 export { beginStatement, currentTx, withTransaction } from './transaction';

package/src/introspect.ts

@@ -17,9 +17,18 @@ export interface ColumnDescription {
 
 export interface IndexDescription {
   readonly name: string;
+  /** Physical columns in **index key order** — the order the planner sorts by, never `attnum`. */
   readonly columns: readonly string[];
   readonly unique: boolean;
   readonly primary: boolean;
+  /**
+   * Partial index predicate as SQL, `null` when the index covers every row. The catalog returns
+   * its own rewriting of the expression (`(deleted_at IS NULL)`), never the author's spelling, so
+   * this is readable and comparable to *itself* — never to a snapshot's text. See `drift.ts`.
+   */
+  readonly where: string | null;
+  /** `desc` only when every key column is descending; `null` is Postgres' own default. */
+  readonly order: 'asc' | 'desc' | null;
 }
 
 export interface ForeignKeyDescription {
@@ -65,6 +74,8 @@ interface IndexRow {
   readonly is_unique: boolean;
   readonly is_primary: boolean;
   readonly columns: readonly string[];
+  readonly predicate: string | null;
+  readonly descending: boolean;
 }
 
 interface ForeignKeyRow {
@@ -90,37 +101,50 @@ export async function introspect(options: IntrospectOptions = {}): Promise<Schem
     order by table_name, ordinal_position
   `);
 
+  // Ordered by the index's own key position, never by `attnum`: `indkey` IS the order the planner
+  // sorts by, and a composite index on `(created_at, org_id)` whose columns were declared the
+  // other way round came back reversed — a description that reads correct and compares wrong.
+  // `indnkeyatts` drops INCLUDE payload columns, which are stored, not keyed.
   const indexes = await client.query<IndexRow>(sql`
     select
       t.relname as table_name,
       i.relname as index_name,
       ix.indisunique as is_unique,
       ix.indisprimary as is_primary,
-      array_agg(a.attname order by a.attnum) as columns
+      pg_get_expr(ix.indpred, ix.indrelid) as predicate,
+      array_agg(a.attname order by k.ord) as columns,
+      bool_and((ix.indoption[k.ord - 1] & 1) = 1) as descending
     from pg_class t
     join pg_namespace n on n.oid = t.relnamespace
     join pg_index ix on ix.indrelid = t.oid
     join pg_class i on i.oid = ix.indexrelid
-    join pg_attribute a on a.attrelid = t.oid and a.attnum = any(ix.indkey)
-    where n.nspname = ${schema} and t.relkind = 'r'
-    group by t.relname, i.relname, ix.indisunique, ix.indisprimary
+    cross join lateral unnest(ix.indkey::smallint[]) with ordinality as k(attnum, ord)
+    join pg_attribute a on a.attrelid = t.oid and a.attnum = k.attnum
+    where n.nspname = ${schema} and t.relkind = 'r' and k.ord <= ix.indnkeyatts
+    group by t.relname, i.relname, ix.indisunique, ix.indisprimary, ix.indpred, ix.indrelid
     order by t.relname, i.relname
   `);
 
+  // `conkey` and `confkey` are unnested TOGETHER, by shared ordinality: they are two halves of one
+  // ordered pairing, and matching each independently with `= any(...)` is a cross product — a
+  // two-column key came back as four source columns against four referenced ones, duplicated and
+  // misaligned. Ordered by `k.ord` (the constraint's own key position), never by `attnum`, for the
+  // same reason `indkey` orders the index query: `references t (y, x)` is not `references t (x, y)`.
   const foreignKeys = await client.query<ForeignKeyRow>(sql`
     select
       src.relname as table_name,
       c.conname as constraint_name,
-      array_agg(sa.attname order by sa.attnum) as columns,
+      array_agg(sa.attname order by k.ord) as columns,
       tgt.relname as referenced_table,
-      array_agg(ta.attname order by ta.attnum) as referenced_columns,
+      array_agg(ta.attname order by k.ord) as referenced_columns,
       c.confdeltype as on_delete
     from pg_constraint c
     join pg_class src on src.oid = c.conrelid
     join pg_class tgt on tgt.oid = c.confrelid
     join pg_namespace n on n.oid = src.relnamespace
-    join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = any(c.conkey)
-    join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = any(c.confkey)
+    cross join lateral unnest(c.conkey, c.confkey) with ordinality as k(src_attnum, tgt_attnum, ord)
+    join pg_attribute sa on sa.attrelid = src.oid and sa.attnum = k.src_attnum
+    join pg_attribute ta on ta.attrelid = tgt.oid and ta.attnum = k.tgt_attnum
     where c.contype = 'f' and n.nspname = ${schema}
     group by src.relname, c.conname, tgt.relname, c.confdeltype
     order by src.relname, c.conname
@@ -149,6 +173,8 @@ export function buildSchema(
         columns: [...row.columns],
         unique: row.is_unique,
         primary: row.is_primary,
+        where: row.predicate,
+        order: row.descending ? ('desc' as const) : null,
       }))
       .sort(byName);
     return {

package/src/libpq-options.ts

@@ -0,0 +1,76 @@
+// Single responsibility: merging the framework's own libpq `options` into whatever the operator
+// already put in `DATABASE_URL`. A connection string is the operator's file, not the framework's,
+// and `searchParams.set` on a key they may have written is a silent overwrite of their setting.
+
+/**
+ * libpq hands `options` to the backend as command-line arguments, split on whitespace with a
+ * backslash escaping the next character. Escapes are kept intact, so re-joining the tokens
+ * reproduces the operator's string byte for byte.
+ */
+export function splitLibpqOptions(options: string): readonly string[] {
+  const tokens: string[] = [];
+  let current = '';
+  let open = false;
+  for (let index = 0; index < options.length; index += 1) {
+    const char = options[index] ?? '';
+    const escaped = options[index + 1];
+    if (char === '\\' && escaped !== undefined) {
+      current += `\\${escaped}`;
+      open = true;
+      index += 1;
+      continue;
+    }
+    if (char.trim() === '') {
+      if (open) tokens.push(current);
+      current = '';
+      open = false;
+      continue;
+    }
+    current += char;
+    open = true;
+  }
+  if (open) tokens.push(current);
+  return tokens;
+}
+
+/**
+ * The three spellings a backend accepts for one GUC on the command line: `-c name=value` as two
+ * arguments, `-cname=value` as one, and `--name=value` (where a hyphen in the name reads as an
+ * underscore). A bare `name=value` token is the second half of the first spelling.
+ */
+const ASSIGNS = (name: string): RegExp => new RegExp(`^(?:-c|--)?${name.replaceAll('_', '[_-]')}=`);
+
+/** Drops every assignment of `name`, and the `-c` that introduced it. */
+function without(tokens: readonly string[], name: string): readonly string[] {
+  const assigns = ASSIGNS(name);
+  const kept: string[] = [];
+  for (const token of tokens) {
+    if (!assigns.test(token)) {
+      kept.push(token);
+      continue;
+    }
+    if (kept.at(-1) === '-c') kept.pop();
+  }
+  return kept;
+}
+
+/**
+ * The operator's `options` with the framework's settings merged in.
+ *
+ * **Precedence: the framework wins on the settings it names, the operator keeps everything else.**
+ * A role's `statement_timeout` is a safety bound the role is sized around — `web`'s 10s is what
+ * stops a slow endpoint holding all 20 pool slots — so a value in the URL may not raise it; but a
+ * `search_path`, an `application_name` or a `-c` an operator added is theirs and must survive.
+ * Enforced by removing the framework's own names before appending, never by position: relying on
+ * "the last `-c` wins" would make the bound depend on backend argument order nobody here measured.
+ */
+export function mergeLibpqOptions(
+  existing: string | null,
+  settings: Readonly<Record<string, string>>,
+): string {
+  let tokens = splitLibpqOptions(existing ?? '');
+  for (const [name, value] of Object.entries(settings)) {
+    tokens = [...without(tokens, name), '-c', `${name}=${value}`];
+  }
+  return tokens.join(' ');
+}