turbine-orm 0.61.0 → 0.62.0

package/dist/cjs/cli/studio.d.ts

@@ -141,6 +141,19 @@ export interface StudioContext {
      * (saved queries persist to `<stateDir>/studio-queries.json`).
      */
     memorySavedQueries?: SavedQueriesFile;
+    /**
+     * Set when a generated metadata file was found but its PII tags could NOT be
+     * read (`PiiScan.ok === false`). Studio then fails CLOSED: every column of
+     * every table is marked `pii`, so the existing enforcement points redact
+     * everything, and this record drives the persistent UI banner explaining why.
+     * Absent when the scan succeeded, when there was no metadata file, or when
+     * `--show-pii` is on.
+     */
+    piiScanFailed?: {
+        path: string;
+        reason: string;
+        columns: number;
+    };
 }
 /**
  * Start the Studio server. Returns a handle with the session token, a pre-built
@@ -204,4 +217,14 @@ export declare function apiCreateSavedQuery(req: IncomingMessage, res: ServerRes
 export declare function apiDeleteSavedQuery(res: ServerResponse, ctx: StudioContext, id: string): void;
 /** The literal replacement value for a redacted PII cell. */
 export declare const PII_REDACTED = "\u2022\u2022 redacted \u2022\u2022";
+/**
+ * Mark every column of every table `pii`, and return how many were touched.
+ *
+ * The fail-closed posture for "the generated metadata exists but its tags are
+ * unreadable". Deliberately expressed as data (tags on the metadata) rather
+ * than as a new flag threaded through the redaction code: every enforcement
+ * point in this file already asks `col.pii === true`, so there is no path that
+ * can forget to consult a separate switch.
+ */
+export declare function forceTagAllColumnsPii(metadata: SchemaMetadata): number;
 export {};

package/dist/cjs/cli/studio.js

@@ -55,6 +55,7 @@ exports.apiRowWrite = apiRowWrite;
 exports.apiListSavedQueries = apiListSavedQueries;
 exports.apiCreateSavedQuery = apiCreateSavedQuery;
 exports.apiDeleteSavedQuery = apiDeleteSavedQuery;
+exports.forceTagAllColumnsPii = forceTagAllColumnsPii;
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
@@ -91,6 +92,7 @@ async function startStudio(options) {
     let dialect;
     let statementTimeout;
     let piiTags = null;
+    let piiScanFailed;
     if (demo) {
         // Seeded in-memory SQLite store: no DATABASE_URL, no network. Each launch
         // starts pristine and nothing is ever persisted.
@@ -139,8 +141,35 @@ async function startStudio(options) {
         // what happened so the CLI can be explicit about it at startup.
         if (options.metadataDir) {
             const source = (0, pii_tags_js_1.loadPiiTags)(options.metadataDir);
-            if (source)
+            if (source && !source.scan.ok) {
+                // FAIL CLOSED. The file exists and is meant to carry the tags, but the
+                // scanner could not prove anything about it (`ok: false` is "we do not
+                // know", never "no tagged columns"). Redacting nothing here and then
+                // reporting a clean tag count is the exact silent-failure shape this
+                // module was rewritten to end, and Studio is also the tool with a
+                // `--write` mode. So every column of every table is marked PII, which
+                // routes through the enforcement points that already exist (row
+                // redaction, builder rows, the write echo, and the orderBy / search /
+                // filter refusals) with no second code path. `--show-pii` is the
+                // override, and it overrides forced tags exactly as it overrides real
+                // ones.
+                piiScanFailed = {
+                    path: source.path,
+                    reason: source.scan.reason ?? 'unrecognized shape',
+                    columns: forceTagAllColumnsPii(metadata),
+                };
+                // `applied` is the count of columns being redacted, which is what it
+                // means to the reader of the startup line. The warning below is what
+                // says these are forced, not declared.
+                piiTags = { path: source.path, applied: piiScanFailed.columns };
+                console.warn(`[turbine studio] WARNING: ${source.path} exists but its PII tags could not be read ` +
+                    `(${piiScanFailed.reason}). Failing closed: EVERY column of every table is redacted, sorting, ` +
+                    'searching, and filtering on any column are refused, and the Query tab is disabled. Re-run ' +
+                    '`turbine generate` to fix this, or pass --show-pii to run unredacted anyway.');
+            }
+            else if (source) {
                 piiTags = { path: source.path, applied: (0, pii_tags_js_1.applyPiiTags)(metadata, source.tags) };
+            }
         }
         statementTimeout = options.adapter?.statementTimeout?.(30) ?? {
             // Postgres rejects parameters in `SET LOCAL` (`SET LOCAL ... = $1` is a
@@ -166,6 +195,7 @@ async function startStudio(options) {
         // live. Non-demo honors the CLI flags.
         writable: demo ? false : options.write === true,
         showPii: demo ? false : options.showPii === true,
+        piiScanFailed,
         demo,
         dialect,
         // Demo never touches disk: saved queries live (and die) with the process,
@@ -438,6 +468,12 @@ async function apiSchema(res, ctx) {
         showPii: ctx.showPii === true,
         // Demo flag drives the in-UI mode switcher + persistent demo banner.
         demo: ctx.demo === true,
+        // Present only when the PII tag scan failed and Studio is redacting
+        // everything as a result. Drives a persistent banner: a screen of redaction
+        // markers with no explanation reads like a bug, not like a safety posture.
+        piiScanFailed: ctx.piiScanFailed
+            ? { path: ctx.piiScanFailed.path, reason: ctx.piiScanFailed.reason, columns: ctx.piiScanFailed.columns }
+            : null,
     });
 }
 /** True when `columnName` on `table` is PII-tagged and currently redacted. */
@@ -903,6 +939,35 @@ async function apiBuilder(req, res, ctx) {
         sendJson(res, 400, { error: unknownTableMessage(tableName, ctx) });
         return;
     }
+    // Fail-closed posture: the generated metadata exists but its PII tags could
+    // not be read, so every column is treated as PII. The Query tab is then
+    // REFUSED outright rather than half-served. A default projection that
+    // excludes every column emits `SELECT  FROM "t"`, which the database answers
+    // with a syntax error, and letting an explicit `select` through would be a
+    // way to name any column in a database whose sensitive columns are, by
+    // assumption, unknown. The Data tab still works and shows every cell
+    // redacted, so the shape of the database is still visible.
+    if (ctx.piiScanFailed && !ctx.showPii) {
+        sendJson(res, 400, {
+            error: `The Query tab is disabled: PII tags could not be read from ${ctx.piiScanFailed.path} ` +
+                `(${ctx.piiScanFailed.reason}), so Studio treats every column as PII. Re-run \`turbine generate\`, or ` +
+                'restart Studio with --show-pii to query unredacted.',
+        });
+        return;
+    }
+    // The same empty-projection trap without the fail-closed posture: a schema
+    // that genuinely tags every column of a table. Explicit `select` is allowed
+    // here (the user named the columns, and the values are redacted on the way
+    // out); only the empty default projection is refused, with a reason instead
+    // of a syntax error.
+    const target = ctx.metadata.tables[tableName];
+    if (target && !ctx.showPii && args.select === undefined && target.columns.every((c) => c.pii === true)) {
+        sendJson(res, 400, {
+            error: `Every column of "${tableName}" is PII-tagged, so the default projection is empty. Name the columns you ` +
+                'want in `select`, or run Studio with --show-pii.',
+        });
+        return;
+    }
     let deferred;
     try {
         const qi = new index_js_1.QueryInterface(ctx.pool, tableName, ctx.metadata, [], {
@@ -936,17 +1001,30 @@ async function apiBuilder(req, res, ctx) {
         const elapsedMs = Date.now() - started;
         if (!ctx.demo)
             await client.query('COMMIT');
-        // Postgres auto-parses json/jsonb relation columns into JS values via its
-        // type parsers; the SQLite demo driver returns them as raw JSON strings. So
-        // in demo mode, parse relation columns back into arrays/objects (walking the
-        // `with` tree) to match the Postgres shape before redaction + serialization.
-        const rawRows = ctx.demo
-            ? parseDemoRelationRows(result.rows, tableName, args.with, ctx.metadata)
-            : result.rows;
-        const redactedRows = ctx.showPii ? rawRows : redactBuilderRows(rawRows, tableName, args.with, ctx.metadata);
+        // Run the driver rows through the QUERY'S OWN transform rather than reading
+        // `result.rows`. The transform is what turns a raw result into the entity
+        // shape the ORM contracts for: column names mapped to camelCase field names,
+        // dates coerced, and relation columns re-nested under the relation name at
+        // every depth (whatever encoding the plan chose, and whatever the driver
+        // handed back, pg's parsed json objects or the SQLite demo driver's raw JSON
+        // strings, which is why this also replaces the demo-only re-parse).
+        //
+        // SECURITY, not cosmetics: `relationLoadStrategy: 'flatten'` projects a
+        // to-one relation's columns FLAT onto the parent row under generated
+        // prefixed aliases (`f0__email`). `redactBuilderRows` redacts a relation's
+        // PII by walking the `with` tree into the NESTED object, so on flat rows it
+        // walked into nothing and every prefixed PII cell was served in the clear.
+        // `assertNoPiiPredicates` deliberately permits `select` on a PII column
+        // because "those values are redacted on the way out", and only the
+        // transform makes that true. The flat shape must never reach redaction.
+        const rows = deferred.transform(result);
+        const redactedRows = ctx.showPii ? rows : redactBuilderRows(rows, tableName, args.with, ctx.metadata);
         sendJson(res, 200, {
             sql: deferred.sql,
-            columns: resultColumns(result, result.rows),
+            // Columns come from the TRANSFORMED rows: `result.fields` names raw SQL
+            // output columns (`created_at`, `f0__email`), which are neither what the
+            // rows are keyed by nor what a user would write in a query.
+            columns: entityResultColumns(redactedRows),
             rows: redactedRows.map((r) => serializeRow(r)),
             rowCount: result.rowCount ?? result.rows.length,
             elapsedMs,
@@ -1310,6 +1388,27 @@ function apiDeleteSavedQuery(res, ctx, id) {
 // ---------------------------------------------------------------------------
 /** The literal replacement value for a redacted PII cell. */
 exports.PII_REDACTED = '•• redacted ••';
+/**
+ * Mark every column of every table `pii`, and return how many were touched.
+ *
+ * The fail-closed posture for "the generated metadata exists but its tags are
+ * unreadable". Deliberately expressed as data (tags on the metadata) rather
+ * than as a new flag threaded through the redaction code: every enforcement
+ * point in this file already asks `col.pii === true`, so there is no path that
+ * can forget to consult a separate switch.
+ */
+function forceTagAllColumnsPii(metadata) {
+    let count = 0;
+    for (const table of Object.values(metadata.tables)) {
+        for (const col of table.columns) {
+            if (col.pii !== true) {
+                col.pii = true;
+                count++;
+            }
+        }
+    }
+    return count;
+}
 /** Shared empty key set for the `--show-pii` fast path (no redaction). */
 const NO_PII_KEYS = new Set();
 /**
@@ -1386,50 +1485,24 @@ function redactBuilderRows(rows, tableName, withClause, metadata) {
     });
 }
 /**
- * Demo-only: parse relation columns that arrive as raw JSON strings from the
- * SQLite driver back into arrays/objects, walking the `with` tree so nested
- * relations are parsed at every level. This mirrors what Postgres' json/jsonb
- * type parsers do automatically, so the builder response shape (and downstream
- * redaction) is identical across engines. Rows without the named relation, or
- * whose value is already a parsed object/array, pass through unchanged.
+ * Column descriptors for rows that have already been through a query's
+ * `transform`, i.e. entity rows keyed by camelCase FIELD name with relations
+ * nested under the relation name.
+ *
+ * Derived from the rows themselves rather than from `result.fields`, which
+ * names raw SQL output columns (`created_at`, or a flatten plan's `f0__email`)
+ * and so would label the grid with keys the rows do not have. Keys are unioned
+ * across every row in first-seen order: a `select` is uniform, but a null
+ * to-one relation and a JSON-shaped row can still differ, and a column missing
+ * from row 0 must not disappear from the header.
  */
-function parseDemoRelationRows(rows, tableName, withClause, metadata) {
-    const table = metadata.tables[tableName];
-    if (!table)
-        return rows;
-    const relEntries = withClause && typeof withClause === 'object'
-        ? Object.entries(withClause).filter(([, v]) => v)
-        : [];
-    if (relEntries.length === 0)
-        return rows;
-    return rows.map((row) => {
-        const out = { ...row };
-        for (const [relName, relVal] of relEntries) {
-            const rel = table.relations[relName];
-            if (!rel)
-                continue;
-            let child = out[relName];
-            if (typeof child === 'string') {
-                try {
-                    child = JSON.parse(child);
-                }
-                catch {
-                    continue;
-                }
-            }
-            const nestedWith = relVal && typeof relVal === 'object' ? relVal.with : undefined;
-            if (Array.isArray(child)) {
-                out[relName] = parseDemoRelationRows(child, rel.to, nestedWith, metadata);
-            }
-            else if (child && typeof child === 'object') {
-                out[relName] = parseDemoRelationRows([child], rel.to, nestedWith, metadata)[0];
-            }
-            else {
-                out[relName] = child;
-            }
-        }
-        return out;
-    });
+function entityResultColumns(rows) {
+    const seen = new Set();
+    for (const row of rows) {
+        for (const key of Object.keys(row))
+            seen.add(key);
+    }
+    return [...seen].map((name) => ({ name, dataTypeID: 0 }));
 }
 /**
  * A fresh CSP nonce for one HTML response. Base64 of 16 random bytes; the value

package/dist/cjs/cli/ui.d.ts

@@ -33,7 +33,7 @@ export declare const symbols: {
     readonly info: "i" | "ℹ";
     readonly warning: "⚠" | "!";
     readonly dot: "." | "∙";
-    readonly line: "-" | "─";
+    readonly line: "─" | "-";
     readonly vertLine: "|" | "│";
     readonly topLeft: "+" | "╭";
     readonly topRight: "+" | "╮";
@@ -70,4 +70,18 @@ export declare function divider(): void;
 export declare function banner(): void;
 export declare function elapsed(startMs: number): string;
 export declare function stripAnsi(s: string): string;
+/**
+ * A query-string parameter whose name ENDS in `password`: libpq's `password`
+ * and `sslpassword`, plus any vendor spelling of the same idea. Group 1 is
+ * `?`/`&` + the key, group 2 is the value, which runs to the next `&`, `#`, or
+ * the end of the string, and may be empty.
+ *
+ * Exported because "does this string carry a secret" and "redact the secret in
+ * this string" must agree on ONE definition. They did not: this redactor knew
+ * about `?password=` while `connectionStringHasPassword` in config.ts did not,
+ * so `turbine init --url` committed a query-form password into
+ * `turbine.config.ts` while printing the redacted spelling of the same string
+ * one line above. config.ts now matches with this exact pattern.
+ */
+export declare const PASSWORD_QUERY_PARAM_PATTERN = "([?&][^=&#]*password)=([^&#]*)";
 export declare function redactUrl(url: string): string;

package/dist/cjs/cli/ui.js

@@ -6,7 +6,7 @@
  * Zero dependencies, raw escape codes only.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Spinner = exports.symbols = exports.bgCyan = exports.bgYellow = exports.bgRed = exports.bgGreen = exports.redBright = exports.yellowBright = exports.cyanBright = exports.greenBright = exports.gray = exports.white = exports.cyan = exports.magenta = exports.blue = exports.yellow = exports.green = exports.red = exports.underline = exports.italic = exports.dim = exports.bold = void 0;
+exports.PASSWORD_QUERY_PARAM_PATTERN = exports.Spinner = exports.symbols = exports.bgCyan = exports.bgYellow = exports.bgRed = exports.bgGreen = exports.redBright = exports.yellowBright = exports.cyanBright = exports.greenBright = exports.gray = exports.white = exports.cyan = exports.magenta = exports.blue = exports.yellow = exports.green = exports.red = exports.underline = exports.italic = exports.dim = exports.bold = void 0;
 exports.box = box;
 exports.table = table;
 exports.header = header;
@@ -228,11 +228,25 @@ function stripAnsi(s) {
 // ---------------------------------------------------------------------------
 // Redact password from connection URL
 // ---------------------------------------------------------------------------
+/**
+ * A query-string parameter whose name ENDS in `password`: libpq's `password`
+ * and `sslpassword`, plus any vendor spelling of the same idea. Group 1 is
+ * `?`/`&` + the key, group 2 is the value, which runs to the next `&`, `#`, or
+ * the end of the string, and may be empty.
+ *
+ * Exported because "does this string carry a secret" and "redact the secret in
+ * this string" must agree on ONE definition. They did not: this redactor knew
+ * about `?password=` while `connectionStringHasPassword` in config.ts did not,
+ * so `turbine init --url` committed a query-form password into
+ * `turbine.config.ts` while printing the redacted spelling of the same string
+ * one line above. config.ts now matches with this exact pattern.
+ */
+exports.PASSWORD_QUERY_PARAM_PATTERN = '([?&][^=&#]*password)=([^&#]*)';
+const PASSWORD_QUERY_PARAM_RE = new RegExp(exports.PASSWORD_QUERY_PARAM_PATTERN, 'gi');
 function redactUrl(url) {
-    return (redactUserinfo(url)
-        // Query-string password params: `password=`, `sslpassword=`, and similar,
-        // case-insensitive. Value runs up to the next `&`, `#`, or end of string.
-        .replace(/([?&][^=&#]*password)=([^&#]*)/gi, '$1=***'));
+    // `String.replace` with a /g regex resets `lastIndex`, so sharing the compiled
+    // instance across calls is safe.
+    return redactUserinfo(url).replace(PASSWORD_QUERY_PARAM_RE, '$1=***');
 }
 /**
  * Replace `<scheme>://<user>:<password>@` with `<scheme>://<user>:***@`, for

package/dist/cjs/client.js

@@ -193,6 +193,133 @@ function warnUnknownConfigKeys(config) {
         // must never be the reason a client fails to construct.
     }
 }
+/**
+ * Two bases that differ ONLY in host, used to detect whether the host pg ends
+ * up with came from the connection string or from pg's own placeholder base.
+ *
+ * pg-connection-string resolves a connection string as `new URL(str,
+ * 'postgres://base')`. A string with no scheme is therefore a RELATIVE url, and
+ * silently inherits the literal host `base`, which is where
+ * `getaddrinfo ENOTFOUND base` comes from. Parsing against two different bases
+ * and comparing the resulting hostnames identifies that case exactly, and
+ * cannot be fooled by a string that genuinely names a host called `base`.
+ */
+const CONNECTION_STRING_PROBE_BASES = ['postgres://turbine-probe-a', 'postgres://turbine-probe-b'];
+/**
+ * Classify a connection string by replaying the parse pg itself performs.
+ *
+ * This is a deliberate mirror of `pg-connection-string`'s `parse()`, in the
+ * same order, because that function IS the oracle: anything it resolves to a
+ * real host/socket is a string pg will connect with, and a validator that
+ * refuses one of those breaks a working deployment. In particular all of these
+ * are usable and must pass:
+ *   - `/var/run/postgresql app` and `/cloudsql/proj:region:instance`, the
+ *     leading-slash unix-socket form (peer auth, Cloud SQL),
+ *   - `socket:/var/run/postgresql?db=app`, the explicit socket scheme,
+ *   - `postgresql:///db`, `postgres:/db`, `postgres://`, all empty-host forms
+ *     that fall back to pg's localhost default,
+ *   - `postgres://user:pw@/db` (the `@/` dummy-host retry) and
+ *     `?host=/var/run/postgresql` (host as a query parameter),
+ *   - anything else that parses as an absolute URL, `localhost:5432` included.
+ *
+ * Only two shapes are not usable: a string with no scheme (pg substitutes its
+ * placeholder host) and a string neither parse attempt can turn into a URL (pg
+ * throws `Invalid URL` from its own constructor).
+ */
+function classifyConnectionString(value) {
+    // Leading slash: pg short-circuits to `{ host: <path>, database: <word 2> }`
+    // before any URL parsing. Unix-domain socket directory or Cloud SQL path.
+    if (value.charAt(0) === '/')
+        return { kind: 'usable' };
+    // pg percent-encodes before parsing, so a string with spaces (or a stray
+    // half-written escape) reaches the URL constructor already encoded.
+    const encoded = / |%[^a-f0-9]|%[a-f0-9][^a-f0-9]/i.test(value)
+        ? encodeURI(value).replace(/%25(\d\d)/g, '%$1')
+        : value;
+    const parseAgainst = (base) => {
+        try {
+            return { url: new URL(encoded, base), dummyHost: false };
+        }
+        catch {
+            // pg's own second attempt: `postgres://user:pw@/db` is not a valid URL,
+            // so it retries with a placeholder authority and treats the host as empty.
+            try {
+                return { url: new URL(encoded.replace('@/', '@___DUMMY___/'), base), dummyHost: true };
+            }
+            catch {
+                return null;
+            }
+        }
+    };
+    const a = parseAgainst(CONNECTION_STRING_PROBE_BASES[0]);
+    const b = parseAgainst(CONNECTION_STRING_PROBE_BASES[1]);
+    if (!a || !b)
+        return { kind: 'unparseable' };
+    // `socket:` is handled by its own branch in pg's parse: the pathname is the
+    // socket directory and the base never contributes.
+    if (a.url.protocol === 'socket:')
+        return { kind: 'usable' };
+    // The dummy-host retry only happens for an absolute URL, so the host is
+    // empty by construction and pg falls back to its localhost default.
+    if (a.dummyHost)
+        return { kind: 'usable' };
+    // A `host=` query parameter wins over the URL authority in pg's parse.
+    if (a.url.searchParams.get('host'))
+        return { kind: 'usable' };
+    return a.url.hostname === b.url.hostname ? { kind: 'usable' } : { kind: 'phantom-host' };
+}
+/**
+ * Reject a connection string pg cannot connect with, at construction, naming
+ * the string as the problem.
+ *
+ * Without this, a typo'd or truncated string is handed to pg, which resolves it
+ * as a URL relative to its own `postgres://base`, so the string silently
+ * becomes a request for a host named `base`. The failure surfaces one query
+ * later as `[TURBINE_E004] Database connection error: getaddrinfo ENOTFOUND
+ * base`, and sends the reader looking for a DNS problem with a host they never
+ * configured.
+ *
+ * The oracle is pg itself (see {@link classifyConnectionString}), not a scheme
+ * pattern. An earlier scheme-matching version of this check refused
+ * `/var/run/postgresql app` and `/cloudsql/project:region:instance`, which are
+ * documented, working unix-socket connection strings, i.e. it broke peer-auth
+ * and Cloud SQL deployments at `new TurbineClient(...)`.
+ *
+ * The empty string never reaches here: the call sites skip a falsy value, which
+ * is exactly what the pool-building branch does with it, so
+ * `connectionString: process.env.DATABASE_URL ?? ''` keeps constructing.
+ */
+function assertUsableConnectionString(value, source) {
+    // Whitespace-only is not empty: it is truthy, so pg WOULD take it, encode it
+    // to `%20%20%20`, and resolve it against its placeholder host. Naming it as
+    // empty is more useful than reporting the phantom host.
+    if (value.trim().length === 0) {
+        throw new errors_js_1.ConnectionError(`[turbine] The ${source} is empty. Expected a Postgres connection string such as ` +
+            '"postgresql://user:password@host:5432/database".');
+    }
+    const verdict = classifyConnectionString(value);
+    if (verdict.kind === 'usable')
+        return;
+    // Never echo the value: it may carry a password, and it is malformed, so no
+    // redaction written against the URL grammar can be trusted on it.
+    const tail = '(Check for a missing "//", a stray quote copied out of a .env file, or a shell-truncated value.) ' +
+        'The value is not included here because it may contain a password.';
+    if (verdict.kind === 'unparseable') {
+        throw new errors_js_1.ConnectionError(`[turbine] The ${source} cannot be parsed as a connection string, pg rejects it with "Invalid URL" ` +
+            '(most often a non-numeric port). Expected something like ' +
+            `"postgresql://user:password@host:5432/database". ${tail}`);
+    }
+    // libpq keyword/value strings land here, and deserve their own sentence:
+    // node-postgres does NOT implement that form, it feeds the whole string to
+    // the URL parser, so `host=localhost dbname=app` becomes a request for the
+    // host `base` with the database `host=localhost dbname=app`.
+    const keywordForm = /^[A-Za-z_][A-Za-z0-9_]*\s*=/.test(value.trimStart())
+        ? 'It looks like a libpq "host=… dbname=…" keyword/value string, which node-postgres does not support. '
+        : '';
+    throw new errors_js_1.ConnectionError(`[turbine] The ${source} names no host: it has no "postgres://" or "postgresql://" scheme, so pg would ` +
+        `resolve it as a relative URL and try to connect to its internal placeholder host. ${keywordForm}` +
+        `Expected something like "postgresql://user:password@host:5432/database". ${tail}`);
+}
 /**
  * Maps isolation level names to SQL. Null-prototype and read through
  * {@link resolveIsolationLevel}, never indexed directly: an inherited key
@@ -234,6 +361,29 @@ const ISOLATION_LEVELS = Object.assign(Object.create(null), {
  * loops, and a loop keyed on it would never fire for the commit-time conflicts
  * that are the main reason to run SERIALIZABLE at all.
  */
+/**
+ * Check out a pooled connection, translating a driver failure into a typed
+ * Turbine error.
+ *
+ * `pool.connect()` is where the first-run failures actually land: wrong
+ * password (SQLSTATE 28P01), no such database (3D000), nothing listening
+ * (ECONNREFUSED), an unverifiable TLS certificate. Unwrapped, every one of
+ * those left `$transaction`, `transaction()` and `connect()` as a raw pg
+ * `DatabaseError` carrying a SQLSTATE in `.code`, the same property Turbine
+ * puts `TURBINE_E0NN` in, so the single error a new user is most likely to see
+ * was the one error the typed-error contract did not cover.
+ *
+ * Query paths need no equivalent: `pool.query()` opens the connection itself
+ * and rejects with the connect error, which the query boundary already wraps.
+ */
+async function acquireConnection(pool) {
+    try {
+        return await pool.connect();
+    }
+    catch (err) {
+        throw (0, errors_js_1.wrapPgError)(err);
+    }
+}
 async function runTxControl(client, sql) {
     try {
         await client.query(sql);
@@ -591,6 +741,39 @@ class TurbineClient {
         // would poison the next, valid, TurbineClient with a phantom conflict.
         const dialect = config.dialect ?? dialect_js_1.postgresDialect;
         const planCacheMode = TurbineClient.resolvePlanCacheMode(config.planCacheMode, dialect);
+        // Refuse a connection string that cannot address a database, before it
+        // reaches pg's permissive parser and comes back one query later as a DNS
+        // error about a fragment of itself. Only the strings this client will
+        // actually USE are checked: with an external pool the connection target is
+        // the caller's, and an explicit host/port/user config makes DATABASE_URL
+        // irrelevant (the same precedence the pool-building branch below applies).
+        // The truthiness checks here mirror the pool-building branch below EXACTLY.
+        // An empty `connectionString` is ignored there (pg ignores it too), so
+        // `connectionString: process.env.DATABASE_URL ?? ''` must keep constructing,
+        // and it still suppresses the DATABASE_URL fallback because
+        // `hasExplicitConnection` tests `!= null`, not truthiness.
+        if (!config.pool) {
+            if (config.connectionString) {
+                assertUsableConnectionString(config.connectionString, 'connectionString');
+            }
+            else if (config.connectionString == null &&
+                config.host == null &&
+                config.port == null &&
+                config.database == null &&
+                config.user == null &&
+                config.password == null &&
+                process.env.DATABASE_URL) {
+                assertUsableConnectionString(process.env.DATABASE_URL, 'DATABASE_URL environment variable');
+            }
+        }
+        for (const [i, replica] of (config.replicas ?? []).entries()) {
+            // Only string replicas are ours to open; a PgCompatPool entry is already
+            // connected by its owner. An empty string is skipped for the same reason
+            // as above: pg ignores a falsy connectionString and uses its defaults.
+            if (typeof replica === 'string' && replica) {
+                assertUsableConnectionString(replica, `replicas[${i}] connection string`);
+            }
+        }
         /**
          * Parse int8 (bigint, OID 20) as JavaScript number instead of string.
          * Safe for values up to Number.MAX_SAFE_INTEGER (9,007,199,254,740,991).
@@ -1311,7 +1494,7 @@ class TurbineClient {
      * ```
      */
     async transaction(fn) {
-        const client = await this.pool.connect();
+        const client = await acquireConnection(this.pool);
         /**
          * Only true once BEGIN has actually succeeded. If BEGIN itself throws
          * (e.g. a single-writer engine's transaction gate times out or rejects a
@@ -1358,7 +1541,7 @@ class TurbineClient {
         // Resolve the isolation level BEFORE taking a pool slot: a bad argument is
         // the caller's bug and should not cost a connection to discover.
         const isolationSql = resolveIsolationLevel(options?.isolationLevel);
-        const client = await this.pool.connect();
+        const client = await acquireConnection(this.pool);
         const timeout = options?.timeout;
         /**
          * Track whether the connection has already been released so the finally
@@ -1682,7 +1865,7 @@ class TurbineClient {
      * Throws if the connection fails.
      */
     async connect() {
-        const client = await this.pool.connect();
+        const client = await acquireConnection(this.pool);
         try {
             await client.query('SELECT 1');
             if (this.logging) {

package/dist/cjs/errors.d.ts

@@ -53,10 +53,29 @@ export type ErrorMessageMode = 'safe' | 'verbose';
  *     clause (e.g. `where: { id, email }`). Values are redacted.
  *   - `'verbose'`: the message includes the full JSON-serialized where
  *     clause (e.g. `where: {"id":1,"email":"alice@x.com"}`).
+ *
+ * SCOPE, stated precisely because the useful version of this contract is the
+ * one that is true. 'safe' mode redacts row values from the surfaces Turbine
+ * OWNS: its own error messages, and the `detail` field of a driver error it
+ * wraps and attaches as `.cause` (see redactCauseForMode).
+ *
+ * It is NOT a blanket guarantee that no row value can be reached from a thrown
+ * error. A driver error whose SQLSTATE {@link wrapPgError} does not classify is
+ * returned UNCHANGED, and some of those carry a value in the `message` field
+ * itself, where nothing can be removed without destroying the diagnosis:
+ * `22P02 invalid input syntax for type integer: "alice@example.com"` is the
+ * common one. Treat 'safe' mode as removing Turbine's own contribution to the
+ * leak, not as a log-scrubbing boundary.
  */
 export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
 /** Returns the current NotFoundError message mode. Exported for tests. */
 export declare function getErrorMessageMode(): ErrorMessageMode;
+/**
+ * The marker left where a driver `detail` string was removed in 'safe' mode.
+ * Re-exported from the package root so tests and callers writing log
+ * assertions can match on it without hardcoding the wording.
+ */
+export declare const REDACTED_DETAIL = "[redacted by turbine errorMessages:\"safe\"]";
 /**
  * Render a user-supplied `where` / `connect` target for a "no row found" error
  * message, honoring the global {@link ErrorMessageMode}. In 'safe' mode (the
@@ -122,13 +141,29 @@ export declare class ValidationError extends TurbineError {
 }
 /** Thrown when a database connection fails */
 export declare class ConnectionError extends TurbineError {
+    /**
+     * The driver code that produced this error: a Postgres SQLSTATE (`28P01`
+     * wrong password, `3D000` no such database, `08006` connection failure, ...)
+     * or a Node socket/TLS code (`ECONNREFUSED`, `CERT_HAS_EXPIRED`, ...).
+     *
+     * Exposed because E004 covers causes with very different remedies, and the
+     * alternative for a caller who needs to tell "wrong password" from "server
+     * down" is matching on `.message` text or reaching into `.cause`, both of
+     * which are exactly the untyped handling this error class exists to remove.
+     * Undefined when Turbine raised the error itself rather than wrapping a
+     * driver error (a malformed connection string, a subscription on an HTTP
+     * pool).
+     */
+    readonly sqlstate?: string;
     /**
      * @param message human-readable connection failure description.
      * @param options optional pg/driver `cause` to preserve, used when wrapping a
-     *   connection-class driver error via `wrapPgError`.
+     *   connection-class driver error via `wrapPgError`, plus the driver `code`
+     *   that classified it.
      */
     constructor(message: string, options?: {
         cause?: unknown;
+        sqlstate?: string;
     });
 }
 /** Thrown when a relation reference is invalid */
@@ -363,6 +398,8 @@ export declare class ReadOnlyError extends TurbineError {
  *   40P01 (deadlock_detected)     -> DeadlockError       (retryable)
  *   40001 (serialization_failure) -> SerializationFailureError (retryable)
  *   57014 (query_canceled)        -> TimeoutError (server-side statement_timeout)
+ *   28P01 / 28000 (auth refused)  -> ConnectionError, with a remediation hint
+ *   3D000 (no such database)      -> ConnectionError, with a remediation hint
  *   connection-class codes        -> ConnectionError (see CONNECTION_ERROR_CODES)
  *
  * The original pg error is preserved as `.cause` on the wrapped error.