turbine-orm 0.65.0 → 0.66.0

package/dist/dialect.d.ts

@@ -220,6 +220,51 @@ export interface LimitOffsetInput {
     /** Whether the outer SELECT already carries an ORDER BY (so none must be injected). */
     hasOrderBy: boolean;
 }
+/**
+ * Inputs for {@link Dialect.buildPartitionLimit}, the per-correlation-key row
+ * bound the batched relation loader pushes into its follow-up query.
+ *
+ * The follow-up is one flat `WHERE fk = ANY($1)` over EVERY parent's children,
+ * so a trailing `LIMIT n` would cap the TOTAL rather than the per-parent count.
+ * A window function is the portable-in-shape way to say "at most n rows per
+ * key": rank inside the partition, then keep the ranks at or below the bound.
+ *
+ * The loader hands over the compiled child SELECT and the pieces it cannot
+ * spell engine-independently; the dialect owns the SQL text (and its aliases),
+ * exactly like {@link buildLimitOffset} and {@link buildRelationSubquery}.
+ */
+export interface PartitionLimitInput {
+    /** The compiled child SELECT, to be wrapped as a derived table. */
+    innerSql: string;
+    /** RAW (unquoted) correlation column to partition by. */
+    partitionColumn: string;
+    /**
+     * The window's (and the outer result's) ordering, as RAW column names.
+     *
+     * NEVER EMPTY, and never a partial order: the loader only asks for this
+     * rewrite when the relation's `orderBy` covers a NOT NULL unique key of the
+     * target table, so no two rows of a partition can tie. That precondition is
+     * the whole licence for the rewrite. The join plan takes its `limit` with a
+     * per-parent `ORDER BY … LIMIT n` and this takes it with a rank over one flat
+     * result, and where ties exist the two are each free to keep different rows,
+     * which was measured happening (see `partitionOrderBy` in
+     * query/batched-loader.ts). Anything short of a total order therefore keeps
+     * the client-side slice instead of arriving here.
+     */
+    orderBy: readonly {
+        column: string;
+        direction: 'ASC' | 'DESC';
+        nulls?: 'FIRST' | 'LAST';
+    }[];
+    /** SQL-ready placeholder for the bound (`$3`, `?`, …). */
+    limitPlaceholder: string;
+    /**
+     * RAW name of the rank column the wrapper adds. It is part of the projection
+     * (`SELECT <outer>.*`), so the CALLER must remove it from each raw row before
+     * parsing, or it would surface as an extra field on every child entity.
+     */
+    rankColumn: string;
+}
 /**
  * Everything an engine needs to OVERRIDE nested-relation subquery generation, for
  * dialects whose JSON-aggregation shape is fundamentally different from PostgreSQL's
@@ -345,6 +390,37 @@ export interface Dialect {
     readonly supportsUpsertUpdateWhere?: boolean;
     /** Whether this dialect/engine supports pgvector distance ops (KNN / distance WHERE). */
     readonly supportsVector: boolean;
+    /**
+     * Whether this dialect/engine can actually answer JSON CONTAINMENT, i.e. the
+     * pathless `{ contains }` and `{ equals }` JSON filters that compile through
+     * {@link buildJsonContains}.
+     *
+     * A capability flag rather than a per-operand hook, because the answer turned
+     * out not to vary by operand. SQLite emulates containment as
+     * `EXISTS (SELECT 1 FROM json_each(col) WHERE value = $1)` while the param is
+     * bound as JSON TEXT, and `json_each.value` yields the DECODED SQL value, so
+     * the comparison is between two different encodings and never holds. Measured
+     * against a real in-process SQLite, every operand type returned zero rows:
+     *
+     *   stored              filter                PG        SQLite
+     *   ["gold"]            contains: 'gold'      match     none   ('gold' = '"gold"')
+     *   [1]                 contains: 1           match     none   (INTEGER 1 = TEXT '1')
+     *   {"a":1,"t":"gold"}  contains: { a: 1 }    match     none   (no structural walk)
+     *
+     * So the feature has never worked on that engine at all, and refusing it
+     * removes nothing that functioned. Fewer-rows-with-no-error is the exact
+     * degrade the capability contract exists to convert into a refusal.
+     *
+     * Repairing it rather than refusing it is possible and deliberately not done
+     * here: `json_each` exposes a `type` column ('text' / 'integer' / 'real' /
+     * 'true' / 'false' / 'null'), so a faithful scalar test is
+     * `type = $1 AND value IS $2`. That is a param-COUNT change on a path whose
+     * build and collect sides must stay in lockstep, which is a different change
+     * from this one. Until then the flag is honest and the error names the
+     * alternative that is exact today (`{ path: [...], equals }`, which compiles
+     * to `json_extract`).
+     */
+    readonly supportsJsonContains: boolean;
     /**
      * Whether this dialect/engine supports the PostgreSQL full-text `search`
      * filter (`to_tsvector(...) @@ to_tsquery(...)`). Optional: absent is treated
@@ -454,6 +530,28 @@ export interface Dialect {
     readonly supportsILike: boolean;
     /** Build a case-insensitive LIKE equivalent. */
     buildInsensitiveLike(column: string, paramRef: string): string;
+    /**
+     * Escape the LIKE metacharacters of this engine in a bound `contains` /
+     * `startsWith` / `endsWith` / `stringContains` operand. Optional: when a
+     * dialect omits it the shared {@link escapeLike} is used, which escapes the
+     * SQL-standard set (`\`, `%`, `_`) and pairs with the `ESCAPE '\'` clause the
+     * builders always emit.
+     *
+     * It exists because the standard set is not the whole set everywhere:
+     * T-SQL's `LIKE` also treats `[` as opening a character CLASS, so
+     * `{ contains: '[draft]' }` becomes "contains any one of d, r, a, f, t" on
+     * SQL Server, a silently over-broad predicate on an engine where every other
+     * dialect agrees the value is a literal. That is not injection (the operand
+     * is still bound), but it is a wrong answer, and the difference is a property
+     * of the ENGINE's pattern grammar, not of the SQL text, which is why it is a
+     * dialect hook rather than a branch in the where builder.
+     *
+     * Whatever a dialect returns MUST be escaped for the same `ESCAPE '\'`
+     * clause, i.e. a backslash prefix, and MUST be identical on the SQL-build and
+     * the cache-hit param-collect paths (both call this one hook, so they cannot
+     * drift).
+     */
+    escapeLikePattern?(value: string): string;
     /** JSON operator support level for this dialect. */
     readonly jsonPathSupport: 'native' | 'function' | 'limited';
     /** Build a JSON containment check. */
@@ -601,6 +699,31 @@ export interface Dialect {
      * param-push-ordering contract the override must honor.
      */
     buildRelationSubquery?(ctx: RelationSubqueryContext): string;
+    /**
+     * Bound a batched relation follow-up to at most N rows per correlation key,
+     * by wrapping the compiled child SELECT in a `ROW_NUMBER() OVER (PARTITION
+     * BY …)` filter. See {@link PartitionLimitInput} for why a trailing `LIMIT`
+     * cannot express this.
+     *
+     * OPTIONAL, and absent means "no pushdown": the batched loader then fetches
+     * every matching child and applies the per-relation `limit` client-side, the
+     * behaviour every engine had before this hook existed. That fallback is
+     * correct but unbounded in bytes over the wire (200 parents x ~505 children
+     * with `limit: 3` measured 101,000 rows fetched to keep 600, +52.9 MB peak
+     * heap against +0.5 MB for the join plan), which is why PostgreSQL
+     * implements it. Only PostgreSQL does in this release; the other engines keep
+     * the client-side slice, so their emitted SQL is byte-identical to before.
+     *
+     * The client-side slice is NOT removed when a dialect implements this: it
+     * stays as the belt-and-braces bound, and is a no-op once the engine has
+     * already limited each partition. It is also still the whole mechanism for
+     * any relation whose `orderBy` does not TOTALLY order the target table, on
+     * every engine including this one: a rewrite that reaches here has to return
+     * the same rows the join plan's per-parent `ORDER BY … LIMIT n` returns, and
+     * with ties present neither plan's choice is forced. See
+     * {@link PartitionLimitInput.orderBy}.
+     */
+    buildPartitionLimit?(input: PartitionLimitInput): string;
 }
 export interface DialectIntrospector {
     introspect(options: IntrospectOptions): Promise<SchemaMetadata>;

package/dist/dialect.js

@@ -20,6 +20,7 @@ export const postgresDialect = {
     nullJsonLiteral: 'NULL',
     aggSupportsInlineOrderBy: true,
     supportsVector: true,
+    supportsJsonContains: true,
     supportsFullTextSearch: true,
     supportsArrayColumns: true,
     supportsListenNotify: true,
@@ -258,6 +259,38 @@ export const postgresDialect = {
             params: [name, value],
         };
     },
+    buildPartitionLimit(input) {
+        // Two wrapper levels, and both are needed: `ROW_NUMBER()` is a window
+        // function, so it cannot appear in the same WHERE that filters on it.
+        // Aliases are deliberately not in the `t<n>` family the relation builder
+        // allocates, so a future caller that wraps a query carrying those aliases
+        // cannot shadow one.
+        const inner = this.quoteIdentifier('turbine_pl_src');
+        const outer = this.quoteIdentifier('turbine_pl_rank');
+        const rank = this.quoteIdentifier(input.rankColumn);
+        const order = (ref) => input.orderBy
+            .map((o) => `${ref}.${this.quoteIdentifier(o.column)} ${o.direction}${o.nulls ? ` NULLS ${o.nulls}` : ''}`)
+            .join(', ');
+        // The empty-list branches are defensive only: the loader never asks for
+        // this rewrite without a total order (see the note on
+        // `PartitionLimitInput.orderBy`). An unordered window numbers each
+        // partition arbitrarily, and so does the join plan's ORDER-BY-less
+        // per-parent `LIMIT`, but they are different plans over different row sets
+        // and were measured choosing differently, so that shape keeps the loader's
+        // client-side slice rather than arriving here.
+        const windowOrder = input.orderBy.length > 0 ? ` ORDER BY ${order(inner)}` : '';
+        // The OUTER ordering is not cosmetic: the loader buckets children in result
+        // order, so without re-applying it here the relation array would come back
+        // in whatever order the rank filter happened to emit. It agrees with the
+        // window's own ordering by construction, since both are this one list and
+        // that list admits no ties, so the outer sort cannot pick a different order
+        // among the ranked rows than the rank did.
+        const outerOrder = input.orderBy.length > 0 ? ` ORDER BY ${order(outer)}` : '';
+        return (`SELECT ${outer}.* FROM (SELECT ${inner}.*, ROW_NUMBER() OVER (PARTITION BY ` +
+            `${inner}.${this.quoteIdentifier(input.partitionColumn)}${windowOrder}) AS ${rank} ` +
+            `FROM (${input.innerSql}) AS ${inner}) AS ${outer} ` +
+            `WHERE ${outer}.${rank} <= ${input.limitPlaceholder}${outerOrder}`);
+    },
     async *openStream(connection, sql, params, batchSize, opts) {
         // Cursors require a single connection inside a transaction: BEGIN → DECLARE
         // … NO SCROLL CURSOR FOR → FETCH n (loop) → CLOSE → COMMIT; ROLLBACK on

package/dist/errors.d.ts

@@ -47,6 +47,40 @@ export declare class TurbineError extends Error {
  * with `{ errorMessages: 'verbose' }`.
  */
 export type ErrorMessageMode = 'safe' | 'verbose';
+/**
+ * Register a client's configured mode and report whether per-operation scoping
+ * is now required.
+ *
+ * The gate is DIVERGENCE, not "has a client been built": while every client in
+ * the process agrees (the overwhelmingly common case, including every
+ * single-client app), the module default is already the right answer for all of
+ * them and no scope has to be established, so the query path pays exactly
+ * nothing. The moment two clients disagree, every client starts scoping, which
+ * is why this is read per call rather than latched per client.
+ *
+ * @internal Used by TurbineClient; not part of the public surface.
+ */
+export declare function registerClientErrorMessageMode(mode: ErrorMessageMode): void;
+/**
+ * Whether any two clients in this process have registered different modes, so
+ * the module default can no longer speak for all of them.
+ *
+ * @internal
+ */
+export declare function errorMessageModesDiverged(): boolean;
+/**
+ * Run `fn` with `mode` in force for everything it does, awaits included.
+ *
+ * Establishing the scope around the call (rather than threading a mode
+ * parameter into every error constructor) is what makes this reachable at all:
+ * the mode-sensitive errors are built deep inside the query executor, the write
+ * builders and the nested-write engine, none of which are handed the client.
+ * The async context is captured when the operation's promise chain is created
+ * INSIDE this call, so every continuation of it resolves the same mode.
+ *
+ * @internal
+ */
+export declare function runWithErrorMessageMode<R>(mode: ErrorMessageMode, fn: () => R): R;
 /**
  * Set the global NotFoundError message mode. Called from the TurbineClient
  * constructor when `TurbineConfig.errorMessages` is provided.
@@ -70,7 +104,14 @@ export type ErrorMessageMode = 'safe' | 'verbose';
  * leak, not as a log-scrubbing boundary.
  */
 export declare function setErrorMessageMode(mode: ErrorMessageMode): void;
-/** Returns the current NotFoundError message mode. Exported for tests. */
+/**
+ * Returns the NotFoundError message mode in effect right now.
+ *
+ * Called inside an operation issued through a client whose mode differs from
+ * another client's in the same process, that is THAT client's mode; anywhere
+ * else it is the process default {@link setErrorMessageMode} last set, which is
+ * what it has always returned. Exported for tests.
+ */
 export declare function getErrorMessageMode(): ErrorMessageMode;
 /**
  * The marker left where a driver `detail` string was removed in 'safe' mode.
@@ -78,6 +119,17 @@ export declare function getErrorMessageMode(): ErrorMessageMode;
  * assertions can match on it without hardcoding the wording.
  */
 export declare const REDACTED_DETAIL = "[redacted by turbine errorMessages:\"safe\"]";
+/**
+ * Mark a driver error as carrying row values in its `message` (see
+ * {@link VALUE_BEARING_MESSAGE}). Called by the engine error augmenters for the
+ * exact driver codes whose message grammar embeds a value; every other code is
+ * left alone so nothing is withheld that did not need to be.
+ *
+ * Non-enumerable so the flag itself never shows up in a serialized error, and
+ * best-effort so a frozen or exotic driver error cannot turn a constraint
+ * violation into a TypeError.
+ */
+export declare function markValueBearingMessage<T>(err: T): T;
 /**
  * Render a user-supplied `where` / `connect` target for a "no row found" error
  * message, honoring the global {@link ErrorMessageMode}. In 'safe' mode (the
@@ -168,6 +220,27 @@ export declare class ConnectionError extends TurbineError {
         sqlstate?: string;
     });
 }
+/**
+ * The message for "this engine's connection string could not be parsed".
+ *
+ * The one rule it exists to enforce: NEVER echo the value. A DSN carries a
+ * password, and the trigger for this error is a MALFORMED DSN, which is exactly
+ * when someone pastes the failure into a bug report, a CI log, or an error
+ * tracker. No redaction written against the URL grammar can be trusted on a
+ * string that just failed to parse as a URL, so the only safe amount of it to
+ * include is none: not the password, not the host, not a prefix.
+ *
+ * This mirrors the Postgres path (`assertUsableConnectionString` in client.ts),
+ * which reached the same conclusion first and stated the same reason; the
+ * engines used to interpolate the raw string instead, so SECURITY.md's claim of
+ * redaction "in all CLI error output" was true for one engine out of four.
+ * Shared rather than copied so the three engines cannot drift back apart.
+ *
+ * @param engine  the human engine label ("MySQL", "SQL Server", "PowDB").
+ * @param example a well-formed connection string for that engine, with a
+ *   placeholder password. Never derived from the caller's value.
+ */
+export declare function malformedConnectionStringMessage(engine: string, example: string): string;
 /** Thrown when a relation reference is invalid */
 export declare class RelationError extends TurbineError {
     constructor(message: string);

package/dist/errors.js

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
 /**
  * turbine-orm, Error types
  *
@@ -77,6 +78,76 @@ export class TurbineError extends Error {
     }
 }
 let errorMessageMode = 'safe';
+/**
+ * The mode in force for the operation currently executing, when a client has
+ * established one. See {@link runWithErrorMessageMode}.
+ */
+const errorMessageModeScope = new AsyncLocalStorage();
+/** The first mode a TurbineClient registered, used to detect divergence. */
+let firstRegisteredClientMode;
+let clientModesDiverged = false;
+/**
+ * The mode that applies right now: the scope a client established for this
+ * operation, else the process-wide default.
+ *
+ * The default is the fallback rather than the authority, which is the whole
+ * point. `errorMessageMode` is a module-level `let` that every TurbineClient
+ * constructor overwrote, so in a process with a primary client and an analytics
+ * or replica client, or a test harness building one client per suite, the LAST
+ * client constructed decided the mode for ALL of them, order-dependently. A
+ * client asking for `'safe'` could silently be running in `'verbose'`, which is
+ * the direction that leaks. (The dual ESM+CJS build makes it worse: the two
+ * copies hold separate `let`s.)
+ *
+ * An error constructed outside any client, directly or via
+ * {@link setErrorMessageMode}, still formats by the default, unchanged.
+ */
+function currentErrorMessageMode() {
+    return errorMessageModeScope.getStore() ?? errorMessageMode;
+}
+/**
+ * Register a client's configured mode and report whether per-operation scoping
+ * is now required.
+ *
+ * The gate is DIVERGENCE, not "has a client been built": while every client in
+ * the process agrees (the overwhelmingly common case, including every
+ * single-client app), the module default is already the right answer for all of
+ * them and no scope has to be established, so the query path pays exactly
+ * nothing. The moment two clients disagree, every client starts scoping, which
+ * is why this is read per call rather than latched per client.
+ *
+ * @internal Used by TurbineClient; not part of the public surface.
+ */
+export function registerClientErrorMessageMode(mode) {
+    if (firstRegisteredClientMode === undefined)
+        firstRegisteredClientMode = mode;
+    else if (firstRegisteredClientMode !== mode)
+        clientModesDiverged = true;
+}
+/**
+ * Whether any two clients in this process have registered different modes, so
+ * the module default can no longer speak for all of them.
+ *
+ * @internal
+ */
+export function errorMessageModesDiverged() {
+    return clientModesDiverged;
+}
+/**
+ * Run `fn` with `mode` in force for everything it does, awaits included.
+ *
+ * Establishing the scope around the call (rather than threading a mode
+ * parameter into every error constructor) is what makes this reachable at all:
+ * the mode-sensitive errors are built deep inside the query executor, the write
+ * builders and the nested-write engine, none of which are handed the client.
+ * The async context is captured when the operation's promise chain is created
+ * INSIDE this call, so every continuation of it resolves the same mode.
+ *
+ * @internal
+ */
+export function runWithErrorMessageMode(mode, fn) {
+    return errorMessageModeScope.run(mode, fn);
+}
 /**
  * Set the global NotFoundError message mode. Called from the TurbineClient
  * constructor when `TurbineConfig.errorMessages` is provided.
@@ -102,9 +173,16 @@ let errorMessageMode = 'safe';
 export function setErrorMessageMode(mode) {
     errorMessageMode = mode;
 }
-/** Returns the current NotFoundError message mode. Exported for tests. */
+/**
+ * Returns the NotFoundError message mode in effect right now.
+ *
+ * Called inside an operation issued through a client whose mode differs from
+ * another client's in the same process, that is THAT client's mode; anywhere
+ * else it is the process default {@link setErrorMessageMode} last set, which is
+ * what it has always returned. Exported for tests.
+ */
 export function getErrorMessageMode() {
-    return errorMessageMode;
+    return currentErrorMessageMode();
 }
 /**
  * The marker left where a driver `detail` string was removed in 'safe' mode.
@@ -112,6 +190,69 @@ export function getErrorMessageMode() {
  * assertions can match on it without hardcoding the wording.
  */
 export const REDACTED_DETAIL = '[redacted by turbine errorMessages:"safe"]';
+/**
+ * Marks a driver error whose `message` (not only its `detail`) embeds row
+ * VALUES, so 'safe' mode has to withhold the message text too.
+ *
+ * Postgres splits this cleanly: `message` carries relation / constraint /
+ * column NAMES and `detail` carries the conflicting values, so redacting
+ * `detail` was enough. MySQL and SQL Server do not split it at all. mysql2's
+ * ER_DUP_ENTRY reads `Duplicate entry 'alice@example.com' for key
+ * 'users.email'` and SQL Server's 2627 ends `The duplicate key value is
+ * (alice@example.com).`, both on `message`, with no `detail` field anywhere.
+ * So `redactCauseForMode` took its "nothing value-bearing to remove" early
+ * return and handed back the driver error untouched, and the row value reached
+ * every log line, Sentry event and uncaught-rejection dump that renders the
+ * cause chain, in the mode whose entire job is to prevent exactly that.
+ *
+ * A flag rather than a code list, and set by the ENGINE that knows its own
+ * message grammar, for two reasons. It keeps Postgres byte-identical (pg never
+ * sets it, so its cause is returned exactly as before), and it puts "this
+ * engine's message embeds values" next to the code that reads that engine's
+ * messages instead of in a table here that would silently rot.
+ *
+ * `Symbol.for` so the ESM and CJS copies of this module agree on the key: a
+ * dual-package consumer can hand an error marked by one build to the other.
+ */
+const VALUE_BEARING_MESSAGE = Symbol.for('turbine.error.valueBearingMessage');
+/**
+ * Mark a driver error as carrying row values in its `message` (see
+ * {@link VALUE_BEARING_MESSAGE}). Called by the engine error augmenters for the
+ * exact driver codes whose message grammar embeds a value; every other code is
+ * left alone so nothing is withheld that did not need to be.
+ *
+ * Non-enumerable so the flag itself never shows up in a serialized error, and
+ * best-effort so a frozen or exotic driver error cannot turn a constraint
+ * violation into a TypeError.
+ */
+export function markValueBearingMessage(err) {
+    if (!err || typeof err !== 'object')
+        return err;
+    try {
+        Object.defineProperty(err, VALUE_BEARING_MESSAGE, {
+            value: true,
+            enumerable: false,
+            writable: true,
+            configurable: true,
+        });
+    }
+    catch {
+        /* a frozen driver error keeps its message; the Turbine message is still safe */
+    }
+    return err;
+}
+/**
+ * The replacement for a withheld driver message. The whole message goes, not a
+ * pattern-matched part of it: three engines with three grammars and no
+ * guarantee a future driver keeps either, so "withhold it" is the only rule
+ * that stays true. Nothing diagnostic is lost, the constraint/column/table
+ * names are already on the typed Turbine error as structured fields and in its
+ * own message, and `errorMessages: 'verbose'` returns the driver text in full.
+ */
+function redactedDriverMessage(code) {
+    const codePart = typeof code === 'string' && code.length > 0 ? ` (driver code ${code})` : '';
+    return `${REDACTED_DETAIL}${codePart}: this engine reports the conflicting row values in the message text, so errorMessages:"safe" withholds it. Use errorMessages:"verbose" to see it.`;
+}
 /**
  * Postgres puts the CONFLICTING ROW VALUES in the `detail` field of a
  * constraint error, and nowhere else: `Key (email)=(alice@example.com) already
@@ -148,17 +289,29 @@ export const REDACTED_DETAIL = '[redacted by turbine errorMessages:"safe"]';
  *
  * In 'verbose' mode the cause passes through untouched: that mode's documented
  * job is full-fidelity debugging.
+ *
+ * ENGINES WHOSE MESSAGE CARRIES THE VALUE. MySQL and SQL Server do not have a
+ * `detail` field at all and put the conflicting value in `message`, so the
+ * early return below used to hand the raw driver error straight back (see
+ * {@link markValueBearingMessage}). When the engine set that flag the clone
+ * also withholds `message`, `sqlMessage` (mysql2's copy, which is the field
+ * mysql2 formats `message` FROM, so leaving it would put the value straight
+ * back) and the message text embedded in the rendered `stack` string. The stack
+ * substitution is an exact replacement of the known message string, never a
+ * grammar guess, so the frames survive intact.
  */
 function redactCauseForMode(cause) {
-    if (errorMessageMode === 'verbose')
+    if (currentErrorMessageMode() === 'verbose')
         return cause;
     if (!cause || typeof cause !== 'object')
         return cause;
     const detail = cause.detail;
+    const hasDetail = typeof detail === 'string' && detail.length > 0;
+    const valueBearingMessage = cause[VALUE_BEARING_MESSAGE] === true;
     // Nothing value-bearing to remove: return the original object so the common
     // case (a non-pg cause, or a pg error without a detail) allocates nothing and
     // keeps object identity with what the driver threw.
-    if (typeof detail !== 'string' || detail.length === 0)
+    if (!hasDetail && !valueBearingMessage)
         return cause;
     try {
         const descriptors = Object.getOwnPropertyDescriptors(cause);
@@ -166,12 +319,36 @@ function redactCauseForMode(cause) {
         // non-writable `detail` would make the assignment throw in strict mode
         // (every module here is ESM, so it always would), and losing the cause is
         // worse than paying for one descriptor literal.
-        descriptors.detail = {
-            value: REDACTED_DETAIL,
-            writable: true,
-            enumerable: descriptors.detail?.enumerable ?? true,
-            configurable: true,
-        };
+        if (hasDetail) {
+            descriptors.detail = {
+                value: REDACTED_DETAIL,
+                writable: true,
+                enumerable: descriptors.detail?.enumerable ?? true,
+                configurable: true,
+            };
+        }
+        // The exact message strings to scrub out of the rendered stack, collected
+        // BEFORE the descriptors are overwritten.
+        const withheldTexts = [];
+        if (valueBearingMessage) {
+            const code = cause.code;
+            const replacement = redactedDriverMessage(code);
+            for (const key of ['message', 'sqlMessage']) {
+                const current = cause[key];
+                if (typeof current !== 'string' || current.length === 0)
+                    continue;
+                withheldTexts.push(current);
+                descriptors[key] = {
+                    value: replacement,
+                    writable: true,
+                    // `message` is non-enumerable on a native Error and mysql2's
+                    // `sqlMessage` is enumerable; keep whichever the driver chose so the
+                    // clone serializes with the same key set as the original.
+                    enumerable: descriptors[key]?.enumerable ?? false,
+                    configurable: true,
+                };
+            }
+        }
         // Brand check rather than `instanceof Error`, so a driver error thrown from
         // another realm (a worker, a bundled duplicate of pg) is still recognized.
         const isError = Object.prototype.toString.call(cause) === '[object Error]';
@@ -189,7 +366,14 @@ function redactCauseForMode(cause) {
         // own descriptor rather than having a lie written over it.
         const originalStack = cause.stack;
         if (typeof originalStack === 'string') {
-            descriptors.stack = { value: originalStack, writable: true, enumerable: false, configurable: true };
+            // V8 renders the stack as `<name>: <message>\n    at …`, so a withheld
+            // message is still sitting in it. Substitute the exact strings that were
+            // withheld (split/join, so a message repeated in a nested frame goes
+            // too); everything else, the frames included, is untouched.
+            let stackText = originalStack;
+            for (const text of withheldTexts)
+                stackText = stackText.split(text).join(REDACTED_DETAIL);
+            descriptors.stack = { value: stackText, writable: true, enumerable: false, configurable: true };
         }
         else if (descriptors.stack && typeof descriptors.stack.get === 'function') {
             // An own accessor bound to the ORIGINAL receiver would return undefined
@@ -218,7 +402,7 @@ function redactCauseForMode(cause) {
  * connect/update failures which historically embedded the raw values.
  */
 export function describeTargetForMessage(target) {
-    if (errorMessageMode === 'verbose') {
+    if (currentErrorMessageMode() === 'verbose') {
         try {
             return JSON.stringify(target);
         }
@@ -292,11 +476,11 @@ export class NotFoundError extends TurbineError {
         let message = input.message;
         if (!message) {
             if (operation && table) {
-                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, errorMessageMode)}` : '';
+                const wherePart = where !== undefined ? ` matching where: ${renderWhereForMessage(where, currentErrorMessageMode())}` : '';
                 message = `[turbine] ${operation} on "${table}" found no record${wherePart}`;
             }
             else if (table) {
-                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, errorMessageMode)}` : '';
+                const wherePart = where !== undefined ? ` matching where ${renderWhereForMessage(where, currentErrorMessageMode())}` : '';
                 message = `[turbine] No record found in "${table}"${wherePart}`;
             }
             else {
@@ -362,6 +546,31 @@ export class ConnectionError extends TurbineError {
         this.sqlstate = options?.sqlstate;
     }
 }
+/**
+ * The message for "this engine's connection string could not be parsed".
+ *
+ * The one rule it exists to enforce: NEVER echo the value. A DSN carries a
+ * password, and the trigger for this error is a MALFORMED DSN, which is exactly
+ * when someone pastes the failure into a bug report, a CI log, or an error
+ * tracker. No redaction written against the URL grammar can be trusted on a
+ * string that just failed to parse as a URL, so the only safe amount of it to
+ * include is none: not the password, not the host, not a prefix.
+ *
+ * This mirrors the Postgres path (`assertUsableConnectionString` in client.ts),
+ * which reached the same conclusion first and stated the same reason; the
+ * engines used to interpolate the raw string instead, so SECURITY.md's claim of
+ * redaction "in all CLI error output" was true for one engine out of four.
+ * Shared rather than copied so the three engines cannot drift back apart.
+ *
+ * @param engine  the human engine label ("MySQL", "SQL Server", "PowDB").
+ * @param example a well-formed connection string for that engine, with a
+ *   placeholder password. Never derived from the caller's value.
+ */
+export function malformedConnectionStringMessage(engine, example) {
+    return (`[turbine] The ${engine} connection string could not be parsed as a URL. Expected something like "${example}". ` +
+        '(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.');
+}
 /** Thrown when a relation reference is invalid */
 export class RelationError extends TurbineError {
     constructor(message) {
@@ -419,7 +628,7 @@ export class UniqueConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -449,7 +658,7 @@ export class ForeignKeyError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -478,7 +687,7 @@ export class NotNullViolationError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -572,7 +781,7 @@ export class CheckConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }
@@ -600,7 +809,7 @@ export class ExclusionConstraintError extends TurbineError {
             // values straight back into any log line that prints the error object).
             // The structured `.columns`/`.constraint`/`.column` fields survive in
             // both modes, they carry NAMES, never values.
-            const detail = errorMessageMode === 'verbose' ? detailFromCause(cause) : undefined;
+            const detail = currentErrorMessageMode() === 'verbose' ? detailFromCause(cause) : undefined;
             if (detail)
                 message += `: ${detail}`;
         }