turbine-orm 0.81.0 → 0.90.0

package/dist/schema.d.ts

@@ -79,10 +79,24 @@ export interface ColumnMetadata {
     pgTypeSchema?: string;
     /** TypeScript type string (e.g. 'number', 'string', 'Date') */
     tsType: string;
+    /**
+     * The TypeScript type a `defineSchema()` file declared for this column, WITHOUT
+     * `| null`. Only `turbine generate` reads it. Every engine branches on
+     * {@link tsType}, which stays the type mapped from the database type (MySQL
+     * boolean normalization and PowDB column types depend on that). Absent for
+     * introspected metadata and for columns that declare no type.
+     */
+    declaredTsType?: string;
     /** Whether the column allows NULL */
     nullable: boolean;
     /** Whether the column has a DEFAULT, is serial, or is generated */
     hasDefault: boolean;
+    /**
+     * The column's declared DEFAULT expression as SQL text (for example `now()`, `'active'`, `0`), when the
+     * metadata source knows it. defineSchema records it; engines with no server-side defaults (PowDB) apply it
+     * client-side. Absent for introspected metadata.
+     */
+    defaultValue?: string | null;
     /**
      * Whether the **database server** generates this column's value on insert -
      * a `serial`/`BIGSERIAL` sequence, an `IDENTITY` column, or PowDB's `auto`
@@ -114,10 +128,10 @@ export interface ColumnMetadata {
      * True when this column holds personally identifiable information (PII).
      * Tagged in `defineSchema` (`pii: true`) and carried through generated
      * metadata. A PII column is EXCLUDED from default projections: it comes back
-     * only when explicitly named in `select` or when the query passes
-     * `includePii: UNSAFE` (full opt-in, the imported sentinel symbol, since a
-     * literal `true` is what a stray JSON body deserializes to). Studio redacts
-     * PII cells by default.
+     * only from a read that passes `includePii: UNSAFE` (the imported sentinel
+     * symbol, since a literal `true` is what a stray JSON body deserializes to).
+     * Naming it in `select` without that flag throws (E003), and a write never
+     * returns it. Studio redacts PII cells by default.
      * Optional / defaults to `false`; untagged schemas behave exactly as before.
      * Introspection never auto-tags PII (it is a code-first declaration).
      */
@@ -228,8 +242,15 @@ export interface IndexMetadata {
      */
     declared?: boolean;
 }
-/** Map a Postgres type to its TypeScript equivalent */
+/** Map a Postgres type to the TypeScript type a read returns for it. */
 export declare function pgTypeToTs(pgType: string, nullable: boolean): string;
+/**
+ * Map a Postgres type to the TypeScript type the write path accepts for it
+ * (the generated `*Create` / `*Update` field types). Wider than
+ * {@link pgTypeToTs} where the runtime takes more than one spelling, narrower
+ * where the parsed read value cannot be written back (see `PG_TO_TS_INPUT`).
+ */
+export declare function pgTypeToTsInput(pgType: string, nullable: boolean): string;
 /** Check if a Postgres type is a date/timestamp that needs Date parsing */
 export declare function isDateType(pgType: string): boolean;
 /**

package/dist/schema.js

@@ -14,6 +14,17 @@ export function normalizeKeyColumns(key) {
 // ---------------------------------------------------------------------------
 // Type mapping: Postgres → TypeScript
 // ---------------------------------------------------------------------------
+/**
+ * The TypeScript row types below describe what a READ returns, which is what
+ * the pg driver's text parsers produce (plus the parsers TurbineClient
+ * registers), not what the type is called. A nested relation read reproduces
+ * the same value through `JSON_WIRE_COERCION_OIDS` in query/utils.ts.
+ * `src/test/types-runtime-parity.integration.test.ts` reads every type live and
+ * compares it with this table.
+ */
+const PG_INTERVAL_TS = '{ years?: number; months?: number; days?: number; hours?: number; minutes?: number; seconds?: number; milliseconds?: number }';
+const PG_POINT_TS = '{ x: number; y: number }';
+const PG_CIRCLE_TS = '{ x: number; y: number; radius: number }';
 const PG_TO_TS = {
     // Integers
     int2: 'number',
@@ -45,7 +56,9 @@ const PG_TO_TS = {
     date: 'Date',
     time: 'string',
     timetz: 'string',
-    interval: 'string',
+    // The driver parses an interval into an object (postgres-interval). Zero
+    // fields are absent, so every field is optional.
+    interval: PG_INTERVAL_TS,
     // JSON
     json: 'unknown',
     jsonb: 'unknown',
@@ -55,17 +68,34 @@ const PG_TO_TS = {
     inet: 'string',
     cidr: 'string',
     macaddr: 'string',
-    // Geometric
-    point: 'string',
+    macaddr8: 'string',
+    // Geometric: the driver parses point and circle; the others stay text.
+    point: PG_POINT_TS,
     line: 'string',
     lseg: 'string',
     box: 'string',
     path: 'string',
     polygon: 'string',
-    circle: 'string',
+    circle: PG_CIRCLE_TS,
+    // Bit strings come back as their text form ('1010').
+    bit: 'string',
+    varbit: 'string',
     // TSVector
     tsvector: 'string',
     tsquery: 'string',
+    // Ranges and multiranges come back as their text form ('[1,5)').
+    int4range: 'string',
+    int8range: 'string',
+    numrange: 'string',
+    tsrange: 'string',
+    tstzrange: 'string',
+    daterange: 'string',
+    int4multirange: 'string',
+    int8multirange: 'string',
+    nummultirange: 'string',
+    tsmultirange: 'string',
+    tstzmultirange: 'string',
+    datemultirange: 'string',
     // pgvector, embeddings. Mapped to `number[]` for DX (the natural shape an app
     // passes when inserting / comparing embeddings). NOTE: like `numeric` above,
     // there is a runtime caveat, pg has no built-in parser for the `vector` type,
@@ -77,6 +107,35 @@ const PG_TO_TS = {
     // param, so writing/comparing is unaffected by the read-side caveat.
     vector: 'number[]',
 };
+/**
+ * Array types whose element type is NOT the scalar's row type. The driver's
+ * `bigint[]` parser returns every element as a string (the scalar int8 parser
+ * TurbineClient registers does not apply to arrays), so `bigint[]` reads as
+ * `string[]` while `bigint` reads as `number`. The driver has no `circle[]`
+ * parser, so its elements stay text (`'<(1,2),3>'`) where a scalar circle is an
+ * object.
+ */
+const PG_ARRAY_TO_TS = {
+    _int8: 'string[]',
+    _circle: 'string[]',
+};
+/**
+ * Types whose WRITE input differs from the row type. Each entry is what the
+ * write path accepts, checked live:
+ *   - int8: a `number`, a decimal string (what a large value reads back as) or
+ *     a `bigint`.
+ *   - numeric: the exact string, or a `number`.
+ *   - interval / point / circle: the text form. The parsed object a read
+ *     returns is not accepted for point and circle, and a plain object is read
+ *     as an update operator, so the object form is not part of the input type.
+ */
+const PG_TO_TS_INPUT = {
+    int8: 'number | string | bigint',
+    numeric: 'string | number',
+    interval: 'string',
+    point: 'string',
+    circle: 'string',
+};
 const DATE_TYPES = new Set(['timestamptz', 'timestamp', 'date']);
 /**
  * Postgres type → the array cast `createMany`'s `UNNEST(ARRAY[...]::<type>)`
@@ -154,21 +213,53 @@ const PG_TO_ARRAY = {
     // pgvector
     vector: 'vector[]',
 };
-/** Map a Postgres type to its TypeScript equivalent */
+/** Map a Postgres type to the TypeScript type a read returns for it. */
 export function pgTypeToTs(pgType, nullable) {
-    // Array types: udt_name starts with '_'
+    let tsType;
+    if (Object.hasOwn(PG_ARRAY_TO_TS, pgType)) {
+        tsType = PG_ARRAY_TO_TS[pgType];
+    }
+    else if (pgType.startsWith('_')) {
+        // Array types: udt_name starts with '_'
+        tsType = arrayOf(pgTypeToTs(pgType.slice(1), false));
+    }
+    else {
+        tsType = Object.hasOwn(PG_TO_TS, pgType) ? PG_TO_TS[pgType] : 'unknown';
+    }
+    return nullable ? `${tsType} | null` : tsType;
+}
+/**
+ * Map a Postgres type to the TypeScript type the write path accepts for it
+ * (the generated `*Create` / `*Update` field types). Wider than
+ * {@link pgTypeToTs} where the runtime takes more than one spelling, narrower
+ * where the parsed read value cannot be written back (see `PG_TO_TS_INPUT`).
+ */
+export function pgTypeToTsInput(pgType, nullable) {
+    let tsType;
     if (pgType.startsWith('_')) {
-        const elementType = pgTypeToTs(pgType.slice(1), false);
-        const tsType = `${elementType}[]`;
-        return nullable ? `${tsType} | null` : tsType;
+        const element = pgType.slice(1);
+        tsType = Object.hasOwn(PG_TO_TS_INPUT, element) ? arrayOf(PG_TO_TS_INPUT[element]) : pgTypeToTs(pgType, false);
+    }
+    else {
+        tsType = Object.hasOwn(PG_TO_TS_INPUT, pgType) ? PG_TO_TS_INPUT[pgType] : pgTypeToTs(pgType, false);
     }
-    const tsType = PG_TO_TS[pgType] ?? 'unknown';
     return nullable ? `${tsType} | null` : tsType;
 }
+/** `T[]`, parenthesized when `T` is a union. */
+function arrayOf(element) {
+    return element.includes('|') ? `(${element})[]` : `${element}[]`;
+}
 /** Check if a Postgres type is a date/timestamp that needs Date parsing */
 export function isDateType(pgType) {
     return DATE_TYPES.has(pgType);
 }
+/**
+ * A precision suffix with the whitespace around it: `(6)` in `time(6)` or
+ * `time (6) with time zone`. Every quantifier is bounded, because a leading
+ * `\s*` retried from each position of a long whitespace run is quadratic in
+ * the type name's length; no real type name comes near the bounds.
+ */
+const TYPE_PRECISION = /\s{0,32}\(\s{0,32}\d{1,9}\s{0,32}\)\s{0,32}/;
 /**
  * Classify a column type as a TIME-OF-DAY type (`time` / `timetz`), or `null`
  * for anything else.
@@ -194,7 +285,7 @@ export function timeOfDayKind(dbType) {
         .toLowerCase()
         // Precision can sit at the end (`time(6)`) or mid-spelling
         // (`time(6) with time zone`), so strip it wherever it appears.
-        .replace(/\s*\(\s*\d+\s*\)\s*/, ' ')
+        .replace(TYPE_PRECISION, ' ')
         .trim();
     if (t === 'time' || t === 'time without time zone')
         return 'time';
@@ -229,7 +320,7 @@ export function localDateTimeKind(dbType) {
         .toLowerCase()
         // Precision can sit at the end (`timestamp(3)`) or mid-spelling
         // (`timestamp(3) without time zone`), so strip it wherever it appears.
-        .replace(/\s*\(\s*\d+\s*\)\s*/, ' ')
+        .replace(TYPE_PRECISION, ' ')
         .trim();
     if (t === 'date')
         return 'date';
@@ -239,13 +330,18 @@ export function localDateTimeKind(dbType) {
 }
 /** Get the Postgres array cast type for UNNEST batch inserts */
 export function pgArrayType(pgType) {
-    return PG_TO_ARRAY[pgType] ?? 'text[]';
+    return Object.hasOwn(PG_TO_ARRAY, pgType) ? PG_TO_ARRAY[pgType] : 'text[]';
 }
 // ---------------------------------------------------------------------------
 // Name conversion utilities
 // ---------------------------------------------------------------------------
 /** snake_case → camelCase */
 export function snakeToCamel(s) {
+    // The pattern needs an underscore, so a name without one is returned as-is
+    // without running the regex. Hot: every where/orderBy key goes through
+    // resolveRelation, which calls this for each non-relation key.
+    if (s.indexOf('_') === -1)
+        return s;
     return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
 /** camelCase → snake_case */

package/dist/sql-placeholders.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where the bind placeholders are in a statement, read with the lexical rules
+ * of the engine that will run it.
+ *
+ * The SQLite, MySQL and SQL Server shims rewrite placeholders before handing a
+ * statement to their driver: a `$n` written in raw SQL becomes the engine's own
+ * spelling, and MySQL expands an `in` list into one placeholder per element. A
+ * rewrite that lands inside a string literal, a quoted identifier or a comment
+ * changes what the statement means, so the scan has to agree with the ENGINE
+ * about which characters are code. That is why this is not the migration
+ * tokenizer in `cli/sql-statements.ts`: that one copies PostgreSQL's lexer
+ * (dollar quoting, `E''` strings, nested comments) and knows nothing of
+ * backtick or bracket identifiers, `#` comments or MySQL's backslash escapes,
+ * each of which would put a rewrite inside quoted text here.
+ *
+ * Where a reading is ambiguous the scan treats more text as quoted, never less:
+ * a placeholder it fails to see reaches the driver unrewritten and fails
+ * loudly, while one it invents inside a literal silently changes stored data.
+ * MySQL's backslash escapes are the case in point. A pool Turbine builds turns
+ * them off (`NO_BACKSLASH_ESCAPES`), an injected pool may not, and treating
+ * `\'` as an escape is the reading that can only hide a placeholder.
+ *
+ * Zero imports: every engine entry shares it.
+ */
+/** Which engine's lexical rules to apply. */
+export type PlaceholderSyntax = 'mysql' | 'sqlite' | 'mssql';
+/** One placeholder found in code (never inside a literal, a quoted identifier or a comment). */
+export interface PlaceholderToken {
+    /** `$n` (the portable positional spelling), a named `:name` (MySQL only), or a bare `?`. */
+    readonly kind: 'positional' | 'named' | 'question';
+    /** Offset of the first character (`$` or `:`). */
+    readonly start: number;
+    /** Offset just past the last character. */
+    readonly end: number;
+    /** The digits of a `$n`, the name of a `:name`, or `?`. */
+    readonly name: string;
+}
+/**
+ * Every placeholder in `sql` that the engine would read as code, in order.
+ *
+ * `$n` is reported only where the engine would see a token of its own: not
+ * when the `$` continues a word (`price$1`), and not when the digits run on
+ * into one (`$1abc`, which MySQL reads as an identifier).
+ */
+export declare function scanPlaceholders(sql: string, syntax: PlaceholderSyntax): PlaceholderToken[];
+/**
+ * Rewrite every `$n` in `sql` to the engine's spelling of value `n`, checked
+ * against the number of values the statement was given. Returns `sql` itself
+ * when it holds no `$n`. A statement given no values is never rewritten: on
+ * MySQL `$1` is a legal identifier, and with nothing to bind there is nothing
+ * a placeholder could mean.
+ *
+ * `refuse` throws the caller's error for a `$n` that names no value, and for a
+ * bare `?`: these shims bind values by name, so a `?` could never receive one.
+ */
+export declare function rewritePositionalPlaceholders(sql: string, syntax: PlaceholderSyntax, valueCount: number, spell: (index: number) => string, refuse: (message: string) => never): string;

package/dist/sql-placeholders.js

@@ -0,0 +1,200 @@
+/**
+ * Where the bind placeholders are in a statement, read with the lexical rules
+ * of the engine that will run it.
+ *
+ * The SQLite, MySQL and SQL Server shims rewrite placeholders before handing a
+ * statement to their driver: a `$n` written in raw SQL becomes the engine's own
+ * spelling, and MySQL expands an `in` list into one placeholder per element. A
+ * rewrite that lands inside a string literal, a quoted identifier or a comment
+ * changes what the statement means, so the scan has to agree with the ENGINE
+ * about which characters are code. That is why this is not the migration
+ * tokenizer in `cli/sql-statements.ts`: that one copies PostgreSQL's lexer
+ * (dollar quoting, `E''` strings, nested comments) and knows nothing of
+ * backtick or bracket identifiers, `#` comments or MySQL's backslash escapes,
+ * each of which would put a rewrite inside quoted text here.
+ *
+ * Where a reading is ambiguous the scan treats more text as quoted, never less:
+ * a placeholder it fails to see reaches the driver unrewritten and fails
+ * loudly, while one it invents inside a literal silently changes stored data.
+ * MySQL's backslash escapes are the case in point. A pool Turbine builds turns
+ * them off (`NO_BACKSLASH_ESCAPES`), an injected pool may not, and treating
+ * `\'` as an escape is the reading that can only hide a placeholder.
+ *
+ * Zero imports: every engine entry shares it.
+ */
+const DIGIT = /[0-9]/;
+/** Characters that continue an unquoted identifier or number on every engine here. */
+const WORD = /[A-Za-z0-9_$\u0080-￿]/;
+/** SQL Server also continues an identifier with `@` and `#` (`@p1`, `#temp`). */
+const MSSQL_WORD = /[A-Za-z0-9_$@#\u0080-￿]/;
+/** mysql2's named placeholder: `:` then digits, or a letter and word characters. */
+const MYSQL_NAMED = /^:([0-9]+|[A-Za-z][A-Za-z0-9_]*)/;
+/**
+ * Offset just past a quoted run that opened at `i`. `close` doubled (`''`,
+ * `""`, `` ` ` ``, and `]]` on SQL Server) is an escaped quote, not the end;
+ * with `backslash`, a backslash escapes the next character too.
+ */
+function skipQuoted(sql, i, close, doubled, backslash) {
+    const n = sql.length;
+    let j = i + 1;
+    while (j < n) {
+        const ch = sql[j];
+        if (backslash && ch === '\\') {
+            j += 2;
+            continue;
+        }
+        if (ch === close) {
+            if (doubled && sql[j + 1] === close) {
+                j += 2;
+                continue;
+            }
+            return j + 1;
+        }
+        j++;
+    }
+    return n;
+}
+/** Offset just past a block comment opening at `i`. SQL Server nests them; MySQL and SQLite do not. */
+function skipBlockComment(sql, i, nests) {
+    const n = sql.length;
+    let depth = 1;
+    let j = i + 2;
+    while (j < n) {
+        if (nests && sql[j] === '/' && sql[j + 1] === '*') {
+            depth++;
+            j += 2;
+        }
+        else if (sql[j] === '*' && sql[j + 1] === '/') {
+            j += 2;
+            if (--depth === 0)
+                return j;
+        }
+        else {
+            j++;
+        }
+    }
+    return n;
+}
+/** True when `--` at `i` opens a comment. MySQL needs whitespace (or the end) after the dashes. */
+function opensLineComment(sql, i, syntax) {
+    if (sql[i] !== '-' || sql[i + 1] !== '-')
+        return false;
+    if (syntax !== 'mysql')
+        return true;
+    const after = sql[i + 2];
+    return after === undefined || /\s/.test(after) || after.charCodeAt(0) < 32;
+}
+/**
+ * Every placeholder in `sql` that the engine would read as code, in order.
+ *
+ * `$n` is reported only where the engine would see a token of its own: not
+ * when the `$` continues a word (`price$1`), and not when the digits run on
+ * into one (`$1abc`, which MySQL reads as an identifier).
+ */
+export function scanPlaceholders(sql, syntax) {
+    const out = [];
+    const n = sql.length;
+    const word = syntax === 'mssql' ? MSSQL_WORD : WORD;
+    const backslash = syntax === 'mysql';
+    let i = 0;
+    while (i < n) {
+        const ch = sql[i];
+        if (opensLineComment(sql, i, syntax) || (syntax === 'mysql' && ch === '#')) {
+            while (i < n && sql[i] !== '\n')
+                i++;
+            continue;
+        }
+        if (ch === '/' && sql[i + 1] === '*') {
+            i = skipBlockComment(sql, i, syntax === 'mssql');
+            continue;
+        }
+        if (ch === "'") {
+            i = skipQuoted(sql, i, "'", true, backslash);
+            continue;
+        }
+        if (ch === '"') {
+            // A string on MySQL, an identifier on SQLite and SQL Server: skipped either way.
+            i = skipQuoted(sql, i, '"', true, backslash);
+            continue;
+        }
+        if (ch === '`' && syntax !== 'mssql') {
+            i = skipQuoted(sql, i, '`', true, false);
+            continue;
+        }
+        if (ch === '[' && syntax !== 'mysql') {
+            // SQLite ends a bracket identifier at the first `]`; SQL Server escapes it as `]]`.
+            i = skipQuoted(sql, i, ']', syntax === 'mssql', false);
+            continue;
+        }
+        if (ch === '$' && DIGIT.test(sql[i + 1] ?? '')) {
+            let j = i + 1;
+            while (j < n && DIGIT.test(sql[j]))
+                j++;
+            if (j < n && word.test(sql[j])) {
+                // `$1abc`: one word to the engine, not a placeholder.
+                while (j < n && word.test(sql[j]))
+                    j++;
+                i = j;
+                continue;
+            }
+            out.push({ kind: 'positional', start: i, end: j, name: sql.slice(i + 1, j) });
+            i = j;
+            continue;
+        }
+        if (ch === '?') {
+            out.push({ kind: 'question', start: i, end: i + 1, name: '?' });
+            i++;
+            continue;
+        }
+        if (ch === ':' && syntax === 'mysql') {
+            const m = MYSQL_NAMED.exec(sql.slice(i, i + 64));
+            if (m) {
+                out.push({ kind: 'named', start: i, end: i + m[0].length, name: m[1] });
+                i += m[0].length;
+                continue;
+            }
+        }
+        if (word.test(ch)) {
+            // A whole identifier, keyword or number, so a `$` or `:` inside it is never a placeholder.
+            let j = i + 1;
+            while (j < n && word.test(sql[j]))
+                j++;
+            i = j;
+            continue;
+        }
+        i++;
+    }
+    return out;
+}
+/**
+ * Rewrite every `$n` in `sql` to the engine's spelling of value `n`, checked
+ * against the number of values the statement was given. Returns `sql` itself
+ * when it holds no `$n`. A statement given no values is never rewritten: on
+ * MySQL `$1` is a legal identifier, and with nothing to bind there is nothing
+ * a placeholder could mean.
+ *
+ * `refuse` throws the caller's error for a `$n` that names no value, and for a
+ * bare `?`: these shims bind values by name, so a `?` could never receive one.
+ */
+export function rewritePositionalPlaceholders(sql, syntax, valueCount, spell, refuse) {
+    if (valueCount === 0 || !/\$[0-9]|\?/.test(sql))
+        return sql;
+    const tokens = scanPlaceholders(sql, syntax).filter((t) => t.kind !== 'named');
+    if (tokens.length === 0)
+        return sql;
+    let out = '';
+    let last = 0;
+    for (const t of tokens) {
+        if (t.kind === 'question') {
+            refuse('A `?` placeholder cannot be bound here: write the values as $1, $2, and so on.');
+        }
+        const index = Number(t.name);
+        if (!Number.isSafeInteger(index) || index < 1 || index > valueCount) {
+            refuse(`$${t.name} names no value: the statement was given ${valueCount} ` +
+                `value${valueCount === 1 ? '' : 's'}, numbered $1 to $${valueCount}. Pass one value per placeholder.`);
+        }
+        out += sql.slice(last, t.start) + spell(index);
+        last = t.end;
+    }
+    return out + sql.slice(last);
+}

package/dist/sqlite.d.ts

@@ -19,18 +19,24 @@
  * - `RETURNING` + `ON CONFLICT … DO UPDATE` (SQLite ≥ 3.35) → create / upsert /
  *   update / delete return real rows in a single statement (`resultStrategy =
  *   'returning'`, same as Postgres).
- * - **Single-writer:** one connection / one write transaction at a time;
- *   concurrent writers get `SQLITE_BUSY` (treated as retryable). `journal_mode =
- *   WAL` is enabled for file databases to allow concurrent readers.
+ * - **Single-writer:** one connection / one transaction at a time. On one
+ *   client, statements from other callers wait (FIFO, up to `busyTimeoutMs`)
+ *   while a transaction is open instead of running inside it; another
+ *   process's writer gets `SQLITE_BUSY`. Both surface as the retryable
+ *   `SerializationFailureError`. `journal_mode = WAL` is enabled for file
+ *   databases to allow concurrent readers across connections.
  * - **Unsupported (throw `UnsupportedFeatureError`):** pgvector distance ops,
  *   LISTEN/NOTIFY (`$listen` / `$notify`), RLS `sessionContext`. Advisory-lock
  *   migration locking is unavailable, SQLite is single-writer, so migrations
  *   serialize naturally.
- * - **Type affinity caveats:** SQLite has no native `BOOLEAN` (0/1 integers) or
- *   `DATE` (TEXT/INTEGER). Booleans bind as 1/0; `Date` values bind as ISO-8601
- *   text; columns declared `TIMESTAMP`/`DATETIME`/`DATE` are coerced back to
- *   `Date`. Integers wider than `Number.MAX_SAFE_INTEGER` come back as strings
- *   (the same safe-int policy Turbine uses for Postgres `int8`).
+ * - **Type affinity caveats:** SQLite has no native `BOOLEAN` (0/1 integers),
+ *   `JSON` (text) or `DATE` (TEXT/INTEGER). Booleans bind as 1/0; `Date` values
+ *   bind as ISO-8601 text; an integral JS number binds as INTEGER. A column the
+ *   schema declares boolean or json/jsonb reads back as a boolean or a parsed
+ *   value on every path; date/time columns are coerced back to `Date`.
+ *   Integers wider than `Number.MAX_SAFE_INTEGER` come back as strings (the
+ *   same safe-int policy Turbine uses for Postgres `int8`). `numeric` has no
+ *   exact storage: it reads back as a JS number.
  * - **Case-insensitive matching** uses `COLLATE NOCASE`, which is **ASCII-only**
  *   (no Unicode case folding).
  *
@@ -68,7 +74,7 @@
  *
  * const db = turbineSqlite(':memory:', schemaDefToMetadata(schema));
  * for (const stmt of schemaToSQL(schema, { dialect: sqliteDialect })) {
- *   await db.raw([stmt] as never);
+ *   await db.rawUnsafe(stmt);
  * }
  *
  * // `db.table(...)`, not `db.users`: the typed property accessors are emitted
@@ -88,27 +94,75 @@ type QueryArg = string | {
     text: string;
     values?: unknown[];
 };
+/** Options for {@link SqlitePool}. */
+export interface SqlitePoolOptions {
+    /**
+     * How long, in ms, a statement waits for a transaction another caller has
+     * open on this handle before failing with a retryable
+     * `SerializationFailureError`. Default: 5000, the same bound as
+     * `PRAGMA busy_timeout`.
+     */
+    busyTimeoutMs?: number;
+    /**
+     * The client's schema. A column it declares boolean or json/jsonb is read
+     * back as a boolean or a parsed value, whatever its SQLite declared type.
+     * `turbineSqlite` passes the schema it was given.
+     */
+    schema?: SchemaMetadata;
+}
 /**
  * A `PgCompatPool` backed by a single `node:sqlite` `DatabaseSync` connection.
  * SQLite is single-connection by nature (a `:memory:` database is per-handle),
- * so `connect()` hands back a client over the **same** handle, transactions
- * (`BEGIN`/`COMMIT`/`ROLLBACK`, `SAVEPOINT` nesting) just run on it. Queries are
- * serialized; this is the documented single-writer model.
+ * so `connect()` hands back a client over the **same** handle.
+ *
+ * One handle carries one transaction, so the pool decides who may use it. A
+ * caller whose statement opens a transaction OWNS the handle until that
+ * transaction ends; every other caller's statements, plain queries included,
+ * wait their turn in FIFO order (bounded by `busyTimeoutMs`) instead of running
+ * inside it. Without that, a write issued outside an open transaction joined
+ * it, reported success, and was rolled back with it, and reads saw its
+ * uncommitted rows. A checkout that does not open a transaction (a stream, a
+ * connectivity check) holds nothing, so other callers keep running beside it.
  */
 export declare class SqlitePool implements PgCompatPool {
     /** The underlying `node:sqlite` handle, exposed as an escape hatch (seed/DDL). */
     readonly db: DatabaseSync;
     private closed;
     /**
-     * `sql -> declared-boolean result columns` (or `null` for none). Bounded like
+     * `sql -> result columns to decode` (or `null` for none). Bounded like
      * the query builder's SQL-template cache, since a caller can generate
      * unbounded distinct statements (raw SQL, an IN-list that inlines).
      */
-    private readonly booleanCache;
-    constructor(db: DatabaseSync);
+    private readonly decoderCache;
+    /** Schema columns whose stored form is not their declared JS type (see {@link declaredDecoders}). */
+    private readonly declared;
+    private readonly busyTimeoutMs;
+    /** Who may run statements on the handle right now; `null` when nobody holds it. */
+    private owner;
+    private readonly waiters;
+    /** The owner for statements sent through `pool.query()` rather than a checkout. */
+    private readonly poolOwner;
+    /** Transaction state when the driver cannot report it (`isTransaction` arrived in Node 22.16). */
+    private trackedTransaction;
+    constructor(db: DatabaseSync, options?: SqlitePoolOptions);
     query(text: QueryArg, values?: unknown[]): Promise<any>;
     connect(): Promise<PgCompatPoolClient>;
     end(): Promise<void>;
+    /** Is the handle inside a transaction right now? */
+    private inTransaction;
+    /** Run one statement for `owner`, waiting first if another caller's transaction holds the handle. */
+    private runAs;
+    /** True when the current async context is the callback of the transaction that owns the handle. */
+    private calledFromOwnersCallback;
+    private waitForHandle;
+    /** Give the handle to the next waiter, which runs its statement as soon as it resumes. */
+    private handOff;
+    /**
+     * A checkout ended. If it still holds an open transaction (a timed-out or
+     * abandoned callback), roll it back first, so the next caller does not
+     * start inside it.
+     */
+    private releaseOwner;
 }
 /**
  * Map a SQLite declared column type (type affinity) to a TypeScript type.
@@ -131,10 +185,7 @@ export declare const sqliteDialect: Dialect;
  * Exposed directly so callers (and tests) can introspect an in-process
  * `:memory:` database without round-tripping through a file path.
  */
-export declare function introspectSqliteDatabase(db: DatabaseSync, options?: {
-    include?: string[];
-    exclude?: string[];
-}): {
+export declare function introspectSqliteDatabase(db: DatabaseSync, options?: Pick<IntrospectOptions, 'include' | 'exclude' | 'logger'>): {
     tables: Record<string, TableMetadata>;
     enums: {};
 };
@@ -159,7 +210,11 @@ export interface TurbineSqliteOptions extends EngineClientConfig {
      * Ignored for `':memory:'`. Default: `true`.
      */
     wal?: boolean;
-    /** `PRAGMA busy_timeout` in ms, how long a writer waits on `SQLITE_BUSY`. Default: 5000. */
+    /**
+     * How long, in ms, a statement waits for the database: `PRAGMA busy_timeout`
+     * for another process's lock, and the wait behind a transaction another
+     * caller has open on this client. Default: 5000.
+     */
     busyTimeoutMs?: number;
     /** Enable `PRAGMA foreign_keys` enforcement. Default: `true`. */
     foreignKeys?: boolean;