@rudderjs/database 1.1.0 → 1.2.1

package/dist/native/dialect.d.ts

@@ -0,0 +1,255 @@
+import type { ColumnDefinition } from './schema/column.js';
+import type { LockOptions } from '@rudderjs/contracts';
+/**
+ * The date/time component a `whereDate`/`whereTime`/`whereDay`/`whereMonth`/
+ * `whereYear` predicate extracts from a column before comparing. `date` and
+ * `time` compare as strings (`'YYYY-MM-DD'` / `'HH:MM:SS'`); `day`/`month`/
+ * `year` compare as integers.
+ */
+export type DatePart = 'date' | 'time' | 'day' | 'month' | 'year';
+/**
+ * One step of a JSON arrow path (`meta->prefs->lang`, `meta->items->0`): a
+ * validated object key, or a number for an array index (`$[0]` / pg `->0`).
+ */
+export type JsonPathSegment = string | number;
+/**
+ * The JS type of a JSON comparison value, hinting the dialect's extraction
+ * shape: pg casts its text extraction (`::numeric` / `::boolean`) so operators
+ * compare typed values; mysql compares booleans against the raw
+ * `JSON_EXTRACT` (no `JSON_UNQUOTE`); sqlite ignores the hint (`json_extract`
+ * already returns typed values).
+ */
+export type JsonValueKind = 'text' | 'number' | 'boolean';
+/**
+ * One JSON path write inside an UPDATE payload (`'meta->prefs->lang': 'en'`
+ * → `{ segments: ['prefs', 'lang'], value: 'en' }`), consumed by
+ * {@link Dialect.jsonSet}. Segments are validated by {@link parseJsonPath}.
+ */
+export interface JsonPathWrite {
+    segments: readonly JsonPathSegment[];
+    value: unknown;
+}
+/**
+ * A SQL dialect: the knobs that change the emitted SQL text between databases.
+ * `SqliteDialect` is the first concrete impl; `PgDialect` / `MysqlDialect`
+ * plug in here later.
+ */
+export interface Dialect {
+    /** Short dialect tag — drives any capability branching in the compiler. */
+    readonly name: 'sqlite' | 'pg' | 'mysql';
+    /**
+     * Quote a single identifier (table or column). The identifier is validated
+     * first (letters/digits/underscores only, not starting with a digit) and
+     * then wrapped in the dialect's quote character so reserved words and casing
+     * survive. Dotted identifiers (`table.column`) are quoted segment-by-segment.
+     *
+     * Identifiers can't be bound as parameters, so this is the security boundary
+     * for the only user-influenced text that reaches the SQL string.
+     */
+    quoteId(identifier: string): string;
+    /**
+     * Positional placeholder for the value at zero-based `index`. SQLite/MySQL
+     * use a literal `?` (index ignored); Postgres uses `$1`, `$2`, … (1-based).
+     */
+    placeholder(index: number): string;
+    /** Whether the dialect supports `INSERT/UPDATE/DELETE ... RETURNING`.
+     *  Unused on the read path; defined now so Phase 2 branches on the seam. */
+    readonly supportsReturning: boolean;
+    /**
+     * DDL: the SQL fragment that follows a quoted column name in `CREATE TABLE` —
+     * the dialect's storage type plus any type-bundled clause. For an
+     * auto-incrementing column the dialect returns the *complete* spec
+     * (SQLite: `INTEGER PRIMARY KEY AUTOINCREMENT`; pg: `bigserial PRIMARY KEY`),
+     * and the DDL compiler appends no further modifiers to it. For every other
+     * column it returns just the type keyword and the compiler appends the shared
+     * `NOT NULL` / `DEFAULT` / `PRIMARY KEY` modifiers.
+     *
+     * This is the per-dialect half of the schema builder (parent plan Part 2's
+     * column-type table); pg/mysql implement the same method.
+     */
+    columnTypeSql(column: ColumnDefinition): string;
+    /**
+     * Render a `boolean` column DEFAULT as a SQL literal. DDL can't bind values,
+     * so the DDL compiler asks the dialect how to spell a boolean default: SQLite
+     * and MySQL store booleans as `0`/`1` integers, but Postgres has a real
+     * `boolean` type that rejects `DEFAULT 1` and wants `DEFAULT true`/`false`.
+     * This is the only spot in `defaultLiteral` that diverges per dialect.
+     */
+    booleanLiteral(value: boolean): string;
+    /**
+     * The conflict-resolution suffix appended to an `INSERT … VALUES …` for an
+     * upsert (before any `RETURNING`). Diverges sharply per dialect:
+     *
+     * - SQLite / Postgres: `ON CONFLICT (<uniqueBy>) DO UPDATE SET col = excluded.col, …`
+     *   (or `… DO NOTHING` when `update` is empty). The conflict target is the
+     *   `uniqueBy` columns; a matching unique index/constraint must exist.
+     * - MySQL: `ON DUPLICATE KEY UPDATE col = VALUES(col), …`. MySQL keys off any
+     *   existing unique index, so `uniqueBy` is ignored here (the caller still
+     *   needs the unique constraint to exist). An empty `update` degrades to a
+     *   no-op assignment on the first `uniqueBy` column so the row is left intact.
+     *
+     * `uniqueBy` and `update` are already-resolved, validated column-name arrays
+     * (the Model layer computes the default `update` set). Values are never
+     * interpolated here — only identifiers, quoted via {@link quoteId}.
+     */
+    upsertClause(uniqueBy: readonly string[], update: readonly string[]): string;
+    /**
+     * The SQL expression extracting a date/time component from a column — the
+     * per-dialect half of `whereDate`/`whereTime`/`whereDay`/`whereMonth`/
+     * `whereYear`. `column` arrives ALREADY QUOTED (the compiler runs it through
+     * {@link quoteId} first), so the dialect only splices it into its extraction
+     * function. The result must compare cleanly against a bound value:
+     * `'YYYY-MM-DD'` text for `date`, `'HH:MM:SS'` text for `time`, and an
+     * INTEGER for `day`/`month`/`year` (so a bound `5` matches May — dialects
+     * whose extractor yields text, like SQLite's `strftime`, must CAST).
+     */
+    dateExtract(part: DatePart, column: string): string;
+    /**
+     * The SQL expression extracting a JSON path from a column for a scalar
+     * comparison — the per-dialect half of `where('meta->prefs->lang', …)`.
+     * `column` arrives ALREADY QUOTED (the compiler runs it through
+     * {@link quoteId} first); `segments` are validated by {@link parseJsonPath}
+     * (quote/backslash/control characters rejected), so the dialect only splices
+     * them into its path syntax. `valueKind` hints the comparison value's JS
+     * type — see {@link JsonValueKind} for what each dialect does with it.
+     */
+    jsonExtract(column: string, segments: readonly JsonPathSegment[], valueKind: JsonValueKind): string;
+    /**
+     * The `IS [NOT] NULL` predicate for a JSON path — `whereNull('meta->x')` /
+     * `where('meta->x', null)`. Laravel semantics: a MISSING key and an explicit
+     * json `null` BOTH count as null (`whereNotNull` matches only an actual
+     * value). sqlite and pg get this for free — their extractions surface both
+     * as SQL NULL — but mysql's `JSON_EXTRACT` returns a JSON `null` LITERAL
+     * (not SQL NULL) for an explicit null, and `JSON_UNQUOTE` turns it into the
+     * STRING `'null'`, so a plain `extract IS NULL` matched missing keys only.
+     * mysql emits Laravel's grammar shape instead:
+     * `(extract IS NULL OR JSON_TYPE(extract) = 'NULL')`.
+     */
+    jsonNullComparison(column: string, segments: readonly JsonPathSegment[], negated: boolean): string;
+    /**
+     * Normalize a boolean JSON comparison value for binding, paired with
+     * {@link jsonExtract}'s `'boolean'` shape: sqlite `1`/`0` (json_extract
+     * yields integers for json booleans), mysql `'true'`/`'false'` (compared
+     * against the raw JSON_EXTRACT — MySQL coerces the string via
+     * `CAST(… AS JSON)`), pg the boolean itself (the extraction is `::boolean`-cast).
+     */
+    jsonBoolean(value: boolean): unknown;
+    /**
+     * The containment predicate for `whereJsonContains(column, value)`. `column`
+     * arrives quoted; `segments` (possibly empty — a whole-column check)
+     * validated. `value` may be a scalar or an array (array = every element
+     * contained, matching pg `@>` / mysql `JSON_CONTAINS`). Values are never
+     * interpolated — the dialect binds through the `bind` callback (which
+     * returns the placeholder for the value it's handed), keeping positional
+     * order correct across the statement.
+     *
+     * - pg: `(col->'a')::jsonb @> $n::jsonb` (value bound as JSON text).
+     * - mysql: `JSON_CONTAINS(col, ?, '$."a"')` (value bound as JSON text).
+     * - sqlite: emulated via `EXISTS (SELECT 1 FROM json_each(col, '$."a"')
+     *   WHERE json_each.value = ?)` per element (AND-joined for arrays) —
+     *   scalar elements only; object values throw.
+     *
+     * The compiler wraps the returned expression in `NOT (…)` for
+     * `whereJsonDoesntContain`, so multi-part emulations must self-parenthesize.
+     */
+    jsonContains(column: string, segments: readonly JsonPathSegment[], value: unknown, bind: (v: unknown) => string): string;
+    /**
+     * The array-length expression for `whereJsonLength(column, op, n)` — the
+     * comparison value binds in the compiler. sqlite `json_array_length(col,
+     * '$."a"')`, pg `jsonb_array_length((col->'a')::jsonb)`, mysql
+     * `JSON_LENGTH(col, '$."a"')`. `segments` may be empty (whole column).
+     */
+    jsonLength(column: string, segments: readonly JsonPathSegment[]): string;
+    /**
+     * The SET right-hand side writing one or more JSON paths into a single
+     * column — the per-dialect half of `update(id, { 'meta->prefs->lang': … })`.
+     * `column` arrives ALREADY QUOTED; `writes` carry segments validated by
+     * {@link parseJsonPath}. Values are never interpolated — each binds as JSON
+     * text (`JSON.stringify`) through the `bind` callback in write order, so
+     * positional bindings stay in SQL-text order, and the JSON-text shape keeps
+     * every value type (string/number/boolean/null/array/object) round-tripping
+     * identically across dialects:
+     *
+     * - sqlite: `json_set(col, '$."a"', json(?), '$."b"', json(?))`
+     * - mysql:  `JSON_SET(col, '$."a"', CAST(? AS JSON), …)`
+     * - pg:     nested `jsonb_set((col)::jsonb, ARRAY['a'], $n::jsonb)` (one
+     *   wrap per write — jsonb_set takes a single path).
+     *
+     * Like Laravel's grammars, missing INTERMEDIATE keys are not created (only
+     * the leaf key is); a NULL column stays NULL on pg (`jsonb_set(NULL, …)` is
+     * NULL) — write the whole column to initialize it.
+     */
+    jsonSet(column: string, writes: readonly JsonPathWrite[], bind: (v: unknown) => string): string;
+    /**
+     * The pessimistic-locking suffix appended to a `SELECT` (after ORDER BY /
+     * LIMIT), or `''` when the dialect has no row-level locking. Powers
+     * `QueryBuilder.lockForUpdate()` / `sharedLock()`:
+     *
+     * - Postgres / MySQL 8: `' FOR UPDATE'` / `' FOR SHARE'`, with `opts`
+     *   appending the wait behavior — `' SKIP LOCKED'` (skip already-locked
+     *   rows) or `' NOWAIT'` (error instead of blocking). The QueryBuilder
+     *   validates mutual exclusivity before the options reach here.
+     * - SQLite: `''` — there is no per-row lock; a write transaction already
+     *   serializes writers, so the reservation is safe without a suffix. The
+     *   options are ignored along with the lock itself.
+     *
+     * Always prefixed with a leading space so the compiler can concatenate it
+     * unconditionally.
+     */
+    lockSql(mode: 'update' | 'shared', opts?: LockOptions): string;
+}
+/**
+ * Quote a string as a SQL literal (single-quoted, embedded `'` doubled). Used
+ * for DDL value lists that can't be bound — `enum`/`set` allowed-value lists and
+ * the `CHECK (… IN (…))` constraint on pg/sqlite. Migration-author supplied, so
+ * escaping (not an allowlist) is the right boundary, matching the column-DEFAULT
+ * literal path in the DDL compiler.
+ */
+export declare function quoteSqlString(value: string): string;
+/** Render an `enum`/`set` value list as a `(quoted, list)` for inline use. */
+export declare function quoteValueList(values: readonly string[]): string;
+/**
+ * Validate a (possibly dotted) identifier and return its segments. Throws
+ * {@link NativeIdentifierError} on anything that isn't a plain
+ * `[letter|_][letter|digit|_]*` per dot-separated segment.
+ */
+export declare function validateIdentifier(identifier: string): string[];
+/**
+ * Split a `column->path->to->key` arrow column into the base column and its
+ * validated JSON path segments. The column half goes through the normal
+ * {@link validateIdentifier} gate at quote time; each path segment is checked
+ * against {@link JSON_SEGMENT_REJECT} here. All-digit segments become numeric
+ * array indexes (`meta->items->0` → `$[0]` / pg `->0`).
+ */
+export declare function parseJsonPath(path: string): {
+    column: string;
+    segments: JsonPathSegment[];
+};
+/**
+ * Render validated segments as a single-quoted SQL JSON-path literal —
+ * `'$."a"."b"[0]'`. Keys are double-quoted inside the path so spaces/dots
+ * survive; safe to inline because {@link parseJsonPath} rejected every
+ * character that could escape either quoting layer. Shared by the sqlite and
+ * mysql dialects (pg uses `->` operator chains instead).
+ */
+export declare function jsonPathLiteral(segments: readonly JsonPathSegment[]): string;
+/** SQLite dialect — `"`-quoted identifiers, `?` placeholders, RETURNING since
+ *  3.35. Also the dialect used by libsql/Turso (Phase 6). */
+export declare class SqliteDialect implements Dialect {
+    readonly name: "sqlite";
+    readonly supportsReturning = true;
+    quoteId(identifier: string): string;
+    placeholder(_index: number): string;
+    booleanLiteral(value: boolean): string;
+    dateExtract(part: DatePart, column: string): string;
+    jsonExtract(column: string, segments: readonly JsonPathSegment[], _valueKind: JsonValueKind): string;
+    jsonNullComparison(column: string, segments: readonly JsonPathSegment[], negated: boolean): string;
+    jsonBoolean(value: boolean): unknown;
+    jsonContains(column: string, segments: readonly JsonPathSegment[], value: unknown, bind: (v: unknown) => string): string;
+    jsonLength(column: string, segments: readonly JsonPathSegment[]): string;
+    jsonSet(column: string, writes: readonly JsonPathWrite[], bind: (v: unknown) => string): string;
+    lockSql(_mode: 'update' | 'shared', _opts?: LockOptions): string;
+    upsertClause(uniqueBy: readonly string[], update: readonly string[]): string;
+    columnTypeSql(column: ColumnDefinition): string;
+}
+//# sourceMappingURL=dialect.d.ts.map

package/dist/native/dialect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.d.ts","sourceRoot":"","sources":["../../src/native/dialect.ts"],"names":[],"mappings":"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"}

package/dist/native/dialect.js

@@ -0,0 +1,237 @@
+// ─── Dialect seam (per-SQL-flavor) ─────────────────────────
+//
+// The `Dialect` captures every place the SQL TEXT differs between databases:
+// identifier quoting, placeholder syntax, RETURNING support, etc. The compiler
+// builds SQL strings through this interface only, so adding Postgres / MySQL
+// later (Phases 5–6) is a new `Dialect` — not a compiler rewrite.
+//
+// This module is PURE — string building only. No `node:`, no driver, no I/O.
+import { NativeIdentifierError, NativeOrmError } from './errors.js';
+// Strict identifier allowlist. Anything outside it is rejected rather than
+// escaped — the ORM only ever feeds column/table names here, so a value with
+// quotes, spaces, or SQL meta-characters means a bug or an injection attempt.
+const SEGMENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * Quote a string as a SQL literal (single-quoted, embedded `'` doubled). Used
+ * for DDL value lists that can't be bound — `enum`/`set` allowed-value lists and
+ * the `CHECK (… IN (…))` constraint on pg/sqlite. Migration-author supplied, so
+ * escaping (not an allowlist) is the right boundary, matching the column-DEFAULT
+ * literal path in the DDL compiler.
+ */
+export function quoteSqlString(value) {
+    return `'${String(value).replace(/'/g, "''")}'`;
+}
+/** Render an `enum`/`set` value list as a `(quoted, list)` for inline use. */
+export function quoteValueList(values) {
+    return values.map(quoteSqlString).join(', ');
+}
+/**
+ * Validate a (possibly dotted) identifier and return its segments. Throws
+ * {@link NativeIdentifierError} on anything that isn't a plain
+ * `[letter|_][letter|digit|_]*` per dot-separated segment.
+ */
+export function validateIdentifier(identifier) {
+    if (typeof identifier !== 'string' || identifier.length === 0) {
+        throw new NativeIdentifierError(String(identifier));
+    }
+    const segments = identifier.split('.');
+    for (const seg of segments) {
+        if (!SEGMENT.test(seg))
+            throw new NativeIdentifierError(identifier);
+    }
+    return segments;
+}
+// JSON path segments are user-supplied strings spliced into the SQL text (as
+// quoted keys inside a path literal or pg `->'key'` operands), so they're the
+// second identifier-like security boundary after `validateIdentifier`. Unlike
+// column names they may legitimately contain spaces/dots (`$."a b"` quoting
+// handles those), so instead of an allowlist we REJECT the characters that
+// could escape the quoting: quotes, backticks, backslashes, and control chars.
+// eslint-disable-next-line no-control-regex -- control characters are exactly what we reject
+const JSON_SEGMENT_REJECT = /['"`\\\x00-\x1f]/;
+/**
+ * Split a `column->path->to->key` arrow column into the base column and its
+ * validated JSON path segments. The column half goes through the normal
+ * {@link validateIdentifier} gate at quote time; each path segment is checked
+ * against {@link JSON_SEGMENT_REJECT} here. All-digit segments become numeric
+ * array indexes (`meta->items->0` → `$[0]` / pg `->0`).
+ */
+export function parseJsonPath(path) {
+    const [column, ...rawSegments] = path.split('->');
+    if (!column || rawSegments.length === 0 || rawSegments.some(s => s.length === 0)) {
+        throw new NativeOrmError('NATIVE_JSON_PATH_INVALID', `[RudderJS ORM native] Malformed JSON path "${path}" — expected column->key[->key…] with non-empty segments.`);
+    }
+    const segments = rawSegments.map((seg) => {
+        if (JSON_SEGMENT_REJECT.test(seg)) {
+            throw new NativeOrmError('NATIVE_JSON_PATH_SEGMENT', `[RudderJS ORM native] JSON path segment ${JSON.stringify(seg)} in "${path}" contains a quote, backslash, backtick, or control character — not allowed (path segments are spliced into SQL text).`);
+        }
+        return /^\d+$/.test(seg) ? Number(seg) : seg;
+    });
+    return { column, segments };
+}
+/**
+ * Render validated segments as a single-quoted SQL JSON-path literal —
+ * `'$."a"."b"[0]'`. Keys are double-quoted inside the path so spaces/dots
+ * survive; safe to inline because {@link parseJsonPath} rejected every
+ * character that could escape either quoting layer. Shared by the sqlite and
+ * mysql dialects (pg uses `->` operator chains instead).
+ */
+export function jsonPathLiteral(segments) {
+    return `'$${segments.map(s => (typeof s === 'number' ? `[${s}]` : `."${s}"`)).join('')}'`;
+}
+/** SQLite dialect — `"`-quoted identifiers, `?` placeholders, RETURNING since
+ *  3.35. Also the dialect used by libsql/Turso (Phase 6). */
+export class SqliteDialect {
+    name = 'sqlite';
+    supportsReturning = true;
+    quoteId(identifier) {
+        const segments = validateIdentifier(identifier);
+        // Double any embedded `"` defensively; the allowlist already forbids them,
+        // so this is belt-and-suspenders for the quoting itself.
+        return segments.map(s => `"${s.replace(/"/g, '""')}"`).join('.');
+    }
+    placeholder(_index) {
+        return '?';
+    }
+    // SQLite has no boolean type; booleans round-trip as 0/1 integers, so a
+    // boolean default renders as the matching integer literal.
+    booleanLiteral(value) {
+        return value ? '1' : '0';
+    }
+    // SQLite stores dates as ISO-8601 text — `strftime` extracts components.
+    // `date`/`time` stay text ('YYYY-MM-DD' / 'HH:MM:SS'); `day`/`month`/`year`
+    // CAST to INTEGER so a bound number compares (strftime returns zero-padded
+    // text like '05', and SQLite never equates TEXT with INTEGER).
+    dateExtract(part, column) {
+        switch (part) {
+            case 'date': return `strftime('%Y-%m-%d', ${column})`;
+            case 'time': return `strftime('%H:%M:%S', ${column})`;
+            case 'day': return `CAST(strftime('%d', ${column}) AS INTEGER)`;
+            case 'month': return `CAST(strftime('%m', ${column}) AS INTEGER)`;
+            case 'year': return `CAST(strftime('%Y', ${column}) AS INTEGER)`;
+        }
+    }
+    // `json_extract` returns typed values (TEXT for strings, INTEGER/REAL for
+    // numbers, 1/0 for json booleans, NULL for json null AND missing keys), so
+    // the bound value compares directly — no cast, the valueKind hint is unused.
+    jsonExtract(column, segments, _valueKind) {
+        return `json_extract(${column}, ${jsonPathLiteral(segments)})`;
+    }
+    // json_extract already surfaces BOTH a missing key and an explicit json
+    // null as SQL NULL — the plain IS [NOT] NULL on the extraction is correct.
+    jsonNullComparison(column, segments, negated) {
+        return `${this.jsonExtract(column, segments, 'text')} IS ${negated ? 'NOT ' : ''}NULL`;
+    }
+    // json_extract yields INTEGER 1/0 for json true/false — bind the matching int.
+    jsonBoolean(value) {
+        return value ? 1 : 0;
+    }
+    // SQLite has no containment operator — emulate per element via json_each:
+    // EXISTS (SELECT 1 FROM json_each(col, path) WHERE json_each.value = ?).
+    // Array values AND one EXISTS per element (matching pg @> / mysql
+    // JSON_CONTAINS "every element contained" semantics). Scalars only — a
+    // nested object/array element has no reliable text-equality form here.
+    jsonContains(column, segments, value, bind) {
+        const target = segments.length === 0 ? column : `${column}, ${jsonPathLiteral(segments)}`;
+        const elements = Array.isArray(value) ? value : [value];
+        const parts = elements.map(v => {
+            if (v !== null && typeof v === 'object') {
+                throw new NativeOrmError('NATIVE_JSON_CONTAINS_UNSUPPORTED', '[RudderJS ORM native] whereJsonContains on SQLite supports scalar values (and arrays of scalars) only — object containment has no json_each equality form. Use whereRaw(...) for structural checks.');
+            }
+            // json null elements surface as SQL NULL in json_each.value — match on
+            // the row's declared type instead (`= NULL` never matches in SQL).
+            if (v === null)
+                return `EXISTS (SELECT 1 FROM json_each(${target}) WHERE "json_each"."type" = 'null')`;
+            const bound = typeof v === 'boolean' ? (v ? 1 : 0) : v;
+            return `EXISTS (SELECT 1 FROM json_each(${target}) WHERE "json_each"."value" = ${bind(bound)})`;
+        });
+        return parts.length === 1 ? parts[0] : `(${parts.join(' AND ')})`;
+    }
+    // json_array_length takes the path directly as its second argument.
+    jsonLength(column, segments) {
+        return segments.length === 0
+            ? `json_array_length(${column})`
+            : `json_array_length(${column}, ${jsonPathLiteral(segments)})`;
+    }
+    // json_set takes (path, value) varargs — one call covers every write on the
+    // column. `json(?)` parses the bound JSON text so all value types (string/
+    // number/boolean/null/array/object) land as real JSON values, not text.
+    jsonSet(column, writes, bind) {
+        const args = writes
+            .map(w => `${jsonPathLiteral(w.segments)}, json(${bind(JSON.stringify(w.value))})`)
+            .join(', ');
+        return `json_set(${column}, ${args})`;
+    }
+    // SQLite has no row-level pessimistic lock — a write transaction (BEGIN
+    // IMMEDIATE) already serializes writers, so the queue reservation is safe
+    // without a `FOR UPDATE` suffix. No-op, options included: with no row locks
+    // there is never a locked row to skip or fail on.
+    lockSql(_mode, _opts) {
+        return '';
+    }
+    // SQLite + Postgres share the ON CONFLICT (target) DO UPDATE / DO NOTHING form,
+    // referencing the rejected row's values via the `excluded` pseudo-table.
+    upsertClause(uniqueBy, update) {
+        const target = uniqueBy.map(c => this.quoteId(c)).join(', ');
+        if (update.length === 0)
+            return `ON CONFLICT (${target}) DO NOTHING`;
+        const sets = update.map(c => `${this.quoteId(c)} = excluded.${this.quoteId(c)}`).join(', ');
+        return `ON CONFLICT (${target}) DO UPDATE SET ${sets}`;
+    }
+    // SQLite has a small set of storage classes and no real type checking, so the
+    // mapping is coarse: TEXT for anything string-ish, INTEGER for ints/booleans,
+    // REAL/NUMERIC for floats/decimals, BLOB for binary. `length`/`precision` are
+    // recorded on the column for pg/mysql but carry no meaning in SQLite types.
+    columnTypeSql(column) {
+        if (column.autoIncrement) {
+            // SQLite bundles the PK into the type: an INTEGER PRIMARY KEY column is the
+            // rowid alias, and AUTOINCREMENT prevents id reuse. The compiler appends
+            // nothing else to this.
+            return 'INTEGER PRIMARY KEY AUTOINCREMENT';
+        }
+        switch (column.type) {
+            case 'increments': // only reached if an increments column isn't auto (defensive)
+            case 'integer':
+            case 'bigInteger':
+            case 'tinyInteger':
+            case 'smallInteger':
+            case 'mediumInteger':
+            case 'boolean':
+                return 'INTEGER';
+            case 'string':
+            case 'char':
+            case 'text':
+            case 'mediumText':
+            case 'longText':
+            case 'uuid':
+            case 'ulid':
+            case 'json':
+            case 'jsonb':
+            case 'date':
+            case 'time':
+            case 'dateTime':
+            case 'timestamp':
+                return 'TEXT';
+            case 'float':
+            case 'double':
+                return 'REAL';
+            case 'decimal':
+                return 'NUMERIC';
+            case 'binary':
+                return 'BLOB';
+            // SQLite has no enum/set type. Mirror Laravel's SQLite grammar: a TEXT
+            // column with a CHECK (… IN (…)) constraint. `set` genuinely has no
+            // single-column equivalent (multiple values), so it's unsupported.
+            case 'enum':
+                return `TEXT CHECK (${this.quoteId(column.name)} IN (${quoteValueList(column.enumValues ?? [])}))`;
+            case 'set':
+                throw new NativeOrmError('NATIVE_DDL_UNSUPPORTED_TYPE', `[RudderJS ORM native] SQLite has no SET column type ("${column.name}"). Use enum(), a json column, or a pivot table.`);
+            default: {
+                // Exhaustiveness guard — a new ColumnType must extend this switch.
+                const unreachable = column.type;
+                throw new NativeOrmError('NATIVE_DDL_UNKNOWN_TYPE', `[RudderJS ORM native] No SQLite type mapping for column type ${JSON.stringify(unreachable)}.`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=dialect.js.map

package/dist/native/dialect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect.js","sourceRoot":"","sources":["../../src/native/dialect.ts"],"names":[],"mappings":"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"}

package/dist/native/driver.d.ts

@@ -0,0 +1,37 @@
+export type { Row, Executor, Transaction, Connection, TransactionOptions, TransactionIsolationLevel, } from '@rudderjs/contracts';
+import type { Connection } from '@rudderjs/contracts';
+/** Result metadata for a write run through {@link AffectingExecutor}. */
+export interface AffectingResult {
+    /** The auto-increment id the write generated, or `null` when none (a
+     *  non-auto-increment key, or an UPDATE/DELETE). */
+    insertId: number | null;
+    /** Rows the statement affected — the count callers return from
+     *  `updateAll` / `deleteAll` and `DB.insert/update/delete`. */
+    affectedRows: number;
+}
+/**
+ * A write-with-metadata escape hatch for dialects WITHOUT `RETURNING` (MySQL).
+ * On SQLite/Postgres the engine reads written rows back via `RETURNING *`
+ * (`Executor.execute`), so those drivers don't implement this. The MySQL driver
+ * does: the query builder's no-RETURNING path reads `insertId` (for `create`)
+ * and `affectedRows` (for `updateAll`/`deleteAll`) from here, then re-SELECTs by
+ * primary key for terminals that must return the row. A native-only seam (not in
+ * `@rudderjs/contracts`) — accessed by capability check, never on the read path.
+ */
+export interface AffectingExecutor {
+    affectingExecute(sql: string, bindings: readonly unknown[]): Promise<AffectingResult>;
+}
+/**
+ * A database connection the native engine drives — the per-platform seam.
+ * Structurally identical to the canonical {@link Connection}; the distinct name
+ * marks the swappable driver boundary (better-sqlite3 / postgres / RN / WASM).
+ *
+ * `transaction()` (via `Connection`) was defined in Phase 2 so the write path
+ * was transaction-aware by construction; Phase 4 wires the public
+ * `Model.transaction()` API to it.
+ */
+export interface Driver extends Connection {
+    /** Release the underlying connection/handle. Idempotent. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=driver.d.ts.map

package/dist/native/driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.d.ts","sourceRoot":"","sources":["../../src/native/driver.ts"],"names":[],"mappings":"AAkBA,YAAY,EACV,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EACtC,kBAAkB,EAAE,yBAAyB,GAC9C,MAAM,qBAAqB,CAAA;AAE5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AAErD,yEAAyE;AACzE,MAAM,WAAW,eAAe;IAC9B;wDACoD;IACpD,QAAQ,EAAM,MAAM,GAAG,IAAI,CAAA;IAC3B;mEAC+D;IAC/D,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAAA;CACtF;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,MAAO,SAAQ,UAAU;IACxC,4DAA4D;IAC5D,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CACvB"}

package/dist/native/driver.js

@@ -0,0 +1,19 @@
+// ─── Driver seam (per-platform) ────────────────────────────
+//
+// The `Driver` is the ONLY part of the native engine that differs across
+// platforms. It executes already-compiled SQL + bindings and returns rows.
+// The compiler and `NativeQueryBuilder` talk to the {@link Executor} interface
+// and never to a concrete driver — so a React Native (`op-sqlite`/`expo-sqlite`)
+// or browser (WASM) driver drops in later without touching the SQL layer.
+//
+// This module is PURE: type-only. No `node:` import, no I/O. Concrete drivers
+// (e.g. `drivers/better-sqlite3.ts`) live in their own node-only modules and
+// lazy-load their package.
+//
+// The model-independent execution types (`Row`, `Executor`, `Transaction`,
+// `Connection`) are now owned by `@rudderjs/contracts` (the zero-dep foundation)
+// and surfaced to apps via `@rudderjs/database`'s `DB` facade. They're re-exported
+// here unchanged so every existing `./driver.js` import site keeps working — the
+// native engine implements the same contract.
+export {};
+//# sourceMappingURL=driver.js.map

package/dist/native/driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"driver.js","sourceRoot":"","sources":["../../src/native/driver.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,yEAAyE;AACzE,2EAA2E;AAC3E,+EAA+E;AAC/E,iFAAiF;AACjF,0EAA0E;AAC1E,EAAE;AACF,8EAA8E;AAC9E,6EAA6E;AAC7E,2BAA2B;AAC3B,EAAE;AACF,2EAA2E;AAC3E,iFAAiF;AACjF,mFAAmF;AACnF,iFAAiF;AACjF,8CAA8C"}

package/dist/native/drivers/better-sqlite3.d.ts

@@ -0,0 +1,56 @@
+import type { Driver, Transaction, Row, TransactionOptions } from '../driver.js';
+/** Connection config for {@link BetterSqlite3Driver.open}. */
+export interface BetterSqlite3DriverConfig {
+    /**
+     * Database location. Accepts a filesystem path, a `file:` URL, or
+     * `':memory:'` for an in-memory database (the default). A leading `file:`
+     * scheme is stripped for better-sqlite3, which wants a bare path.
+     */
+    filename?: string;
+    /** Forwarded to the better-sqlite3 `Database` constructor (e.g. `readonly`). */
+    options?: Record<string, unknown>;
+}
+/**
+ * {@link Driver} backed by better-sqlite3. Construct via the static
+ * {@link BetterSqlite3Driver.open} factory, which performs the lazy import.
+ */
+export declare class BetterSqlite3Driver implements Driver {
+    private readonly db;
+    /**
+     * Current transaction nesting depth. 0 = no open transaction; 1 = inside a
+     * top-level `BEGIN`; ≥2 = inside N−1 nested SAVEPOINTs. Drives the BEGIN-vs-
+     * SAVEPOINT choice in {@link transaction}. Single field is safe because
+     * better-sqlite3 is single-connection and synchronous — there is exactly one
+     * open transaction stack per driver instance.
+     */
+    private depth;
+    private constructor();
+    /**
+     * Resolve the `better-sqlite3` package, open the database, and return a
+     * ready driver. Throws {@link NativeDriverError} with install guidance when
+     * the package isn't present (it's an optional peer).
+     */
+    static open(config?: BetterSqlite3DriverConfig): Promise<BetterSqlite3Driver>;
+    execute(sql: string, bindings: readonly unknown[]): Promise<Row[]>;
+    /**
+     * Run `fn` inside a transaction. The top-level call wraps it in
+     * BEGIN/COMMIT/ROLLBACK; a nested call (depth ≥ 1) wraps it in a uniquely
+     * named SAVEPOINT so an inner failure rolls back only its own work, leaving
+     * the outer transaction intact. The transaction-scoped {@link Transaction} is
+     * the driver itself — better-sqlite3 is synchronous and single-connection, so
+     * every `execute` between the markers runs on the one open transaction.
+     *
+     * (We don't use better-sqlite3's own `db.transaction()` wrapper because it
+     * only accepts a *synchronous* function, and our `fn` is async — savepoints
+     * give us the same nesting semantics over an async callback.)
+     *
+     * **Single-connection caveat:** because there is one connection, two
+     * *concurrently* in-flight top-level `transaction()` calls would collide on
+     * the same connection. SQLite serializes writers anyway; the native engine
+     * assumes transactions are not run concurrently against one SQLite handle.
+     * Pooled drivers (pg/mysql, Phase 5/6) pin a dedicated client per transaction.
+     */
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=better-sqlite3.d.ts.map

package/dist/native/drivers/better-sqlite3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"better-sqlite3.d.ts","sourceRoot":"","sources":["../../../src/native/drivers/better-sqlite3.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAmBhF,8DAA8D;AAC9D,MAAM,WAAW,yBAAyB;IACxC;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,MAAM;IAU5B,OAAO,CAAC,QAAQ,CAAC,EAAE;IATvC;;;;;;OAMG;IACH,OAAO,CAAC,KAAK,CAAI;IAEjB,OAAO;IAEP;;;;OAIG;WACU,IAAI,CAAC,MAAM,GAAE,yBAA8B,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA6BjF,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAaxE;;;;;;;;;;;;;;;;;OAiBG;IACG,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,WAAW,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC;IA0C1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}