turbine-orm 0.49.0 → 0.50.0

package/dist/query/where.d.ts

@@ -35,6 +35,14 @@ export interface BuilderCtx {
     readonly scopedHostCache: Map<string, WhereHost>;
     readonly columnPgTypeMap: Map<string, string>;
     readonly columnArrayTypeMap: Map<string, string>;
+    /**
+     * The client's `utcTimestamps` setting, when the owning QueryInterface
+     * supplies it. Optional so an older ctx literal (and every test that builds
+     * one by hand) keeps the default. `false` opts out of BOTH the UTC read
+     * parsing and the symmetric UTC bind rewriting for zone-less `date` /
+     * `timestamp` columns (see `coerceWriteValue` in writes.ts).
+     */
+    readonly utcTimestamps?: boolean;
     readonly crossSchemaTypeColumns: Set<string>;
     /**
      * The active query's `skipGlobalFilters` opt-out. A live getter/setter over
@@ -62,7 +70,13 @@ export interface BuilderCtx {
     readonly camelDateFieldCache: Map<string, Set<string>>;
     limitOneClause(): string;
     buildPagination(limitPh: string | undefined, offsetPh: string | undefined, hasOrderBy: boolean): string;
-    paginationRef(value: unknown, params: unknown[]): string;
+    paginationRef(value: unknown, params: unknown[], arg?: string): string;
+    /**
+     * Coerce + validate a LIMIT/OFFSET argument (non-negative safe integer).
+     * The cache-hit param-collect paths call it directly, so a warmed template
+     * can never bind an unvalidated NaN (which Postgres reads as "no limit").
+     */
+    paginationValue(value: unknown, arg?: string): number;
 }
 /**
  * Column-reference resolution context threaded into
@@ -76,6 +90,13 @@ interface ColumnRefContext {
     meta: TableMetadata;
     table: string;
     prefix: string;
+    /**
+     * The operator's own RAW (unquoted) column name. The `column` argument the
+     * operator builders receive is already quoted on the build side and raw on
+     * the collect side, so the temporal bind rewrite resolves the column's type
+     * from here instead — the one value both sides pass identically.
+     */
+    rawColumn: string;
 }
 /**
  * A table-scoped WHERE compilation context for a sub-where that is NOT the
@@ -310,6 +331,22 @@ export declare function buildSubWhereForRelation(qi: BuilderCtx, targetTable: st
  * (relation targets, not just `qi.table`).
  */
 export declare function pgTypeForColumn(_qi: BuilderCtx, meta: TableMetadata, column: string): string;
+/**
+ * Rewrite a WHERE operand bound against `column` the same way the write path
+ * rewrites a `data` value ({@link coerceTemporalValue}): a JS `Date` on a
+ * `time` / `timetz` column becomes a time-of-day literal (Postgres otherwise
+ * answers `22007 invalid input syntax for type time` for the ISO timestamp the
+ * driver would send), and on a zone-less `date` / `timestamp` column it becomes
+ * the UTC-component literal, so a predicate matches the value a write of the
+ * same `Date` stored.
+ *
+ * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * SQL-template cache is unaffected, and it is applied on the cache-hit
+ * param-collect path as well as the build path.
+ *
+ * `timestamptz` and every non-temporal column are returned by identity.
+ */
+export declare function coerceWhereOperand(qi: BuilderCtx, meta: TableMetadata, column: string, value: unknown): unknown;
 /**
  * The Postgres enum type name for a column, when the schema knows one.
  *

package/dist/query/where.js

@@ -13,7 +13,7 @@
 import { UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { camelToSnake, normalizeKeyColumns } from '../schema.js';
 import { assertBindableEqualsOperand, findArrayUniqueKey, findJsonUniqueKey, isArrayFilter, isColumnRef, isJsonFilter, isUnmatchedPlainObject, isWhereOperator, JSON_RANGE_OPERATORS, VECTOR_DISTANCE_COMPARATORS, VECTOR_METRIC_OPERATORS, validateTextSearchConfig, } from './filters.js';
-import { escapeLike, OPERATOR_KEYS, ownLookup } from './utils.js';
+import { coerceTemporalValue, escapeLike, OPERATOR_KEYS, ownLookup } from './utils.js';
 import { classifyScalarForSql, fingerprintScalarToken, walkWhere, } from './where-compile.js';
 /**
  * Produce a value-invariant fingerprint of a where clause.
@@ -158,6 +158,7 @@ export function collectScalarParams(qi, key, value, params) {
                 meta: qi.tableMeta,
                 table: qi.table,
                 prefix: '',
+                rawColumn,
             });
             return;
         default:
@@ -165,7 +166,7 @@ export function collectScalarParams(qi, key, value, params) {
             // the build path, so a cache hit can never silently bind a
             // misspelled-operator object.
             assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
-            params.push(value);
+            params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             return;
     }
 }
@@ -228,24 +229,26 @@ export function collectOperatorParams(qi, column, op, params, refCtx) {
             resolveColumnRef(qi, v, refCtx, op.mode);
         return true;
     };
+    // Mirrors buildOperatorClauses' temporal bind rewrite exactly.
+    const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
     if (op.equals !== undefined && op.equals !== null && !skipRef(op.equals)) {
         assertBindableEqualsOperand(op.equals, `"${column}"`);
-        params.push(op.equals);
+        params.push(cv(op.equals));
     }
     if (op.gt !== undefined && !skipRef(op.gt))
-        params.push(op.gt);
+        params.push(cv(op.gt));
     if (op.gte !== undefined && !skipRef(op.gte))
-        params.push(op.gte);
+        params.push(cv(op.gte));
     if (op.lt !== undefined && !skipRef(op.lt))
-        params.push(op.lt);
+        params.push(cv(op.lt));
     if (op.lte !== undefined && !skipRef(op.lte))
-        params.push(op.lte);
+        params.push(cv(op.lte));
     if (op.not !== undefined && op.not !== null && !skipRef(op.not))
-        params.push(op.not);
+        params.push(cv(op.not));
     if (op.in !== undefined)
-        params.push(qi.inParam(op.in));
+        params.push(qi.inParam(cv(op.in)));
     if (op.notIn !== undefined)
-        params.push(qi.inParam(op.notIn));
+        params.push(qi.inParam(cv(op.notIn)));
     if (op.contains !== undefined)
         params.push(`%${escapeLike(op.contains)}%`);
     if (op.startsWith !== undefined)
@@ -555,6 +558,7 @@ export function buildScalarClause(qi, key, value, params, andClauses) {
                 meta: qi.tableMeta,
                 table: qi.table,
                 prefix: '',
+                rawColumn,
             }));
             return;
         default:
@@ -562,7 +566,7 @@ export function buildScalarClause(qi, key, value, params, andClauses) {
             // is almost always a misspelled operator (`startWith` for `startsWith`);
             // the guard also runs on the cache-hit param-collect path.
             assertBindableEqualityValue(qi, rawColumn, value, getColumnPgType(qi, rawColumn), qi.table);
-            params.push(value);
+            params.push(coerceWhereOperand(qi, qi.tableMeta, rawColumn, value));
             andClauses.push(`${column} = ${qi.p(params.length)}`);
             return;
     }
@@ -704,11 +708,12 @@ export function buildScopedScalarClause(qi, scope, field, value, params, clauses
             meta,
             table: scope.table,
             prefix: scope.qualifier,
+            rawColumn: col,
         }));
         return;
     }
     assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
-    params.push(value);
+    params.push(coerceWhereOperand(qi, meta, col, value));
     clauses.push(`${qCol} = ${qi.p(params.length)}`);
 }
 /**
@@ -760,11 +765,11 @@ export function collectScopedScalarParams(qi, scope, field, value, params) {
         }
     }
     if (isWhereOperator(value)) {
-        collectOperatorParams(qi, col, value, params, { meta, table: scope.table, prefix: '' });
+        collectOperatorParams(qi, col, value, params, { meta, table: scope.table, prefix: '', rawColumn: col });
         return;
     }
     assertBindableEqualityValue(qi, col, value, pgTypeForColumn(qi, meta, col), scope.table);
-    params.push(value);
+    params.push(coerceWhereOperand(qi, meta, col, value));
 }
 /**
  * Value-invariant fingerprint of a scoped sub-where. Same canonical
@@ -944,6 +949,30 @@ export function buildSubWhereForRelation(qi, targetTable, subWhere, params) {
 export function pgTypeForColumn(_qi, meta, column) {
     return meta.dialectTypes?.[column] ?? meta.pgTypes?.[column] ?? 'text';
 }
+/**
+ * Rewrite a WHERE operand bound against `column` the same way the write path
+ * rewrites a `data` value ({@link coerceTemporalValue}): a JS `Date` on a
+ * `time` / `timetz` column becomes a time-of-day literal (Postgres otherwise
+ * answers `22007 invalid input syntax for type time` for the ISO timestamp the
+ * driver would send), and on a zone-less `date` / `timestamp` column it becomes
+ * the UTC-component literal, so a predicate matches the value a write of the
+ * same `Date` stored.
+ *
+ * This is a VALUE transform only — it never changes the emitted SQL — so the
+ * SQL-template cache is unaffected, and it is applied on the cache-hit
+ * param-collect path as well as the build path.
+ *
+ * `timestamptz` and every non-temporal column are returned by identity.
+ */
+export function coerceWhereOperand(qi, meta, column, value) {
+    if (!(value instanceof Date) && !Array.isArray(value))
+        return value;
+    return coerceTemporalValue(pgTypeForColumn(qi, meta, column), value, 
+    // Same PostgreSQL + `utcTimestamps` gate as the write path (see
+    // `utcDateTimeWrites` in writes.ts): only the read/write-symmetric engine
+    // gets the zone-less rewrite. Time-of-day always rewrites.
+    qi.dialect.name === 'postgresql' && qi.utcTimestamps !== false);
+}
 /**
  * The Postgres enum type name for a column, when the schema knows one.
  *
@@ -1081,6 +1110,9 @@ export function columnRefSql(qi, ref, ctx, mode) {
  */
 export function buildOperatorClauses(qi, column, op, params, refCtx) {
     const clauses = [];
+    // Temporal bind rewrite, identical to `collectOperatorParams`. Value-only, so
+    // the emitted SQL (and therefore the template cache) is untouched.
+    const cv = (v) => (refCtx ? coerceWhereOperand(qi, refCtx.meta, refCtx.rawColumn, v) : v);
     if (op.equals !== undefined) {
         if (op.equals === null) {
             clauses.push(`${column} IS NULL`);
@@ -1090,7 +1122,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
         }
         else {
             assertBindableEqualsOperand(op.equals, column);
-            params.push(op.equals);
+            params.push(cv(op.equals));
             clauses.push(`${column} = ${qi.p(params.length)}`);
         }
     }
@@ -1099,7 +1131,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} > ${columnRefSql(qi, op.gt, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.gt);
+            params.push(cv(op.gt));
             clauses.push(`${column} > ${qi.p(params.length)}`);
         }
     }
@@ -1108,7 +1140,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} >= ${columnRefSql(qi, op.gte, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.gte);
+            params.push(cv(op.gte));
             clauses.push(`${column} >= ${qi.p(params.length)}`);
         }
     }
@@ -1117,7 +1149,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} < ${columnRefSql(qi, op.lt, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.lt);
+            params.push(cv(op.lt));
             clauses.push(`${column} < ${qi.p(params.length)}`);
         }
     }
@@ -1126,7 +1158,7 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} <= ${columnRefSql(qi, op.lte, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.lte);
+            params.push(cv(op.lte));
             clauses.push(`${column} <= ${qi.p(params.length)}`);
         }
     }
@@ -1138,16 +1170,16 @@ export function buildOperatorClauses(qi, column, op, params, refCtx) {
             clauses.push(`${column} != ${columnRefSql(qi, op.not, refCtx, op.mode)}`);
         }
         else {
-            params.push(op.not);
+            params.push(cv(op.not));
             clauses.push(`${column} != ${qi.p(params.length)}`);
         }
     }
     if (op.in !== undefined) {
-        params.push(qi.inParam(op.in));
+        params.push(qi.inParam(cv(op.in)));
         clauses.push(qi.inClause(column, qi.p(params.length), false));
     }
     if (op.notIn !== undefined) {
-        params.push(qi.inParam(op.notIn));
+        params.push(qi.inParam(cv(op.notIn)));
         clauses.push(qi.inClause(column, qi.p(params.length), true));
     }
     const buildLikeClause = (paramRef) => op.mode === 'insensitive' ? qi.dialect.buildInsensitiveLike(column, paramRef) : `${column} LIKE ${paramRef}`;
@@ -1207,7 +1239,10 @@ export function vectorOperator(qi, field, rawColumn, metric) {
         throw new ValidationError(`[turbine] Column "${field}" on table "${qi.table}" is not a vector column ` +
             `(actual type: ${colType}); cannot apply a vector distance operation.`);
     }
-    const op = VECTOR_METRIC_OPERATORS[metric];
+    // ownLookup, not a bare index: an inherited Object.prototype member
+    // ("constructor", "toString", …) would otherwise resolve to a truthy builtin
+    // and be spliced into the ORDER BY / WHERE clause as its source text.
+    const op = ownLookup(VECTOR_METRIC_OPERATORS, metric);
     if (!op) {
         throw new ValidationError(`[turbine] Unknown vector metric "${metric}" for column "${field}". ` +
             `Valid metrics: ${Object.keys(VECTOR_METRIC_OPERATORS).join(', ')}.`);

package/dist/query/writes.d.ts

@@ -15,6 +15,29 @@ import type { TableMetadata } from '../schema.js';
 import type { DeferredQuery } from './deferred.js';
 import type { CreateArgs, CreateManyArgs, DeleteArgs, DeleteManyArgs, UpdateArgs, UpdateManyArgs, UpsertArgs } from './types.js';
 import type { BuilderCtx } from './where.js';
+/**
+ * Normalize one `data` value before it is bound as a write param.
+ *
+ * Two value shapes need rewriting, both a JS `Date` on a temporal column:
+ *
+ * 1. A time-of-day column (`time` / `timetz`) — the driver serializes a `Date`
+ *    as a full ISO timestamp with the process offset and Postgres answers
+ *    `22007 invalid input syntax for type time`. Rewritten on every engine.
+ * 2. A zone-less `date` / `timestamp` column on PostgreSQL — the driver's
+ *    local-offset serialization stores the PROCESS's calendar fields, so in a
+ *    non-UTC process the stored value is wrong and (because the read path
+ *    interprets an offset-less value as UTC) does not round-trip. Rewritten to
+ *    the UTC components, mirroring `parseDbDate`. See `toLocalDateTimeLiteral`
+ *    in query/utils.ts.
+ *
+ * `timestamptz` is deliberately untouched: it stores a real instant and the
+ * driver's local-offset string is already correct for it.
+ *
+ * Every other value, including a string that is already a valid literal, is
+ * returned by identity, so this is a byte-for-byte no-op for every non-temporal
+ * column.
+ */
+export declare function coerceWriteValue(qi: BuilderCtx, key: string, value: unknown): unknown;
 /**
  * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
  * by a write's `where` clause. Used by the `'reselect'` result strategy to
@@ -120,6 +143,24 @@ export declare function assertNoGeneratedColumns(qi: BuilderCtx, data: Record<st
  * clause numbering continues correctly afterward.
  */
 export declare function buildSetClause(qi: BuilderCtx, key: string, value: unknown, params: unknown[]): string;
+/**
+ * Reject a `data` value that reached {@link buildSetClause}'s plain-value
+ * fallthrough as a plain object with exactly ONE key that is not a known
+ * atomic operator. On a scalar column that shape can only be a misspelled
+ * operator (`{ incremnt: 1 }`, `{ bogus: 'x' }`); binding it plainly writes the
+ * JSON text `{"bogus":"x"}` into the column and silently corrupts it.
+ *
+ * Deliberately narrow. Skipped for:
+ *  - json / jsonb columns, which legitimately take arbitrary objects;
+ *  - class instances (Buffer for bytea, Decimal wrappers, …), arrays and Dates,
+ *    which {@link isUnmatchedPlainObject} already excludes;
+ *  - multi-key objects, which are never operator-shaped (a real operator object
+ *    has exactly one key) and are far more likely a deliberate payload.
+ *
+ * Shared by the SQL-build path and the cache-hit param-collect path, so a
+ * warmed template can never skip the check.
+ */
+export declare function assertBindableSetValue(qi: BuilderCtx, key: string, value: unknown): void;
 /**
  * Fingerprint SET clauses for update/updateMany.
  * Captures key names + operator types (set/increment/etc) but not values.
@@ -128,4 +169,4 @@ export declare function fingerprintSet(_qi: BuilderCtx, data: Record<string, unk
 /**
  * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
  */
-export declare function collectSetParams(_qi: BuilderCtx, data: Record<string, unknown>, params: unknown[]): void;
+export declare function collectSetParams(qi: BuilderCtx, data: Record<string, unknown>, params: unknown[]): void;

package/dist/query/writes.js

@@ -13,8 +13,58 @@
 import { NotFoundError, OptimisticLockError, ValidationError } from '../errors.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
-import { UPDATE_OPERATOR_KEYS } from './filters.js';
+import { isUnmatchedPlainObject, UPDATE_OPERATOR_KEYS } from './filters.js';
+import { coerceTemporalValue, ownLookup } from './utils.js';
 import * as whereMod from './where.js';
+/**
+ * Normalize one `data` value before it is bound as a write param.
+ *
+ * Two value shapes need rewriting, both a JS `Date` on a temporal column:
+ *
+ * 1. A time-of-day column (`time` / `timetz`) — the driver serializes a `Date`
+ *    as a full ISO timestamp with the process offset and Postgres answers
+ *    `22007 invalid input syntax for type time`. Rewritten on every engine.
+ * 2. A zone-less `date` / `timestamp` column on PostgreSQL — the driver's
+ *    local-offset serialization stores the PROCESS's calendar fields, so in a
+ *    non-UTC process the stored value is wrong and (because the read path
+ *    interprets an offset-less value as UTC) does not round-trip. Rewritten to
+ *    the UTC components, mirroring `parseDbDate`. See `toLocalDateTimeLiteral`
+ *    in query/utils.ts.
+ *
+ * `timestamptz` is deliberately untouched: it stores a real instant and the
+ * driver's local-offset string is already correct for it.
+ *
+ * Every other value, including a string that is already a valid literal, is
+ * returned by identity, so this is a byte-for-byte no-op for every non-temporal
+ * column.
+ */
+export function coerceWriteValue(qi, key, value) {
+    // Cheap shape check first: the common path costs one check and no lookup.
+    if (!(value instanceof Date) && !Array.isArray(value))
+        return value;
+    // Non-throwing column resolution: this runs on the cache-HIT param-collect
+    // path too, where an unknown key must not turn into a different error than
+    // the build path already raises.
+    const column = ownLookup(qi.tableMeta.columnMap, key);
+    if (!column)
+        return value;
+    // Metadata generated by an older Turbine still carries per-column types
+    // (`pgTypes` has always been part of TableMetadata), and a column missing
+    // from the map resolves to undefined → no coercion, today's behavior.
+    return coerceTemporalValue(qi.columnPgTypeMap.get(column), value, utcDateTimeWrites(qi));
+}
+/**
+ * Whether the zone-less `date` / `timestamp` UTC rewrite applies.
+ *
+ * PostgreSQL only: MySQL's `TIMESTAMP`/`DATETIME` and SQL Server's
+ * `datetime2` are converted or bound by their own drivers, and MySQL in
+ * particular reads a zone-less literal in the SESSION time zone, so a UTC
+ * literal would be misread there. `utcTimestamps: false` opts out — it is the
+ * same switch that turns off the UTC READ parsing, so the two stay symmetric.
+ */
+function utcDateTimeWrites(qi) {
+    return qi.dialect.name === 'postgresql' && qi.utcTimestamps !== false;
+}
 /**
  * Build a `SELECT * ... WHERE <predicate>` that re-fetches the row(s) matched
  * by a write's `where` clause. Used by the `'reselect'` result strategy to
@@ -32,7 +82,7 @@ export function buildCreate(qi, args) {
     assertNoGeneratedColumns(qi, args.data, 'create');
     const entries = Object.entries(args.data).filter(([, v]) => v !== undefined);
     const columns = entries.map(([k]) => qi.toSqlColumn(k));
-    const params = entries.map(([, v]) => v);
+    const params = entries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
     const placeholders = entries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     const sql = qi.dialect.buildInsertStatement({
@@ -78,7 +128,9 @@ export function makeCreateReselect(qi, insertSql, insertParams, data) {
         let idx = 1;
         for (const pk of qi.tableMeta.primaryKey) {
             const field = qi.tableMeta.reverseColumnMap[pk] ?? snakeToCamel(pk);
-            selParams.push(data[field] ?? data[pk] ?? insertId);
+            // Same rewrite the INSERT's own params got: a temporal PK re-fetched with
+            // a raw Date would not match the literal that was just written.
+            selParams.push(coerceWriteValue(qi, field, data[field] ?? data[pk] ?? insertId));
             conds.push(`${qi.q(pk)} = ${qi.p(idx++)}`);
         }
         const where = conds.length > 0 ? ` WHERE ${conds.join(' AND ')}` : '';
@@ -103,7 +155,7 @@ export function buildCreateMany(qi, args) {
     const columns = keys.map((k) => qi.toColumn(k));
     const rowValues = args.data.map((row) => {
         const record = row;
-        return keys.map((key) => record[key]);
+        return keys.map((key) => coerceWriteValue(qi, key, record[key]));
     });
     // Use actual Postgres types for array casts in the default PostgreSQL dialect.
     // Enum columns cast to `"EnumName"[]` — the generic text[] fallback would
@@ -303,7 +355,7 @@ export function buildUpsert(qi, args) {
     // Build the INSERT part from create data
     const createEntries = Object.entries(args.create).filter(([, v]) => v !== undefined);
     const columns = createEntries.map(([k]) => qi.toSqlColumn(k));
-    const createParams = createEntries.map(([, v]) => v);
+    const createParams = createEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
     // Enum columns get an explicit `::"EnumName"` cast (see enumTypeForColumn).
     const placeholders = createEntries.map(([k], i) => `${qi.p(i + 1)}${whereMod.enumCastSuffix(qi, qi.toColumn(k))}`);
     // The conflict target comes from `where` keys — must be unique/PK columns
@@ -317,7 +369,7 @@ export function buildUpsert(qi, args) {
         paramIdx++;
         return clause;
     });
-    const updateParams = updateEntries.map(([, v]) => v);
+    const updateParams = updateEntries.map(([k, v]) => coerceWriteValue(qi, k, v));
     const params = [...createParams, ...updateParams];
     // Global filter → restrict the conflict-UPDATE (soft-delete / tenancy) so an
     // upsert never resurrects a soft-deleted row or writes across tenants. Only
@@ -557,7 +609,7 @@ export function buildSetClause(qi, key, value, params) {
             const op = keys[0];
             const opValue = v[op];
             if (op === 'set') {
-                params.push(opValue);
+                params.push(coerceWriteValue(qi, key, opValue));
                 return `${col} = ${qi.p(params.length)}${cast}`;
             }
             // Arithmetic operators: must be finite numbers
@@ -582,12 +634,44 @@ export function buildSetClause(qi, key, value, params) {
             }
         }
         // Fall through: multi-key objects or non-operator single-key objects
-        // are treated as plain values (e.g., JSONB column payloads).
+        // are treated as plain values (e.g., JSONB column payloads), unless the
+        // shape can only be a misspelled atomic operator (see below).
+        assertBindableSetValue(qi, key, value);
     }
     // Plain value (including null, Date, Buffer, arrays, JSON objects)
-    params.push(value);
+    params.push(coerceWriteValue(qi, key, value));
     return `${col} = ${qi.p(params.length)}${cast}`;
 }
+/**
+ * Reject a `data` value that reached {@link buildSetClause}'s plain-value
+ * fallthrough as a plain object with exactly ONE key that is not a known
+ * atomic operator. On a scalar column that shape can only be a misspelled
+ * operator (`{ incremnt: 1 }`, `{ bogus: 'x' }`); binding it plainly writes the
+ * JSON text `{"bogus":"x"}` into the column and silently corrupts it.
+ *
+ * Deliberately narrow. Skipped for:
+ *  - json / jsonb columns, which legitimately take arbitrary objects;
+ *  - class instances (Buffer for bytea, Decimal wrappers, …), arrays and Dates,
+ *    which {@link isUnmatchedPlainObject} already excludes;
+ *  - multi-key objects, which are never operator-shaped (a real operator object
+ *    has exactly one key) and are far more likely a deliberate payload.
+ *
+ * Shared by the SQL-build path and the cache-hit param-collect path, so a
+ * warmed template can never skip the check.
+ */
+export function assertBindableSetValue(qi, key, value) {
+    if (!isUnmatchedPlainObject(value))
+        return;
+    const keys = Object.keys(value);
+    if (keys.length !== 1 || UPDATE_OPERATOR_KEYS.has(keys[0]))
+        return;
+    const column = qi.toColumn(key);
+    if (whereMod.isJsonColumnType(qi, whereMod.getColumnPgType(qi, column)))
+        return;
+    throw new ValidationError(`[turbine] Unknown update operator "${keys[0]}" on "${qi.table}.${key}". ` +
+        `Supported: ${[...UPDATE_OPERATOR_KEYS].join(', ')}. ` +
+        'A plain object is only written as a value on a json/jsonb column.');
+}
 /**
  * Fingerprint SET clauses for update/updateMany.
  * Captures key names + operator types (set/increment/etc) but not values.
@@ -614,9 +698,9 @@ export function fingerprintSet(_qi, data) {
 /**
  * Collect SET params for update/updateMany. Mirrors buildSetClause param order.
  */
-export function collectSetParams(_qi, data, params) {
+export function collectSetParams(qi, data, params) {
     const entries = Object.entries(data).filter(([, v]) => v !== undefined);
-    for (const [, v] of entries) {
+    for (const [k, v] of entries) {
         if (v !== null &&
             typeof v === 'object' &&
             !Array.isArray(v) &&
@@ -625,10 +709,17 @@ export function collectSetParams(_qi, data, params) {
             const obj = v;
             const keys = Object.keys(obj);
             if (keys.length === 1 && UPDATE_OPERATOR_KEYS.has(keys[0])) {
-                params.push(obj[keys[0]]);
+                // `set` is the only operator that binds a user value of arbitrary type;
+                // the arithmetic operators are finite numbers, which coerceWriteValue
+                // returns untouched. Mirrors buildSetClause.
+                params.push(coerceWriteValue(qi, k, obj[keys[0]]));
                 continue;
             }
+            // Mirror the build path's misspelled-operator guard: the SET fingerprint
+            // is `key:eq` for both a plain value and a bogus operator object, so a
+            // cache HIT would otherwise bind the object and skip the check.
+            assertBindableSetValue(qi, k, v);
         }
-        params.push(v);
+        params.push(coerceWriteValue(qi, k, v));
     }
 }

package/dist/schema-sql.d.ts

@@ -126,7 +126,21 @@ export declare function diffEnumValues(enumName: string, schemaLabels: readonly
 };
 /** A check constraint as declared or read from the DB. */
 export interface CheckSpec {
+    /** Constraint name. Always emitted through `dialect.quoteIdentifier`. */
     name: string;
+    /**
+     * RAW SQL boolean expression (e.g. `price >= 0`), emitted VERBATIM into the
+     * `CHECK (...)` clause.
+     *
+     * This is a deliberate escape hatch: a CHECK body is an arbitrary SQL
+     * expression, so it cannot be quoted, parameterized, or validated by the DDL
+     * builder without reimplementing the server's expression parser. The contract
+     * is therefore on the caller: the expression MUST come from the project's own
+     * schema definition (a `defineSchema` literal or an introspected constraint),
+     * and must NEVER be built from user input, request data, or any other
+     * untrusted source. Anything interpolated into it runs with the privileges of
+     * the migration.
+     */
     expression: string;
 }
 /**

package/dist/schema-sql.js

@@ -57,14 +57,23 @@ function generateCreateEnumType(enumName, labels, dialect) {
 /**
  * Resolve the DDL type token for a column: an enum type name, a `vector(n)`
  * literal, or the dialect's scalar type — with a trailing `[]` for arrays.
+ *
+ * `vectorDimensions` is the one number interpolated into the type token, so it
+ * is validated here as a positive integer within pgvector's limit rather than
+ * being trusted to be numeric.
  */
-function resolveDdlType(config, dialect) {
+function resolveDdlType(config, dialect, columnName) {
     let base;
     if (config.enumName) {
         base = dialect.quoteIdentifier(config.enumName);
     }
     else if (config.vectorDimensions != null) {
-        base = `vector(${config.vectorDimensions})`;
+        const dims = config.vectorDimensions;
+        // pgvector caps a `vector` column at 16000 dimensions.
+        if (typeof dims !== 'number' || !Number.isInteger(dims) || dims < 1 || dims > 16000) {
+            throw new ValidationError(`[turbine] Column "${columnName}": vector dimensions must be an integer between 1 and 16000, got ${String(dims)}.`);
+        }
+        base = `vector(${dims})`;
     }
     else {
         base = dialect.buildColumnType({ type: config.type, maxLength: config.maxLength });
@@ -223,6 +232,9 @@ function generateCreateTable(table, resolveRef, dialect = postgresDialect) {
         columnDefs.push(dialect.buildPrimaryKeyConstraint(cols));
     }
     // Table-level CHECK constraints (named → CONSTRAINT "name" CHECK (...)).
+    // The constraint NAME is quoted; the EXPRESSION is raw SQL emitted verbatim
+    // by design (see the CheckSpec.expression contract) and must never be built
+    // from untrusted input.
     for (const chk of table.checks ?? []) {
         columnDefs.push(chk.name
             ? `CONSTRAINT ${dialect.quoteIdentifier(chk.name)} CHECK (${chk.expression})`
@@ -269,7 +281,7 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = postgresDial
     // Resolve the DDL type (enum name / vector(n) / scalar, plus [] for arrays).
     // Passed as a fully-formed `type` token with no maxLength so the dialect
     // doesn't re-apply VARCHAR(n) on top of it.
-    const ddlType = resolveDdlType(config, dialect);
+    const ddlType = resolveDdlType(config, dialect, snakeName);
     let def = dialect.buildColumnDefinition({
         name: dialect.quoteIdentifier(snakeName),
         type: ddlType,
@@ -288,7 +300,9 @@ function generateColumnDef(fieldName, config, resolveRef, dialect = postgresDial
         if (config.onUpdate)
             def += ` ON UPDATE ${referentialActionToSql(config.onUpdate)}`;
     }
-    // Column-level CHECK constraint (raw SQL expression, user-authored).
+    // Column-level CHECK constraint. The expression is RAW SQL authored in the
+    // schema and is emitted verbatim by design (a DDL builder cannot parse or
+    // parameterize a boolean expression); never build it from untrusted input.
     if (config.check) {
         def += ` CHECK (${config.check})`;
     }
@@ -529,6 +543,8 @@ export function diffCheckConstraints(table, schemaChecks, dbChecks, dialect = po
     const dbByName = new Map(dbChecks.map((c) => [c.name, c]));
     const schemaByName = new Map(schemaChecks.map((c) => [c.name, c]));
     const norm = (e) => e.replace(/\s+/g, ' ').trim();
+    // `c.expression` is raw SQL emitted verbatim by design (see CheckSpec):
+    // schema-authored only, never untrusted input.
     const addStmt = (c) => `ALTER TABLE ${q(table)} ADD CONSTRAINT ${q(c.name)} CHECK (${c.expression});`;
     const dropStmt = (name) => `ALTER TABLE ${q(table)} DROP CONSTRAINT ${q(name)};`;
     for (const sc of schemaChecks) {
@@ -741,7 +757,7 @@ export async function schemaDiff(schema, connectionString) {
                 if (expectedUdt && !isSerialType(config.type) && dbCol.udtName !== expectedUdt) {
                     // resolveDdlType handles enum names, vector(n), arrays, and VARCHAR(n) —
                     // config.type alone would emit the internal ENUM/VECTOR sentinels here.
-                    const sqlType = resolveDdlType(config, dialect);
+                    const sqlType = resolveDdlType(config, dialect, snakeName);
                     const oldSqlType = udtToSqlType(dbCol.udtName, dbCol.maxLength);
                     const sql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${sqlType} USING ${dialect.quoteIdentifier(snakeName)}::${sqlType};`;
                     const reverseSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ALTER COLUMN ${dialect.quoteIdentifier(snakeName)} TYPE ${oldSqlType} USING ${dialect.quoteIdentifier(snakeName)}::${oldSqlType};`;
@@ -879,6 +895,8 @@ export async function schemaDiff(schema, connectionString) {
             const normExpr = (e) => e.replace(/\s+/g, ' ').trim();
             for (const sc of namedSchemaChecks) {
                 const existing = dbCheckByName.get(sc.name);
+                // The constraint name is quoted; `sc.expression` is raw SQL emitted
+                // verbatim by design (see CheckSpec) and must be schema-authored.
                 const addSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} ADD CONSTRAINT ${dialect.quoteIdentifier(sc.name)} CHECK (${sc.expression});`;
                 const dropSql = `ALTER TABLE ${dialect.quoteIdentifier(tableName)} DROP CONSTRAINT ${dialect.quoteIdentifier(sc.name)};`;
                 if (!existing) {