turbine-orm 0.51.0 → 0.52.0

package/dist/query/builder.js

@@ -134,6 +134,82 @@ export const AUTO_TO_ONE_JOIN_MAX_ROWS = Math.round(AUTO_ASSUMED_ROUND_TRIP_MS /
  */
 export const AUTO_TO_ONE_JOIN_ROWS_MIN = 100;
 export const AUTO_TO_ONE_JOIN_ROWS_MAX = 100_000;
+/**
+ * WHY THIS IS A CONFIGURED LATENCY AND NOT A MEASURED ONE.
+ *
+ * The obvious next step from the formula above is to have the client measure
+ * its own round-trip time and derive the threshold at runtime. That was built
+ * and benchmarked, and it is NOT what ships, for a reason worth recording so it
+ * is not re-litigated blind:
+ *
+ * Every query's wall time is `roundTrip + serverWork`, and nothing in a
+ * duration distinguishes the two. An all-time MINIMUM reads a lucky packet
+ * (1.489ms on a link whose real per-statement cost was 2.862ms) and lands the
+ * threshold at half the true break-even. A MEDIAN over recent durations is
+ * accurate when the workload is cheap queries, but the workload being planned
+ * for here is precisely the expensive one: in the verification sweep the ring
+ * filled with 10-17ms relation queries, the estimate inflated, and `'auto'`
+ * held an 8,000-row query on the join plan, 1.30x slower than the better plan,
+ * WORSE than the fixed constant it replaced. Capping the median against a
+ * multiple of the floor mitigates it but turns the whole thing into a pair of
+ * magic numbers tuned against two synthetic links, which is the same mistake as
+ * a socket-tuned row count wearing a different hat.
+ *
+ * Round-trip time is a deployment fact, not a runtime discovery: it is fixed by
+ * where the app runs relative to the database, the operator knows it (or gets
+ * it from one `ping`), and it does not change between queries. So it is
+ * configuration. That also keeps plan selection deterministic, which matters
+ * for a library whose documented guarantee is that the strategy changes the
+ * plan and never the result.
+ */
+/**
+ * The smallest plan-time parent-row bound at which `'auto'` moves a relation
+ * `_count` on a PROVEN-UNINDEXED probe to the grouped follow-up. Deliberately
+ * 2, i.e. "everything except a parent set provably bounded at one row".
+ *
+ * `_count` does NOT share the to-one break-even formula above, because its two
+ * plans do not differ by a small per-row penalty. Writing S for one scan of the
+ * child table and RTT for a round trip:
+ *
+ *     inline(N)  = N x S        (a correlated COUNT(*) per parent row; see
+ *                                buildRelationCountExpr in relations.ts, the
+ *                                inline form is NOT a grouped scan)
+ *     batched(N) = S + RTT      (one `COUNT(*) ... GROUP BY fk` follow-up)
+ *
+ * so the crossover sits at `N = 1 + RTT/S` and, decisively, the two regrets are
+ * not comparable in kind:
+ *
+ *   - choosing batched when inline would have won costs at most RTT, once, and
+ *     ONLY at N = 1 (at N = 1 the difference is exactly RTT, and it shrinks to
+ *     zero immediately after);
+ *   - choosing inline when batched would have won costs (N - 1) x S, which is
+ *     unbounded in the parent count.
+ *
+ * Measured on an UNINDEXED FK (PostgreSQL 16, 200K-row child table, 10K-row
+ * parent table, median of 11 interleaved reps per point, loopback;
+ * benchmarks/bench-count-strategy.ts):
+ *
+ *   parents      1      2      3      5     20     100     1000    10000
+ *   inline    4.3ms  8.3ms 12.3ms 20.1ms 79.2ms 417.5ms   3.06s   31.06s
+ *   batched   5.2ms  4.8ms  4.8ms  5.2ms  6.1ms  11.5ms   9.9ms   28.4ms
+ *   winner   inline batched batched batched batched batched batched batched
+ *   ratio     1.22x  1.73x  2.54x  3.84x 13.05x  36.42x 310.92x 1093.35x
+ *
+ * Inline wins exactly one cell, by 0.9ms, then loses the next by 1.73x and the
+ * last by 1093x. A skewed child distribution (half the rows on ten parents)
+ * moves nothing: same crossover at 2, same 1179x at 10,000. So the useful
+ * threshold is not a tunable row count, it is the one row where inline provably
+ * cannot lose. There is deliberately no config knob: the entire regret this rule
+ * can produce is one round trip, which is less than any knob would be worth, and
+ * `relationLoadStrategy: 'join'` already forces the single-statement plan.
+ *
+ * This applies ONLY to a probe the introspected index metadata PROVES unindexed.
+ * An INDEXED `_count` stays inline at every size measured (inline wins 1.30x to
+ * 2.06x from 1 to 10,000 parents, because the per-parent subquery collapses to
+ * an index-only scan costing ~0.001ms), and the partition below never demotes
+ * it.
+ */
+export const AUTO_COUNT_BATCH_MIN_PARENT_ROWS = 2;
 /**
  * Strict structural equality for a single SQL parameter value. Handles the
  * value shapes Turbine binds: primitives (incl. `NaN` and `bigint`), `null`/
@@ -436,15 +512,41 @@ export class QueryInterface {
         this.txScoped = options?._txScoped ?? false;
         this.options = options;
         // Pre-compute column type lookup maps (TASK-26)
+        //
+        // Metadata can carry a column's database type in EITHER of two places: on
+        // the column entry (`dialectType` / `pgType`, what introspection and
+        // `turbine generate` emit) or in the table-level `dialectTypes` / `pgTypes`
+        // maps. Reading only the column entry is not a harmless miss for metadata
+        // that populates just the table-level maps: an unresolved type makes
+        // `coerceWriteValue` return a bound `Date` by identity, so a zone-less
+        // `date` / `timestamp` column stores the PROCESS's local calendar fields
+        // (and, because the read path pins UTC, a turbine-only round trip hides
+        // it). Consult both, column entry first. This costs one extra own-property
+        // lookup per column ONCE per QueryInterface, nothing per query.
         this.columnPgTypeMap = new Map();
         this.columnArrayTypeMap = new Map();
         this.crossSchemaTypeColumns = new Set();
+        const tableDialectTypes = this.tableMeta.dialectTypes;
+        const tablePgTypes = this.tableMeta.pgTypes;
         for (const col of this.tableMeta.columns) {
-            this.columnPgTypeMap.set(col.name, col.dialectType ?? col.pgType);
-            this.columnArrayTypeMap.set(col.name, col.arrayType ?? col.pgArrayType);
+            const dbType = col.dialectType ??
+                col.pgType ??
+                (tableDialectTypes && ownLookup(tableDialectTypes, col.name)) ??
+                (tablePgTypes && ownLookup(tablePgTypes, col.name));
+            if (dbType !== undefined)
+                this.columnPgTypeMap.set(col.name, dbType);
+            // The array map has the same shape of gap, but TableMetadata carries NO
+            // table-level array-type map (only `dialectTypes` / `pgTypes`), so there
+            // is nothing to fall back to. Deriving one from the resolved base type
+            // would invent an UNNEST cast the metadata never declared, so the column
+            // entry stays the only source.
+            const arrayType = col.arrayType ?? col.pgArrayType;
+            if (arrayType !== undefined)
+                this.columnArrayTypeMap.set(col.name, arrayType);
             if (col.pgTypeSchema !== undefined)
                 this.crossSchemaTypeColumns.add(col.name);
         }
+        this.warnUntypedColumns();
         // Bind the shared WHERE-walk view once. `tableMeta` is immutable after this
         // point; the method wrappers forward to the (private) instance methods so
         // the walk needs no public accessors on the class.
@@ -468,6 +570,18 @@ export class QueryInterface {
             scopedHostCache: this.scopedHostCache,
             columnPgTypeMap: this.columnPgTypeMap,
             columnArrayTypeMap: this.columnArrayTypeMap,
+            // The `utcTimestamps: false` opt-out has to reach the write/where web:
+            // omitting it here left `qi.utcTimestamps` undefined for the whole
+            // module, where `!== false` reads as opted IN, so the write side ignored
+            // the flag and rewrote binds the caller had opted out of.
+            //
+            // This half of the flag is PER CLIENT. The read half is not: it is the
+            // pg OID 1114 type parser, which `pg.types.setTypeParser` installs once
+            // per process. Two clients in one process therefore cannot hold
+            // different values, and TurbineClient refuses the second one rather than
+            // building a client whose writes and reads disagree (see
+            // `assertUtcTimestampsAgree` in client.ts).
+            utcTimestamps: this.utcTimestamps,
             crossSchemaTypeColumns: this.crossSchemaTypeColumns,
             get currentSkip() {
                 return self.currentSkip;
@@ -498,6 +612,73 @@ export class QueryInterface {
             paginationValue: (value, arg) => this.paginationValue(value, arg),
         };
     }
+    /**
+     * Dev-only, once per table: the columns whose database type is absent from
+     * BOTH the column entry and the table-level type maps, the residual case
+     * after the two-source resolution above.
+     *
+     * The set is deliberately every untyped column, not the `dateColumns`
+     * members. An unresolved type is precisely the state in which Turbine cannot
+     * say WHICH kind of column it is, so restricting the scan to `dateColumns`
+     * got it wrong in both directions: that set carries `timestamptz` (whose
+     * bind was never affected, since binding the `Date` is the correct thing to
+     * do for it) and omits `time` / `timetz` entirely (deliberately, see
+     * `timeOfDayKind` in schema.ts), which is the one kind that fails LOUDLY
+     * rather than silently. The message therefore names the columns and states
+     * what each kind does, rather than asserting a kind it cannot know.
+     *
+     * What is actually at stake per kind, all of it `coerceWriteValue` returning
+     * the bound `Date` by identity for want of a type:
+     *   - zone-less `date` / `timestamp`: the driver serializes with the
+     *     PROCESS's offset, so the column stores local calendar fields. Nothing
+     *     surfaces at runtime, and a turbine-only round trip reads the same value
+     *     back (the read path shifts by the same offset), so only an outside
+     *     reader sees the drift.
+     *   - `time` / `timetz`: the driver serializes a full ISO timestamp, which
+     *     Postgres rejects with `22007 invalid input syntax for type time`.
+     *   - `timestamptz` and every non-temporal type: unaffected.
+     *
+     * PostgreSQL only: the UTC bind rewrite is Postgres-gated (see
+     * `utcDateTimeWrites` in writes.ts), so on the other engines a missing type
+     * changes nothing about how a `Date` is bound. Suppressed under
+     * `NODE_ENV=production` like the other dev diagnostics and deduped through
+     * the shared registry, so a hot table logs one line for the process.
+     *
+     * Cannot throw on odd metadata: it walks `tableMeta.columns`, the array the
+     * constructor loop above has already iterated (and that client.ts validates
+     * as an array), never `dateColumns`, which is a `Set` in every first-party
+     * metadata path but arrives as a plain object from JSON-round-tripped
+     * metadata. A dev-only diagnostic that crashes a shape production would serve
+     * is worse than the bug it reports.
+     */
+    warnUntypedColumns() {
+        if (process.env.NODE_ENV === 'production')
+            return;
+        if (this.dialect.name !== 'postgresql')
+            return;
+        const untyped = [];
+        for (const col of this.tableMeta.columns) {
+            if (this.columnPgTypeMap.get(col.name) === undefined)
+                untyped.push(col.name);
+        }
+        if (untyped.length === 0)
+            return;
+        if (!shouldWarnOnce(WARN_NS.untypedDateColumn, this.table))
+            return;
+        // Bound the line on a wide table: the fix is per table, not per column, so
+        // the first few names are enough to recognize the metadata that produced it.
+        const MAX_NAMED = 12;
+        const named = untyped.slice(0, MAX_NAMED).join(', ');
+        const rest = untyped.length > MAX_NAMED ? ` (+${untyped.length - MAX_NAMED} more)` : '';
+        console.warn(`[turbine] table "${this.table}": no database type in metadata for column(s) ${named}${rest} (neither the ` +
+            "column entry's `dialectType`/`pgType` nor the table-level `dialectTypes`/`pgTypes` map). Turbine cannot " +
+            'tell which of them are zone-less, so a `Date` written to one is bound by the driver as-is: right for ' +
+            "`timestamptz`, but a zone-less `date`/`timestamp` column then stores the PROCESS's local calendar fields " +
+            'rather than UTC (silently, since the read path shifts back by the same offset), and a `time`/`timetz` ' +
+            'column rejects the value outright (`22007 invalid input syntax for type time`). Columns whose type IS ' +
+            'resolved, every `timestamptz` among them, are unaffected. Regenerate the metadata with ' +
+            '`npx turbine generate`, or set the column types in your `defineSchema` definition.');
+    }
     /** Quote an identifier through the active SQL dialect. */
     q(name) {
         return this.dialect.quoteIdentifier(name);
@@ -942,8 +1123,20 @@ export class QueryInterface {
      * `findFirst` pass `false` explicitly (their parent set is one row).
      */
     autoParentSetLarge(args) {
-        const limit = args?.take ?? args?.limit ?? this.defaultLimit;
-        return limit === undefined || limit > this.autoToOneThreshold();
+        const bound = this.autoParentBound(args);
+        return bound === undefined || bound > this.autoToOneThreshold();
+    }
+    /**
+     * The plan-time UPPER BOUND on the parent-row count, or `undefined` when the
+     * query is unbounded. This is the raw number behind
+     * {@link autoParentSetLarge}; the `_count` rule needs the number itself
+     * because its threshold ({@link AUTO_COUNT_BATCH_MIN_PARENT_ROWS}) is two
+     * rows rather than the to-one break-even. `findUnique` / `findFirst` pass `1`
+     * directly: their parent set is one row as a matter of the statement's shape,
+     * not an estimate.
+     */
+    autoParentBound(args) {
+        return args?.take ?? args?.limit ?? this.defaultLimit;
     }
     /**
      * The parent-row count at which `'auto'` stops preferring the single-statement
@@ -990,13 +1183,13 @@ export class QueryInterface {
      *
      * Everything else (indexed to-many, composite-key, unknown) stays in `joinWith`
      * (byte-identical join). The reserved `_count` key falls back on rule 1 only,
-     * and only for a large parent set: an inline `_count` is one correlated
-     * `COUNT(*)` per parent row, so the grouped follow-up wins exactly when there
-     * are many parents, while for a handful of parents the extra round-trip costs
-     * more than the repeated (small) scans. Also returns the engaged relations for
-     * the dev note.
+     * and on its OWN size rule: an inline `_count` is one correlated `COUNT(*)`
+     * per parent row over an unindexed child table, so the grouped follow-up wins
+     * from {@link AUTO_COUNT_BATCH_MIN_PARENT_ROWS} parent rows upward and inline
+     * is preferred only when the parent set is provably bounded below that. Also
+     * returns the engaged relations for the dev note.
      */
-    partitionWithForAuto(withClause, parentSetLarge) {
+    partitionWithForAuto(withClause, parentSetLarge, parentBound) {
         const hasIndexInfo = schemaHasIndexInfo(this.schema);
         const joinWith = {};
         const batchedWith = {};
@@ -1006,7 +1199,8 @@ export class QueryInterface {
                 continue;
             if (key === '_count') {
                 const cv = this.autoCountVerdict(spec, this.tableMeta);
-                if (hasIndexInfo && parentSetLarge && cv.unindexed && cv.eligible) {
+                const countWorthBatching = parentBound === undefined || parentBound >= AUTO_COUNT_BATCH_MIN_PARENT_ROWS;
+                if (hasIndexInfo && countWorthBatching && cv.unindexed && cv.eligible) {
                     batchedWith[key] = spec;
                     engaged.push({ relation: '_count', reason: 'unindexed', miss: cv.miss });
                 }
@@ -1044,7 +1238,7 @@ export class QueryInterface {
      * to batched. Returns `null` (→ run the plain join path, byte-identical, same
      * cache keys) when nothing qualifies.
      */
-    planAuto(withArg, stableFlag, parentSetLarge) {
+    planAuto(withArg, stableFlag, parentSetLarge, parentBound) {
         // Without DB-backed index info (code-first / defineSchema-only) no probe can
         // be PROVEN unindexed; the to-one cardinality rule does not depend on index
         // metadata, so it still applies.
@@ -1053,7 +1247,7 @@ export class QueryInterface {
         const withClause = this.resolveStableOrder(stableFlag)
             ? this.applyStableRelationOrder(withArg, this.table)
             : withArg;
-        const split = this.partitionWithForAuto(withClause, parentSetLarge);
+        const split = this.partitionWithForAuto(withClause, parentSetLarge, parentBound);
         if (Object.keys(split.batchedWith).length === 0)
             return null;
         return split;
@@ -1075,7 +1269,15 @@ export class QueryInterface {
             const probe = e.miss
                 ? `probe "${e.miss.table}"(${e.miss.columns.join(', ')}) has no covering index`
                 : 'a probe in its subtree has no covering index';
-            console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}). ` +
+            // The `_count` case is the one people read as a needless demotion, because
+            // the follow-up statement is a grouped COUNT and the inline form looks
+            // like it would be one too. It is not: state the shape it replaced.
+            const why = e.relation === '_count'
+                ? ' The inline form is one correlated COUNT(*) re-evaluated per parent row, so on an unindexed ' +
+                    `probe it is one full scan of "${e.miss?.table ?? 'the child table'}" per parent row; the ` +
+                    'follow-up is one grouped scan for the whole page.'
+                : '';
+            console.warn(`[turbine] auto strategy: relation "${e.relation}" on "${this.table}" loads batched (${probe}).${why} ` +
                 "Create the covering index (or set `relationLoadStrategy: 'join'` to force the single-statement " +
                 'plan); run `npx turbine doctor` for the exact CREATE INDEX SQL.');
         }
@@ -1491,8 +1693,10 @@ export class QueryInterface {
                     return this.runFindUniqueBatched(args);
                 if (strategy === 'auto') {
                     // findUnique's parent set is a single row: the join plan's correlated
-                    // subqueries run once, so the cardinality rule never applies here.
-                    const split = this.planAuto(args.with, args.stableRelationOrder, false);
+                    // subqueries run once, so the cardinality rule never applies here, and
+                    // an inline `_count` is one scan against the batched plan's one scan
+                    // plus a round trip.
+                    const split = this.planAuto(args.with, args.stableRelationOrder, false, 1);
                     if (split)
                         return this.runAutoSplit(args, split, true);
                 }
@@ -1676,7 +1880,7 @@ export class QueryInterface {
                 if (strategy === 'batched')
                     return this.runFindManyBatched(args);
                 if (strategy === 'auto') {
-                    const split = this.planAuto(args.with, args.stableRelationOrder, this.autoParentSetLarge(args));
+                    const split = this.planAuto(args.with, args.stableRelationOrder, this.autoParentSetLarge(args), this.autoParentBound(args));
                     if (split)
                         return this.runAutoSplit(args, split, false);
                 }
@@ -2185,7 +2389,7 @@ export class QueryInterface {
                 }
                 if (strategy === 'auto') {
                     // findFirst is findMany + LIMIT 1: a one-row parent set.
-                    const split = this.planAuto(args.with, args.stableRelationOrder, false);
+                    const split = this.planAuto(args.with, args.stableRelationOrder, false, 1);
                     if (split) {
                         const rows = (await this.runAutoSplit({ ...args, limit: 1 }, split, false));
                         return (rows[0] ?? null);

package/dist/query/index.d.ts

@@ -11,4 +11,4 @@ export { postgresDialect } from '../dialect.js';
 export type { SqlCacheEntry } from './utils.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
 export type { DeferredQuery, MiddlewareFn, QueryEvent, QueryEventListener, QueryInterfaceOptions, ReselectExecutor, } from './builder.js';
-export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';
+export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/query/index.js

@@ -7,4 +7,4 @@
  */
 export { postgresDialect } from '../dialect.js';
 export { buildCorrelation, escapeLike, escSingleQuote, fnv1a64Hex, LRUCache, OPERATOR_KEYS, quoteIdent, sqlToPreparedName, } from './utils.js';
-export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';
+export { AUTO_ASSUMED_ROUND_TRIP_MS, AUTO_COUNT_BATCH_MIN_PARENT_ROWS, AUTO_JOIN_PENALTY_MS_PER_ROW, AUTO_TO_ONE_JOIN_MAX_ROWS, AUTO_TO_ONE_JOIN_ROWS_MAX, AUTO_TO_ONE_JOIN_ROWS_MIN, QueryInterface, } from './builder.js';

package/dist/query/warn-registry.d.ts

@@ -65,4 +65,14 @@ export declare const WARN_NS: {
      * engage is indistinguishable from one that does nothing, so say so once.
      */
     readonly flattenFallback: "flattenFallback";
+    /**
+     * Columns whose database type resolves from NEITHER the column entry nor the
+     * table-level type maps, so Turbine cannot tell which of them are zone-less
+     * and a bound `Date` is left to the driver rather than rewritten to a UTC
+     * literal (builder.ts `warnUntypedColumns`). The scan covers every column,
+     * not just `dateColumns`, because an unresolved type is precisely the state
+     * in which the kind is unknown; the warning emits one line per table listing
+     * the offenders, not one per column. The namespace name is historical.
+     */
+    readonly untypedDateColumn: "untypedDateColumn";
 };

package/dist/query/warn-registry.js

@@ -100,4 +100,14 @@ export const WARN_NS = {
      * engage is indistinguishable from one that does nothing, so say so once.
      */
     flattenFallback: 'flattenFallback',
+    /**
+     * Columns whose database type resolves from NEITHER the column entry nor the
+     * table-level type maps, so Turbine cannot tell which of them are zone-less
+     * and a bound `Date` is left to the driver rather than rewritten to a UTC
+     * literal (builder.ts `warnUntypedColumns`). The scan covers every column,
+     * not just `dateColumns`, because an unresolved type is precisely the state
+     * in which the kind is unknown; the warning emits one line per table listing
+     * the offenders, not one per column. The namespace name is historical.
+     */
+    untypedDateColumn: 'untypedDateColumn',
 };

package/dist/query/writes.js

@@ -10,7 +10,7 @@
  * stay class-resident, reached through the ctx. See builder.ts for the thin
  * delegating methods and the async execute wrappers.
  */
-import { NotFoundError, OptimisticLockError, ValidationError } from '../errors.js';
+import { NotFoundError, OptimisticLockError, UnsupportedFeatureError, ValidationError } from '../errors.js';
 import { camelToSnake, snakeToCamel } from '../schema.js';
 import { expandCompoundUniqueWhere } from './compound-unique.js';
 import { isUnmatchedPlainObject, UPDATE_OPERATOR_KEYS } from './filters.js';
@@ -77,6 +77,36 @@ export function buildReselectByWhere(qi, whereObj) {
     const where = clause ? ` WHERE ${clause}` : '';
     return { sql: `SELECT ${writeReselectSelection(qi)} FROM ${qi.q(qi.table)}${where}`, params };
 }
+/**
+ * Build the all-defaults INSERT for a `data` that names no column, via the
+ * dialect's `buildDefaultValuesInsertStatement` hook.
+ *
+ * `INSERT INTO t () VALUES ()` (what the column-driven builders render for an
+ * empty `data`) is a syntax error everywhere but MySQL, and the correct
+ * statement differs per engine, so the shape lives behind the dialect seam.
+ * `{}` is easy to reach honestly, a handler that assembles its payload from
+ * optional request fields produces it on a request that supplied none of them,
+ * so the row of pure defaults is inserted and returned rather than crashing.
+ * The empty-`update` no-op in {@link buildUpdate} has the same rationale.
+ *
+ * A table with no usable defaults still fails, correctly, with the database's
+ * own NOT NULL violation (E010): nothing here pre-empts that.
+ *
+ * A dialect predating the hook raises E017 rather than emitting SQL its engine
+ * will reject.
+ */
+function buildDefaultValuesInsert(qi, rowCount, skipDuplicates) {
+    const build = qi.dialect.buildDefaultValuesInsertStatement;
+    if (!build) {
+        throw new UnsupportedFeatureError('create/createMany with an empty data object', qi.dialect.name, 'This dialect has no all-defaults INSERT form; name at least one column in `data`.');
+    }
+    return build.call(qi.dialect, {
+        table: qi.q(qi.table),
+        rowCount,
+        skipDuplicates,
+        returning: writeReturningColumns(qi),
+    });
+}
 export function buildCreate(qi, args) {
     assertWritable(qi, 'create');
     assertNoGeneratedColumns(qi, args.data, 'create');
@@ -85,12 +115,15 @@ export function buildCreate(qi, args) {
     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({
-        table: qi.q(qi.table),
-        columns,
-        valuePlaceholders: placeholders,
-        returning: writeReturningColumns(qi),
-    });
+    // `data: {}` (or all-undefined) names no column: insert a row of defaults.
+    const sql = entries.length === 0
+        ? buildDefaultValuesInsert(qi, 1)
+        : qi.dialect.buildInsertStatement({
+            table: qi.q(qi.table),
+            columns,
+            valuePlaceholders: placeholders,
+            returning: writeReturningColumns(qi),
+        });
     return {
         sql,
         params,
@@ -137,6 +170,69 @@ export function makeCreateReselect(qi, insertSql, insertParams, data) {
         return exec(`SELECT ${writeReselectSelection(qi)} FROM ${qi.q(qi.table)}${where}`, selParams);
     };
 }
+/**
+ * The fields a write's `data` object actually names.
+ *
+ * A key whose value is `undefined` is NOT named: single-row {@link buildCreate}
+ * filters those out of its column list, so the column takes its declared
+ * default. `createMany` reads its rows through this same helper, so
+ * `{ n: undefined }` and `{}` mean the identical thing on both paths.
+ */
+function definedKeys(row) {
+    return Object.keys(row).filter((k) => row[k] !== undefined);
+}
+/**
+ * Refuse a `createMany` whose rows do not all name the SAME fields.
+ *
+ * `createMany` compiles ONE statement, and its column list is taken from the
+ * first row alone, so a row that disagrees with the first row loses data in
+ * both directions and silently:
+ *
+ * - a field the first row names and a later row OMITS is bound as NULL,
+ *   overwriting that column's declared default (and failing outright on a NOT
+ *   NULL column that has one);
+ * - a field only a LATER row names is not in the column list at all, so its
+ *   value never reaches the database.
+ *
+ * Neither shape is expressible as a single statement on every engine. The
+ * row-major `VALUES` form can carry a per-cell `DEFAULT` keyword on
+ * PostgreSQL, MySQL and SQL Server, but SQLite has no such grammar (`VALUES
+ * (1, DEFAULT)` is a parse error there), and adopting it would also drop
+ * PostgreSQL off the column-major `UNNEST` form that binds one array per
+ * column rather than one placeholder per cell. So the honest answer is a
+ * refusal that names the offending row and its differing columns.
+ *
+ * A single row is trivially uniform, and rows that all name the same fields
+ * (the overwhelmingly common shape) cost one `Object.keys` pass and emit
+ * byte-identical SQL.
+ */
+function assertUniformCreateManyRows(qi, rows, firstKeys) {
+    const expected = new Set(firstKeys);
+    for (let i = 1; i < rows.length; i++) {
+        const rowKeys = definedKeys(rows[i]);
+        const unexpected = rowKeys.filter((k) => !expected.has(k));
+        // No stranger and the same count means the same set (object keys are unique).
+        if (unexpected.length === 0 && rowKeys.length === expected.size)
+            continue;
+        const present = new Set(rowKeys);
+        const missing = firstKeys.filter((k) => !present.has(k));
+        const parts = [];
+        if (missing.length > 0)
+            parts.push(`does not supply ${quoteList(missing)}`);
+        if (unexpected.length > 0)
+            parts.push(`supplies ${quoteList(unexpected)}, which the first row does not`);
+        throw new ValidationError(`[turbine] createMany on "${qi.table}": row ${i} ${parts.join(' and ')}. ` +
+            'Every row must supply the same fields: createMany builds ONE statement whose column list comes from the ' +
+            "first row, so a field a later row omits would be written as NULL over that column's default, and a field " +
+            'only a later row names would be dropped. Supply the field explicitly on every row (a field set to ' +
+            '`undefined` counts as omitted, exactly as it does in `create`), or split the call into one createMany per ' +
+            'row shape.');
+    }
+}
+/** `a, b` → `"a", "b"`, for the field lists in {@link assertUniformCreateManyRows}. */
+function quoteList(fields) {
+    return fields.map((f) => `"${f}"`).join(', ');
+}
 export function buildCreateMany(qi, args) {
     const qt = qi.q(qi.table);
     if (args.data.length === 0) {
@@ -151,7 +247,19 @@ export function buildCreateMany(qi, args) {
     for (const row of args.data) {
         assertNoGeneratedColumns(qi, row, 'createMany');
     }
-    const keys = Object.keys(args.data[0]).filter((k) => args.data[0][k] !== undefined);
+    const keys = definedKeys(args.data[0]);
+    assertUniformCreateManyRows(qi, args.data, keys);
+    // No column named by the first row: every row is pure defaults (the bulk
+    // counterpart of `create({ data: {} })`, see buildDefaultValuesInsert). The
+    // uniformity check above has already established that EVERY row is empty.
+    if (keys.length === 0) {
+        return {
+            sql: buildDefaultValuesInsert(qi, args.data.length, args.skipDuplicates),
+            params: [],
+            transform: (result) => result.rows.map((row) => parseWriteRow(qi, row)),
+            tag: `${qi.table}.createMany`,
+        };
+    }
     const columns = keys.map((k) => qi.toColumn(k));
     const rowValues = args.data.map((row) => {
         const record = row;

package/dist/sqlite.d.ts

@@ -46,8 +46,9 @@
  * ```
  */
 import type { DatabaseSync } from 'node:sqlite';
-import { type PgCompatPool, type PgCompatPoolClient, TurbineClient, type TurbineConfig } from './client.js';
+import { type PgCompatPool, type PgCompatPoolClient, TurbineClient } from './client.js';
 import { type Dialect, type IntrospectOptions } from './dialect.js';
+import type { EngineClientConfig } from './engine-config.js';
 import { type SchemaMetadata, type TableMetadata } from './schema.js';
 /** pg-style query argument: a SQL string or a `{ text, values }` config object. */
 type QueryArg = string | {
@@ -109,8 +110,12 @@ export declare function introspectSqliteDatabase(db: DatabaseSync, options?: {
  * are per-handle), so codegen should target a real file.
  */
 export declare function introspectSqlite(options: IntrospectOptions): Promise<SchemaMetadata>;
-/** Options for {@link turbineSqlite}. Mirrors the relevant {@link TurbineConfig} fields. */
-export interface TurbineSqliteOptions extends Pick<TurbineConfig, 'logging' | 'defaultLimit' | 'warnOnUnlimited'> {
+/**
+ * Options for {@link turbineSqlite}: every client-level {@link TurbineConfig}
+ * field the engine can honour (see {@link EngineClientConfig}) plus the SQLite
+ * pragmas below.
+ */
+export interface TurbineSqliteOptions extends EngineClientConfig {
     /**
      * Enable WAL journal mode for file databases (better read concurrency).
      * Ignored for `':memory:'`. Default: `true`.
@@ -131,7 +136,8 @@ export interface TurbineSqliteOptions extends Pick<TurbineConfig, 'logging' | 'd
  *
  * @param target  A SQLite file path, `':memory:'`, or an open `DatabaseSync`.
  * @param schema  Introspected or hand-written {@link SchemaMetadata}.
- * @param options Optional pragmas + logging / defaultLimit / warnOnUnlimited.
+ * @param options Optional SQLite pragmas plus any client-level
+ *                {@link TurbineConfig} field (see {@link EngineClientConfig}).
  *
  * @example
  * ```ts

package/dist/sqlite.js

@@ -48,7 +48,7 @@
 import { createRequire } from 'node:module';
 import { TurbineClient } from './client.js';
 import { postgresDialect, } from './dialect.js';
-import { ConnectionError } from './errors.js';
+import { ConnectionError, UnsupportedFeatureError } from './errors.js';
 import { applyTableFilters, deriveEngineRelations } from './introspect.js';
 import { isDateType, snakeToCamel, } from './schema.js';
 let cachedDatabaseSync;
@@ -482,6 +482,17 @@ export const sqliteDialect = {
             params: input.rowValues.flat(),
         };
     },
+    buildDefaultValuesInsertStatement(input) {
+        // SQLite's `DEFAULT VALUES` inserts exactly one row and the engine accepts
+        // neither `VALUES (DEFAULT, …)` nor MySQL's empty `VALUES ()` tuple, so
+        // there is no multi-row all-defaults statement to emit.
+        if (input.rowCount !== 1) {
+            throw new UnsupportedFeatureError(`createMany with ${input.rowCount} empty data rows`, 'sqlite', 'SQLite INSERT … DEFAULT VALUES inserts a single row and has no multi-row form; ' +
+                'issue one create({ data: {} }) per row.');
+        }
+        const conflict = input.skipDuplicates ? ' ON CONFLICT DO NOTHING' : '';
+        return `INSERT INTO ${input.table} DEFAULT VALUES${conflict}${this.buildReturningClause(input.returning)}`;
+    },
     buildUpsertStatement(input) {
         return (`INSERT INTO ${input.table} (${input.insertColumns.join(', ')}) VALUES (${input.valuePlaceholders.join(', ')})` +
             ` ON CONFLICT (${input.conflictColumns.join(', ')}) DO UPDATE SET ${input.updateSetClauses.join(', ')}` +
@@ -778,7 +789,8 @@ function openSqliteDatabase(target, options) {
  *
  * @param target  A SQLite file path, `':memory:'`, or an open `DatabaseSync`.
  * @param schema  Introspected or hand-written {@link SchemaMetadata}.
- * @param options Optional pragmas + logging / defaultLimit / warnOnUnlimited.
+ * @param options Optional SQLite pragmas plus any client-level
+ *                {@link TurbineConfig} field (see {@link EngineClientConfig}).
  *
  * @example
  * ```ts
@@ -789,12 +801,14 @@ function openSqliteDatabase(target, options) {
 export function turbineSqlite(target, schema, options = {}) {
     const db = typeof target === 'string' ? openSqliteDatabase(target, options) : target;
     const pool = new SqlitePool(db);
+    // Everything that is not a SQLite pragma is client config and rides through
+    // untouched, so a new TurbineConfig option works here the day it lands. The
+    // engine-owned keys come last, so no caller can unbind the dialect.
+    const { wal: _wal, busyTimeoutMs: _busyTimeoutMs, foreignKeys: _foreignKeys, ...clientConfig } = options;
     return new TurbineClient({
+        ...clientConfig,
         pool,
         dialect: sqliteDialect,
         preparedStatements: false,
-        logging: options.logging,
-        defaultLimit: options.defaultLimit,
-        warnOnUnlimited: options.warnOnUnlimited,
     }, schema);
 }