turbine-orm 0.65.0 → 0.66.0

package/dist/mysql.js

@@ -64,7 +64,7 @@
  */
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
-import { ConnectionError, UnsupportedFeatureError } from './errors.js';
+import { ConnectionError, malformedConnectionStringMessage, markValueBearingMessage, UnsupportedFeatureError, } from './errors.js';
 import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { isDateType, snakeToCamel, } from './schema.js';
@@ -114,10 +114,58 @@ function toNamedBinding(values) {
 // ---------------------------------------------------------------------------
 // Result shaping + error translation
 // ---------------------------------------------------------------------------
+/**
+ * mysql2's `MYSQL_TYPE_TINY`. A result field with this type and a display width
+ * of 1 IS the `BOOLEAN` / `TINYINT(1)` column; see {@link MYSQL_BOOLEAN_TYPE}.
+ */
+const MYSQL_FIELD_TYPE_TINY = 1;
+/**
+ * Turn `TINYINT(1)` cells back into real booleans, in place.
+ *
+ * MySQL stores a boolean as 1/0 and mysql2 returns the integer. Turbine still
+ * generates `ok: boolean` for the column ({@link mysqlTypeToTs}), so
+ * `row.ok === true` was false, `JSON.stringify(row)` emitted `1`, and a value
+ * the ORM itself wrote as `true` came back as a number.
+ *
+ * Done from the RESULT FIELDS rather than from mysql2's `typeCast` option on
+ * purpose. `typeCast` lives in {@link MYSQL_DRIVER_FLAGS}, which only applies
+ * to pools TURBINE builds; an injected mysql2 pool (a supported, documented
+ * entry point) would keep returning numbers at the top level while the join
+ * strategy's `jsonWireRule` returned booleans, i.e. fixing it there would have
+ * created exactly the strategy-dependent split this is meant to close. The
+ * field metadata is on every result from every pool.
+ *
+ * An expression column is never touched: `ok + 0` comes back as
+ * MYSQL_TYPE_LONGLONG with a different width, and only an exact
+ * (TINY, width 1) field is coerced.
+ */
+function coerceBooleanColumns(rows, fields) {
+    if (!Array.isArray(fields) || rows.length === 0)
+        return;
+    const names = [];
+    for (const f of fields) {
+        if (!f || f.columnType !== MYSQL_FIELD_TYPE_TINY || f.columnLength !== 1)
+            continue;
+        if (typeof f.name !== 'string')
+            continue;
+        names.push(f.name);
+    }
+    if (names.length === 0)
+        return;
+    for (const row of rows) {
+        for (const name of names) {
+            const v = row[name];
+            if (v === 1 || v === 0)
+                row[name] = v === 1;
+        }
+    }
+}
 /** Shape a mysql2 `[result]` into a `pg.QueryResult`-like object. */
-function shapeResult(result) {
+function shapeResult(result, fields) {
     if (Array.isArray(result)) {
-        return { rows: result, rowCount: result.length };
+        const rows = result;
+        coerceBooleanColumns(rows, fields);
+        return { rows, rowCount: rows.length };
     }
     // Write statement → ResultSetHeader (no rows). Expose insertId/lastID for the
     // `reselect` strategy to re-fetch the auto-increment row.
@@ -154,6 +202,19 @@ function augmentMysqlError(err) {
                 const parts = key.split('.');
                 target.constraint = parts.length > 1 ? parts[parts.length - 1] : key;
             }
+            // THE conflicting row value is in that message, between the quotes after
+            // "Duplicate entry". MySQL has no `detail` field, so 'safe' mode had
+            // nothing to redact and returned this error verbatim as `.cause`, putting
+            // the value into every log line that renders the cause chain. Flag it so
+            // the message is withheld in 'safe' mode (see markValueBearingMessage);
+            // the constraint NAME survives on `target.constraint` and in the typed
+            // UniqueConstraintError's own message, so nothing diagnostic is lost.
+            //
+            // Deliberately only 1062: the other MySQL codes handled here report
+            // column/constraint NAMES only ("Column 'x' cannot be null", "Check
+            // constraint 'c' is violated", the FK constraint definition), so flagging
+            // them would withhold a message that never carried a value.
+            markValueBearingMessage(err);
             return err;
         }
         // ER_ROW_IS_REFERENCED_2 / ER_NO_REFERENCED_ROW_2 → foreign key violation
@@ -202,8 +263,8 @@ function normalizeQueryArgs(arg, values) {
 async function execOne(runner, sql, params) {
     const binding = toNamedBinding(params);
     try {
-        const [result] = binding ? await runner.execute(sql, binding) : await runner.query(sql);
-        return shapeResult(result);
+        const [result, fields] = binding ? await runner.execute(sql, binding) : await runner.query(sql);
+        return shapeResult(result, fields);
     }
     catch (err) {
         throw augmentMysqlError(err);
@@ -279,7 +340,11 @@ export function mysqlTypeToTs(dialectType, nullable, columnType) {
     const t = dialectType.toLowerCase();
     const full = (columnType ?? '').toLowerCase();
     let base;
-    if (t === 'tinyint' && full === 'tinyint(1)')
+    // `tinyint(1)` can arrive either way: as (DATA_TYPE, COLUMN_TYPE) from the
+    // introspector's first pass, or as a single dialect type, because that is the
+    // spelling the introspector RECORDS for a boolean column (see the note there)
+    // and the `typeToTypeScript` dialect hook passes only the one string.
+    if (t === MYSQL_BOOLEAN_TYPE || (t === 'tinyint' && full === MYSQL_BOOLEAN_TYPE))
         base = 'boolean';
     else if (/^(tinyint|smallint|mediumint|int|integer|bigint)$/.test(t))
         base = 'number';
@@ -299,6 +364,63 @@ export function mysqlTypeToTs(dialectType, nullable, columnType) {
         base = 'unknown';
     return nullable ? `${base} | null` : base;
 }
+/**
+ * The dialect-type spelling Turbine records for a MySQL boolean column.
+ *
+ * MySQL has no boolean type: `BOOLEAN` is an alias for `TINYINT(1)`, and
+ * `information_schema` reports DATA_TYPE `tinyint` for it, which is the same
+ * DATA_TYPE a genuine one-byte integer column has. The display width in
+ * COLUMN_TYPE is the ONLY thing that separates them, so the introspector keeps
+ * the full spelling for this one type rather than the bare DATA_TYPE. Anything
+ * reading a dialect type has to accept both spellings; the two places that
+ * matter are {@link mysqlTypeToTs} and {@link mysqlDialect.jsonWireRule}.
+ */
+const MYSQL_BOOLEAN_TYPE = 'tinyint(1)';
+/**
+ * Rewrite every boolean column's recorded dialect type to
+ * {@link MYSQL_BOOLEAN_TYPE}, returning a schema that is safe to key
+ * {@link mysqlDialect.jsonWireRule} on.
+ *
+ * WHY. Only the join strategy consults the recorded type, so a column whose
+ * type is spelled some other way reads as a boolean at the top level (the shim
+ * decides that from the RESULT FIELDS, which every pool has) and as 1/0 through
+ * a `with` join, which is the strategy-dependent split the boolean rule exists
+ * to close. Two schemas spell it differently and neither is wrong:
+ *
+ *  - a metadata file generated before Turbine started keeping the display width
+ *    records the bare DATA_TYPE `tinyint` (with `tsType: 'boolean'`, which is
+ *    what identifies it), so `turbine generate` is NOT required to get the fix;
+ *  - a code-first `defineSchema` column records the Postgres spelling
+ *    `boolean` / `bool`, which the DDL generator already emits as `TINYINT(1)`.
+ *
+ * A genuine one-byte integer column is never touched: it carries
+ * `tsType: 'number'`, and the `tsType` is the gate. Copy-on-write, because the
+ * argument is usually a shared exported constant and may also be handed to
+ * another engine's factory; an already-correct schema is returned unchanged and
+ * pays nothing.
+ */
+function normalizeBooleanDialectTypes(schema) {
+    const needsFix = (col) => {
+        if (!/^boolean\b/.test(col.tsType))
+            return false;
+        const recorded = (col.dialectType ?? col.pgType ?? '').toLowerCase();
+        return recorded === 'tinyint' || recorded === 'bool' || recorded === 'boolean';
+    };
+    let tables;
+    for (const [name, table] of Object.entries(schema.tables)) {
+        if (!table.columns.some(needsFix))
+            continue;
+        const columns = table.columns.map((col) => needsFix(col) ? { ...col, dialectType: MYSQL_BOOLEAN_TYPE, pgType: MYSQL_BOOLEAN_TYPE } : col);
+        if (!tables)
+            tables = { ...schema.tables };
+        tables[name] = {
+            ...table,
+            columns,
+            pgTypes: Object.fromEntries(columns.map((c) => [c.name, c.pgType])),
+        };
+    }
+    return tables ? { ...schema, tables } : schema;
+}
 /** Is a MySQL declared type a date/time type (so values coerce back to `Date`)? */
 function isMysqlDateType(dialectType) {
     const t = dialectType.toLowerCase();
@@ -466,6 +588,52 @@ export const mysqlDialect = {
         if (t === 'decimal' || t === 'numeric') {
             return { sql: (ref) => `CAST(${ref} AS CHAR)`, decode: (value) => value };
         }
+        // A boolean is 1/0 on the wire, and the driver shim turns that back into
+        // true/false on every direct read (see coerceBooleanColumns). JSON_OBJECT
+        // renders the same column as a JSON number and has no column metadata to
+        // consult, so without this the join strategy alone would keep returning
+        // 1/0: the same strategy-dependent type flip the json rule below exists to
+        // prevent. Carried as text because the decode half only runs on a string
+        // cell, and a plain CAST is enough here (unlike SQLite, MySQL enforces the
+        // column type, so the value is always an integer and `Number` reproduces
+        // the driver's own reading of anything that is not 0 or 1).
+        if (t === MYSQL_BOOLEAN_TYPE) {
+            return {
+                sql: (ref) => `CAST(${ref} AS CHAR)`,
+                decode: (value) => {
+                    if (value === '1')
+                        return true;
+                    if (value === '0')
+                        return false;
+                    if (typeof value !== 'string' || !/^-?\d+$/.test(value))
+                        return value;
+                    return Number(value);
+                },
+            };
+        }
+        // A `json` column gets NO rule, and that is the fix rather than the absence
+        // of one. It used to read differently depending on the relation strategy:
+        // the driver handed back text while JSON_OBJECT, which knows the column is
+        // JSON, embedded it as a real nested value, so parsing the row yielded an
+        // object. Under the default `'auto'` the strategy is decided per query by
+        // row counts and index coverage, so adding a `limit` to
+        // `findMany({ with: { org: true } })` flipped `org.meta` from a string to
+        // an object with no other change.
+        //
+        // A `CAST(… AS CHAR)` carrier closes that, but only for a pool Turbine
+        // built: the text half of it came from a `typeCast` override in
+        // MYSQL_DRIVER_FLAGS, and an injected mysql2 pool (a documented entry
+        // point) never sees those flags, so it read the column as an object at the
+        // top level and as a string through the join. That trades one split for
+        // another. So the agreement is built on what BOTH pool shapes already do:
+        // mysql2 parses a `json` column by default, JSON_OBJECT embeds it parsed,
+        // and with the `typeCast` override gone every read path lands on the same
+        // parsed value. It is also what `pg` returns for json/jsonb, so this is
+        // Postgres parity rather than a MySQL convention.
+        //
+        // Contrast SQLite and SQL Server, which return TEXT for the same schema:
+        // neither has a JSON column type, so the value there really is a string in
+        // a text column and there is nothing to parse it back from.
         // Binary columns are worse than lossy: JSON_OBJECT emits MySQL's internal
         // `base64:type15:…` marker string, so the caller got that text instead of
         // bytes. Carry hex and rebuild the buffer.
@@ -700,11 +868,14 @@ export async function introspectMysqlWith(exec, schema, options = {}) {
             }
         }
         const maxLen = c.CHARACTER_MAXIMUM_LENGTH != null ? num(c.CHARACTER_MAXIMUM_LENGTH) : undefined;
+        // `tinyint(1)` is the one type whose DATA_TYPE is not enough to identify it
+        // (see MYSQL_BOOLEAN_TYPE); everything else keeps the bare DATA_TYPE.
+        const recordedType = c.COLUMN_TYPE.toLowerCase() === MYSQL_BOOLEAN_TYPE ? MYSQL_BOOLEAN_TYPE : dataType;
         const col = {
             name: c.COLUMN_NAME,
             field: snakeToCamel(c.COLUMN_NAME),
-            dialectType: dataType,
-            pgType: dataType,
+            dialectType: recordedType,
+            pgType: recordedType,
             tsType: mysqlTypeToTs(dataType, nullable, c.COLUMN_TYPE),
             nullable,
             hasDefault: c.COLUMN_DEFAULT !== null || /auto_increment/i.test(c.EXTRA),
@@ -870,12 +1041,18 @@ const MYSQL_DRIVER_FLAGS = {
     // DATETIME/TIMESTAMP → JS Date interpreted as UTC (matches Postgres).
     dateStrings: false,
     timezone: 'Z',
-    // Force JSON columns to raw strings so the nested-relation parser
-    // (parseNestedRow) always takes its well-tested JSON.parse path, instead of
-    // mysql2's auto-parsed objects or a Buffer. Top-level JSON columns therefore
-    // come back as strings (consistent with the SQLite engine; parse them yourself).
-    // biome-ignore lint/suspicious/noExplicitAny: mysql2 typeCast field shape (has .type and .string()).
-    typeCast: (field, next) => (field.type === 'JSON' ? field.string() : next()),
+    //
+    // NOTE: deliberately NO `typeCast` JSON override here. There used to be one,
+    // pinning a `json` column to raw text so the nested-relation parser always
+    // took its JSON.parse path. It could only ever apply to pools TURBINE builds,
+    // and pool injection is a documented entry point, so it did not decide how a
+    // `json` column reads; it decided that the two pool shapes read it
+    // DIFFERENTLY (owned: string, injected: object). Every flag above is
+    // idempotent in that sense (a placeholder style, an integer policy, a time
+    // zone) and none of them changes a value's TYPE. Letting mysql2 parse a
+    // `json` column is what both pool shapes do by default, and it is also what
+    // `pg` does with json/jsonb, so the parsed value is the one answer that is
+    // reachable from every entry point. See `jsonWireRule` for the other half.
 };
 /** Parse a `mysql://user:pass@host:port/db` connection string into mysql2 config. */
 function parseMysqlConfig(connectionString) {
@@ -895,7 +1072,8 @@ function parseMysqlConfig(connectionString) {
         return config;
     }
     catch {
-        throw new ConnectionError(`[turbine] Invalid MySQL connection string: "${connectionString}"`);
+        // Never echo the value, see malformedConnectionStringMessage.
+        throw new ConnectionError(malformedConnectionStringMessage('MySQL', 'mysql://user:password@localhost:3306/app'));
     }
 }
 /**
@@ -951,8 +1129,11 @@ function isMysql2Pool(x) {
  *    `disconnect()` is a no-op, advanced config like SSL lives here).
  *
  * When Turbine builds the pool (string/config), it pins the correct mysql2 flags
- * (named placeholders, bignum, UTC dates, JSON-as-string), probes `SELECT VERSION()`
- * to reject MySQL < 8.0 / MariaDB, and `disconnect()` closes the pool it created.
+ * (named placeholders, bignum, UTC dates), probes `SELECT VERSION()` to reject
+ * MySQL < 8.0 / MariaDB, and `disconnect()` closes the pool it created. None of
+ * those flags changes a column's TYPE, so an injected pool reads every value
+ * the same way (see {@link MYSQL_DRIVER_FLAGS}); `namedPlaceholders: true` is
+ * the one an injected pool must set for itself.
  *
  * @example
  * ```ts
@@ -1007,7 +1188,11 @@ export async function turbineMysql(target, schema, options = {}) {
         pool,
         dialect: mysqlDialect,
         preparedStatements: false,
-    }, schema);
+    }, 
+    // The join strategy is the only read path that consults a recorded dialect
+    // type, so a schema that spells a boolean any other way would read 1/0
+    // there and `true`/`false` everywhere else.
+    normalizeBooleanDialectTypes(schema));
     if (owns) {
         // Turbine built this pool, so disconnect()/end() must close it. External
         // pools (injection) stay the caller's responsibility (disconnect() no-op),

package/dist/nested-write.js

@@ -12,7 +12,7 @@
  * `NestedWriteContext`.
  */
 import { CircularRelationError, describeTargetForMessage, NotFoundError, RelationError, UnsupportedFeatureError, ValidationError, } from './errors.js';
-import { resolveColumnName } from './query/utils.js';
+import { markInternalCombinator, resolveColumnName } from './query/utils.js';
 import { normalizeKeyColumns } from './schema.js';
 const MAX_DEPTH = 10;
 const CREATE_ONLY_OPS = new Set(['create', 'connect', 'connectOrCreate']);
@@ -310,8 +310,13 @@ function belongsToCorrelationWhere(ctx, rel, parentRow, parentTable) {
  */
 function scopeWhereToParent(target, correlation) {
     for (const key of Object.keys(correlation)) {
+        // Branded as Turbine's own: this `AND` has a FIXED arity of two, chosen
+        // here rather than reachable from a request body, so it must not cost the
+        // statement its server-side prepared name the way a caller-written
+        // combinator array does. Same reason the global-filter merge and the
+        // batched loader's correlation merge are branded.
         if (Object.hasOwn(target, key))
-            return { AND: [target, correlation] };
+            return markInternalCombinator({ AND: [target, correlation] });
     }
     return { ...target, ...correlation };
 }

package/dist/pipeline-submittable.js

@@ -18,7 +18,7 @@
  */
 import Result from 'pg/lib/result';
 import { prepareValue } from 'pg/lib/utils';
-import { wrapPgError } from './errors.js';
+import { PipelineError, wrapPgError } from './errors.js';
 // ---------------------------------------------------------------------------
 // Event names we intercept
 // ---------------------------------------------------------------------------
@@ -165,7 +165,8 @@ export async function runPipelined(client, queries, options = {}) {
                 return;
             }
             if (!transactional && pipelineError) {
-                // In non-transactional mode, attach partial results to the error
+                // In non-transactional mode, report every slot: what each query returned
+                // or the error it failed with.
                 const partialResults = [];
                 for (let i = 0; i < queries.length; i++) {
                     const qErr = queryErrors[i];
@@ -182,8 +183,21 @@ export async function runPipelined(client, queries, options = {}) {
                         }
                     }
                 }
-                pipelineError.results = partialResults;
-                reject(pipelineError);
+                // A REAL PipelineError, not the first driver error with a `results`
+                // property bolted onto it. The old shape happened to satisfy
+                // `err.results`, which is what the docs show callers reading, while
+                // leaving `err instanceof PipelineError` and `err.code ===
+                // 'TURBINE_E014'` permanently false: E014 was defined, documented, and
+                // never constructed. The driver error survives as `.cause` and as the
+                // first `error` slot, and `failedIndex` / `failedTag` (recorded on it by
+                // `onErrorMessage`) move onto the typed error's own fields.
+                const first = pipelineError;
+                reject(new PipelineError({
+                    results: partialResults,
+                    failedIndex: first.failedIndex,
+                    failedTag: first.failedTag,
+                    cause: pipelineError,
+                }));
                 return;
             }
             // All succeeded, transform results

package/dist/pipeline.js

@@ -18,7 +18,7 @@
  * Sequential fallback covers HTTP-based drivers (Neon HTTP, Vercel Postgres, Cloudflare
  * Hyperdrive), mock pools in tests, and any pool that doesn't expose pg internals.
  */
-import { wrapPgError } from './errors.js';
+import { PipelineError, wrapPgError } from './errors.js';
 import { runPipelined, supportsExtendedPipeline } from './pipeline-submittable.js';
 /**
  * Execute queries sequentially on an already-acquired connection.
@@ -30,10 +30,21 @@ import { runPipelined, supportsExtendedPipeline } from './pipeline-submittable.j
  */
 async function runSequential(client, queries, options = {}) {
     const { transactional = true } = options;
+    if (!transactional)
+        return runIndependent(client, queries);
     try {
-        if (transactional) {
+        // Transaction control is wrapped too. It used to be bare, so a connection
+        // that died between checkout and BEGIN (or at COMMIT) surfaced the raw
+        // driver error while every statement between them surfaced a typed
+        // TurbineError, and a caller branching on `err.code` saw neither
+        // `TURBINE_E004` nor a retryable flag for the one failure that is most
+        // worth retrying.
+        try {
             await client.query('BEGIN');
         }
+        catch (err) {
+            throw wrapPgError(err);
+        }
         const results = [];
         for (const q of queries) {
             let raw;
@@ -45,23 +56,78 @@ async function runSequential(client, queries, options = {}) {
             }
             results.push(q.transform(raw));
         }
-        if (transactional) {
+        try {
             await client.query('COMMIT');
         }
+        catch (err) {
+            throw wrapPgError(err);
+        }
         return results;
     }
     catch (err) {
-        if (transactional) {
-            try {
-                await client.query('ROLLBACK');
-            }
-            catch {
-                // Best-effort rollback
-            }
+        try {
+            await client.query('ROLLBACK');
+        }
+        catch {
+            // Best-effort rollback
         }
         throw err;
     }
 }
+/**
+ * Sequential fallback for `{ transactional: false }`: each query is
+ * INDEPENDENT, which is what that option promises and what the real pipeline
+ * path already did. A failing query records its slot and the batch keeps going
+ * (there is no transaction to poison), and if anything failed the whole batch
+ * rejects with a `PipelineError` carrying every slot.
+ *
+ * It used to `throw wrapPgError(err)` on the first failure instead. That both
+ * abandoned the remaining queries, contradicting the option's own docstring,
+ * and rejected with the raw driver error, so `err instanceof PipelineError` and
+ * `err.code === 'TURBINE_E014'` were permanently false on the one path that
+ * documents them, and `err.results` did not exist at all. The first failure is
+ * still reachable, as `.cause` and as the first `error` slot.
+ */
+async function runIndependent(client, queries) {
+    const slots = [];
+    let firstError;
+    let failedIndex;
+    let failedTag;
+    const fail = (index, error) => {
+        slots.push({ status: 'error', error });
+        if (firstError !== undefined)
+            return;
+        firstError = error;
+        failedIndex = index;
+        failedTag = queries[index]?.tag;
+    };
+    for (let i = 0; i < queries.length; i++) {
+        const q = queries[i];
+        let raw;
+        try {
+            raw = await client.query(q.sql, q.params);
+        }
+        catch (err) {
+            const wrapped = wrapPgError(err);
+            fail(i, wrapped instanceof Error ? wrapped : new Error(String(wrapped)));
+            continue;
+        }
+        // A transform throw is a slot failure too, not a batch abort: that is what
+        // the real pipeline path's `finalize` does with the same situation. It is
+        // deliberately NOT run through wrapPgError, since it never came from the
+        // driver.
+        try {
+            slots.push({ status: 'ok', value: q.transform(raw) });
+        }
+        catch (err) {
+            fail(i, err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    if (firstError === undefined) {
+        return slots.map((slot) => slot.value);
+    }
+    throw new PipelineError({ results: slots, failedIndex, failedTag, cause: firstError });
+}
 // ---------------------------------------------------------------------------
 // Pipeline executor (public)
 // ---------------------------------------------------------------------------

package/dist/powdb.d.ts

@@ -478,6 +478,29 @@ export declare const POWQL_KEYWORDS: ReadonlySet<string>;
  * errors when emitted bare, so quoting is strictly an improvement.
  */
 export declare function quotePowqlIdent(name: string): string;
+/**
+ * The DOTTED-position spelling of {@link quotePowqlIdent}: quote a name that
+ * falls outside the bare-identifier grammar, and only that.
+ *
+ * A dotted reference (`.col` in a filter, projection, `order`, `group`, or an
+ * `upsert on`) bypasses keyword lookup, so `.order` parses on every engine
+ * version and stays bare here, which is the ≤0.9 compatibility decision
+ * {@link quotePowqlIdent} documents and which this must not undo.
+ *
+ * What it does NOT excuse is interpolating the name RAW, which is what these
+ * sites used to do. Keyword-ness is a parsing question; a name outside
+ * `POWQL_BARE_IDENT` is a statement-integrity one, and that name is the only
+ * thing that can carry PowQL syntax into a statement whose values are all bound
+ * as `$N` params. Reaching it needs a hostile column name (an introspected
+ * database, a generator, a migration authored elsewhere) since names come from
+ * schema metadata, but "the names are trusted" is not the invariant the rest of
+ * this engine is written to. So: bare when the grammar allows it (byte-identical
+ * output for every ordinary and every keyword name), quoted when it does not,
+ * where the bare form was a parse error anyway. Verified against the engine that
+ * a quoted dotted reference parses everywhere the bare one does and yields the
+ * same result-column name.
+ */
+export declare function quotePowqlDotted(name: string): string;
 /**
  * Options for {@link powqlSchemaDDL}. Additive: with no options the DDL is
  * emitted unconditionally (pure-function callers / tests); pass `capabilities`

package/dist/powdb.js

@@ -55,7 +55,7 @@
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { TurbineClient, } from './client.js';
 import { postgresDialect } from './dialect.js';
-import { ConnectionError, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
+import { ConnectionError, malformedConnectionStringMessage, NotNullViolationError, ReadOnlyError, TimeoutError, UniqueConstraintError, UnsupportedFeatureError, ValidationError, } from './errors.js';
 import importOptionalPeer from './optional-peer-import.cjs';
 import { shouldWarnOnce, WARN_NS } from './query/warn-registry.js';
 import { normalizeKeyColumns } from './schema.js';
@@ -162,7 +162,8 @@ export function parsePowdbUrl(connectionString) {
         u = new URL(connectionString);
     }
     catch {
-        throw new ConnectionError(`[turbine] Invalid PowDB connection string: "${connectionString}"`);
+        // Never echo the value, see malformedConnectionStringMessage.
+        throw new ConnectionError(malformedConnectionStringMessage('PowDB', 'powdb://user:password@127.0.0.1:5433/app'));
     }
     if (u.protocol !== 'powdb:') {
         throw new ConnectionError(`[turbine] PowDB connection string must use the powdb:// scheme (got "${u.protocol}//…").`);
@@ -585,6 +586,36 @@ export function quotePowqlIdent(name) {
     }
     return POWQL_KEYWORDS.has(name) || !POWQL_BARE_IDENT.test(name) ? `\`${name}\`` : name;
 }
+/**
+ * The DOTTED-position spelling of {@link quotePowqlIdent}: quote a name that
+ * falls outside the bare-identifier grammar, and only that.
+ *
+ * A dotted reference (`.col` in a filter, projection, `order`, `group`, or an
+ * `upsert on`) bypasses keyword lookup, so `.order` parses on every engine
+ * version and stays bare here, which is the ≤0.9 compatibility decision
+ * {@link quotePowqlIdent} documents and which this must not undo.
+ *
+ * What it does NOT excuse is interpolating the name RAW, which is what these
+ * sites used to do. Keyword-ness is a parsing question; a name outside
+ * `POWQL_BARE_IDENT` is a statement-integrity one, and that name is the only
+ * thing that can carry PowQL syntax into a statement whose values are all bound
+ * as `$N` params. Reaching it needs a hostile column name (an introspected
+ * database, a generator, a migration authored elsewhere) since names come from
+ * schema metadata, but "the names are trusted" is not the invariant the rest of
+ * this engine is written to. So: bare when the grammar allows it (byte-identical
+ * output for every ordinary and every keyword name), quoted when it does not,
+ * where the bare form was a parse error anyway. Verified against the engine that
+ * a quoted dotted reference parses everywhere the bare one does and yields the
+ * same result-column name.
+ */
+export function quotePowqlDotted(name) {
+    if (POWQL_BARE_IDENT.test(name))
+        return name;
+    if (name.includes('`')) {
+        throw new ValidationError(`[turbine] Identifier "${name}" contains a backtick, which PowQL cannot represent.`);
+    }
+    return `\`${name}\``;
+}
 /**
  * Derive the entity links Turbine would declare from a schema's relations. One
  * link per single-column hasMany / hasOne / belongsTo relation, owned by the