@ultimat3/db 19.0.0 → 19.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/db",
-  "version": "19.0.0",
+  "version": "19.1.0",
   "description": "Postgres access, transactions, migrations and drift detection",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,7 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "19.0.0"
+    "@ultimat3/core": "19.1.0"
   },
   "peerDependencies": {
     "@electric-sql/pglite": ">=0.5.0"

package/src/errors.ts

@@ -19,6 +19,8 @@ import { type DbSqlStateCode, sqlState, sqlStateCode } from './sqlstate';
  */
 export const DB_OWNED_ERROR_CODES = [
   'X_DB_UNAVAILABLE',
+  'X_DB_SCHEMA_STALE',
+  'X_DB_STATEMENT_FAILED',
   'X_DB_UNIQUE_VIOLATION',
   'X_DB_FOREIGN_KEY_VIOLATION',
   'X_DB_SERIALIZATION_FAILURE',
@@ -61,6 +63,8 @@ export type DbErrorCode = (typeof DB_ERROR_CODES)[number];
 
 export const DB_ERROR_TITLES: Readonly<Record<DbOwnedErrorCode, string>> = {
   X_DB_UNAVAILABLE: 'cannot reach the database',
+  X_DB_SCHEMA_STALE: 'the statement names a table or column the database does not have',
+  X_DB_STATEMENT_FAILED: 'the database refused the statement',
   X_DB_UNIQUE_VIOLATION: 'a unique constraint rejected the row',
   X_DB_FOREIGN_KEY_VIOLATION: 'a foreign key constraint rejected the row',
   X_DB_SERIALIZATION_FAILURE: 'the transaction lost a serialization race',
@@ -127,7 +131,9 @@ export const DB_ERROR_RETRY = {
 // a typo or a renamed code is a build error rather than a classification for a code nothing throws.
 //
 // Left to the fail-closed default, deliberately, each for its own reason:
-//   X_DB_UNAVAILABLE            two failures in one code — see the note above
+//   X_DB_UNAVAILABLE            a connection failure — see the note above
+//   X_DB_SCHEMA_STALE           `42P01`/`42703`: the migration is the fix, and no attempt runs it
+//   X_DB_STATEMENT_FAILED       the server's verdict on the SQL; the same SQL gets the same verdict
 //   X_DB_STATEMENT_TIMEOUT      `57014`, and this package's fix for it is "add the index": an edit.
 //                               The queued-behind-a-lock case has its own code, above
 //   X_DB_UNIQUE_VIOLATION       the same row, the same constraint, the same refusal
@@ -171,7 +177,9 @@ export class DbError extends UltimateError {
 export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
   new DbError({
     code: 'X_DB_UNAVAILABLE',
-    cause: detail,
+    // The driver's own words ride along when there are any: `ECONNREFUSED 127.0.0.1:5432` is the
+    // half of "cannot reach the database" an operator acts on, and it was dropped on the floor.
+    cause: sourceError === undefined ? detail : `${detail}: ${renderThrowable(sourceError)}`,
     fix: 'set DATABASE_URL to a reachable Postgres url, or run `x dev` to use the embedded PGlite',
     sourceError,
   });
@@ -186,6 +194,9 @@ export const dbUnavailable = (detail: string, sourceError?: unknown): DbError =>
  * of one; `driverError` substitutes the placeholder when the driver reported none.
  */
 const SQLSTATE_FIXES = Object.freeze<Record<DbSqlStateCode, string>>({
+  X_DB_SCHEMA_STALE:
+    'x db gen "<what changed>" && x db migrate   # the entity is ahead of the schema; ' +
+    'if the migration already exists, only the migrate half is due',
   X_DB_UNIQUE_VIOLATION:
     'upsertAll(rows, { onConflict: [...] }) over the columns {constraint} covers — ' +
     'or catch X_DB_UNIQUE_VIOLATION and answer 409, which is what a raced signup is',
@@ -219,19 +230,31 @@ const UNNAMED_CONSTRAINT = 'the constraint named in cause';
  * given where it is true, and a new SQLSTATE arrives as a new row here rather than as a new
  * `catch` at a call site.
  */
-export const driverError = (detail: string, sourceError: unknown): DbError => {
-  const code = sqlStateCode(sourceError);
-  if (code === undefined) return dbUnavailable(detail, sourceError);
+export const driverError = (statement: string, sourceError: unknown): DbError => {
   const state = sqlState(sourceError);
+  // No SQLSTATE means the failure never reached a server — a refused socket, a closed pool, a
+  // driver that would not load. THAT is unavailability, and it is the only thing that is.
+  if (state === undefined) return dbUnavailable(`statement failed: ${statement}`, sourceError);
+  // A state the table does not classify still proves the server answered: it read the statement
+  // and refused it. `X_DB_STATEMENT_FAILED` says so and carries the server's own words, where
+  // `X_DB_UNAVAILABLE` said "set DATABASE_URL" to a developer whose database was fine.
+  const code = sqlStateCode(sourceError) ?? 'X_DB_STATEMENT_FAILED';
   const constraint = stringField(sourceError, 'constraint');
   return new DbError({
     code,
-    cause: `${detail}: ${renderThrowable(sourceError)} [SQLSTATE ${state ?? '?????'}]`,
+    // The server's SQLSTATE and message FIRST, the statement after: a cause is rendered on one
+    // line and cut when long, and a column list of any width put the one thing an author needs —
+    // `column "host_id" does not exist` — past the cut. The statement is `statementExcerpt`'d by
+    // the caller, so the whole line has a known ceiling.
+    cause: `[SQLSTATE ${state}] ${renderThrowable(sourceError)} — statement: ${statement}`,
     // A FUNCTION as the replacement, never the string: `String.replace` expands `$&`, `` $` ``,
     // `$'` and `$$` inside a replacement literal, and a constraint name is the server's, not
     // ours — `$` is legal in a Postgres identifier, so `posts_$&_key` would splice the matched
     // `{constraint}` back into the fix line an author is meant to paste.
-    fix: SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
+    fix:
+      code === 'X_DB_STATEMENT_FAILED'
+        ? `psql "$DATABASE_URL" -c "<the statement in cause>"   # SQLSTATE ${state} is the server's verdict on it: fix the SQL or the data it names, not the connection`
+        : SQLSTATE_FIXES[code].replace('{constraint}', () => constraint ?? UNNAMED_CONSTRAINT),
     meta: {
       sqlState: state,
       ...(constraint === undefined ? {} : { constraint }),

package/src/pglite.ts

@@ -5,11 +5,12 @@
 
 import { statementAttribution } from './attribution';
 import type { DbConnection, ReservableClient } from './client';
-import { DbError, dbUnavailable } from './errors';
+import { DbError, driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
 import { createTurnQueue } from './pglite-turns';
 import type { SqlFragment } from './sql';
+import { statementExcerpt } from './statement-excerpt';
 import { withStatementSpan } from './statement-span';
 import { inLiveTx } from './transaction';
 
@@ -142,7 +143,12 @@ export function createPgliteClient(options: PgliteOptions = {}): PgliteClient {
     try {
       return await driver.query(fragment.text, fragment.values);
     } catch (error) {
-      throw dbUnavailable(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+      // `driverError`, as `statement-funnel.ts` already does for Bun's driver: this site passed
+      // every failure to `dbUnavailable`, so under `x dev` — which IS this driver when no
+      // `DATABASE_URL` is set — a `select` naming a column whose migration had not run answered
+      // "cannot reach the database" with the fix "set DATABASE_URL", against a database that was
+      // answering fine (measured 2026-09-05). PGlite carries the SQLSTATE on `code`.
+      throw driverError(statementExcerpt(fragment.text), error);
     }
   }
 

package/src/sqlstate.ts

@@ -14,6 +14,8 @@ import { stringField } from '@ultimat3/core';
 export const SQLSTATE = Object.freeze({
   /** `undefined_table` — the ledger's absence is a class, not a message to match on. */
   undefinedTable: '42P01',
+  /** `undefined_column` — an entity edited before the migration that adds the column ran. */
+  undefinedColumn: '42703',
   uniqueViolation: '23505',
   foreignKeyViolation: '23503',
   serializationFailure: '40001',
@@ -70,6 +72,7 @@ export function sqlState(error: unknown): string | undefined {
 
 /** The codes a SQLSTATE can classify into. `errors.ts` owns their titles and their fixes. */
 export type DbSqlStateCode =
+  | 'X_DB_SCHEMA_STALE'
   | 'X_DB_UNIQUE_VIOLATION'
   | 'X_DB_FOREIGN_KEY_VIOLATION'
   | 'X_DB_SERIALIZATION_FAILURE'
@@ -84,6 +87,11 @@ export type DbSqlStateCode =
  * class 53, insufficient resources, and both are answered by asking for fewer connections.
  */
 export const DB_SQLSTATE_CODES: Readonly<Record<string, DbSqlStateCode>> = Object.freeze({
+  // Both class 42 "the schema does not have what this statement names": a table or a column
+  // declared in code whose migration has not run. One code, because the instruction is one
+  // instruction — generate the migration and apply it — and the cause names which it was.
+  [SQLSTATE.undefinedTable]: 'X_DB_SCHEMA_STALE',
+  [SQLSTATE.undefinedColumn]: 'X_DB_SCHEMA_STALE',
   [SQLSTATE.uniqueViolation]: 'X_DB_UNIQUE_VIOLATION',
   [SQLSTATE.foreignKeyViolation]: 'X_DB_FOREIGN_KEY_VIOLATION',
   [SQLSTATE.serializationFailure]: 'X_DB_SERIALIZATION_FAILURE',
@@ -94,7 +102,11 @@ export const DB_SQLSTATE_CODES: Readonly<Record<string, DbSqlStateCode>> = Objec
   [SQLSTATE.outOfMemory]: 'X_DB_POOL_EXHAUSTED',
 } as const);
 
-/** `undefined` when the state is unknown or absent — the caller then reports unavailability. */
+/**
+ * `undefined` when the state is absent or not in the table. What the caller does with that is
+ * `driverError`'s decision, not this file's: a state the table does not name still proves the
+ * statement REACHED a server, which is the opposite of unavailable.
+ */
 export function sqlStateCode(error: unknown): DbSqlStateCode | undefined {
   const state = sqlState(error);
   return state === undefined ? undefined : DB_SQLSTATE_CODES[state];

package/src/statement-funnel.ts

@@ -10,6 +10,7 @@ import { driverError } from './errors';
 import { expectedQueryLoopReason } from './expected-loop';
 import { statementObserver } from './observe';
 import type { SqlFragment } from './sql';
+import { statementExcerpt } from './statement-excerpt';
 import { withStatementSpan } from './statement-span';
 
 export function rowsOf<T>(result: unknown): readonly T[] {
@@ -42,7 +43,7 @@ async function sendOn(
     // read it, so a `23505` from two clicks racing a signup told the operator the database was
     // unreachable and paged on-call for an outage that never happened. Everything the table does
     // not classify is still `X_DB_UNAVAILABLE`, byte for byte.
-    throw driverError(`statement failed: ${fragment.text.slice(0, 120)}`, error);
+    throw driverError(statementExcerpt(fragment.text), error);
   }
 }