@rudderjs/database 1.1.0 → 1.2.1

package/dist/native/drivers/better-sqlite3.js

@@ -0,0 +1,171 @@
+// ─── better-sqlite3 Driver (Node) ──────────────────────────
+//
+// Concrete {@link Driver} over the `better-sqlite3` package. NODE-ONLY:
+// `better-sqlite3` is an optional peer of `@rudderjs/orm` and is loaded with a
+// lazy `await import()` inside `open()` so this module never drags the native
+// addon into a client bundle at eval time (cross-phase rule 5).
+//
+// better-sqlite3 is synchronous; we wrap its calls in resolved promises to
+// satisfy the async {@link Driver} contract shared with RN/WASM drivers.
+import { NativeDriverError } from '../errors.js';
+/**
+ * {@link Driver} backed by better-sqlite3. Construct via the static
+ * {@link BetterSqlite3Driver.open} factory, which performs the lazy import.
+ */
+export class BetterSqlite3Driver {
+    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.
+     */
+    depth = 0;
+    constructor(db) {
+        this.db = db;
+    }
+    /**
+     * 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 async open(config = {}) {
+        const filename = normalizeFilename(config.filename);
+        let Database;
+        try {
+            // `better-sqlite3` uses `export =`, so a dynamic import wraps it in
+            // `.default`. Fall back to the namespace object for older interop.
+            const mod = await import('better-sqlite3');
+            Database = mod.default ?? mod;
+        }
+        catch (err) {
+            throw new NativeDriverError(`[RudderJS ORM native] Failed to load "better-sqlite3". It is an optional ` +
+                `peer of @rudderjs/orm — install it with \`pnpm add better-sqlite3\` to use ` +
+                `the native SQLite engine.`, { cause: err });
+        }
+        try {
+            const db = new Database(filename, config.options);
+            return new BetterSqlite3Driver(db);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new NativeDriverError(`[RudderJS ORM native] Could not open SQLite database at ${JSON.stringify(filename)}: ${msg}`, { cause: err });
+        }
+    }
+    async execute(sql, bindings) {
+        const params = normalizeBindings(bindings);
+        const stmt = this.db.prepare(sql);
+        // `.all()` is only valid on statements that return rows. A SELECT — or any
+        // write with a `RETURNING` clause — is a reader; a plain INSERT/UPDATE/DELETE
+        // is not and routes through `.run()`, yielding no rows.
+        if (stmt.reader) {
+            return stmt.all(...params);
+        }
+        stmt.run(...params);
+        return [];
+    }
+    /**
+     * 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.
+     */
+    async transaction(fn, opts) {
+        // SQLite has no SQL-standard isolation levels (one writer; readers see a
+        // serializable snapshot) — a requested level would silently mean nothing,
+        // so throw rather than no-op. Checked before the nesting branch: the error
+        // is the same at any depth.
+        if (opts?.isolationLevel) {
+            throw new Error('[RudderJS ORM native] SQLite does not support transaction isolation levels — ' +
+                'its single-writer model is already serializable. Drop the isolationLevel ' +
+                'option, or use the Postgres/MySQL engine.');
+        }
+        const top = this.depth === 0;
+        const savepoint = top ? null : `rudder_sp_${this.depth}`;
+        if (top)
+            this.db.exec('BEGIN');
+        else
+            this.db.exec(`SAVEPOINT ${savepoint}`);
+        this.depth++;
+        try {
+            const result = await fn(this);
+            if (top)
+                this.db.exec('COMMIT');
+            else
+                this.db.exec(`RELEASE ${savepoint}`);
+            return result;
+        }
+        catch (err) {
+            try {
+                if (top) {
+                    this.db.exec('ROLLBACK');
+                }
+                else {
+                    // Roll back to the savepoint, then release it so the saved name is
+                    // discarded — otherwise it lingers on the outer transaction's stack.
+                    this.db.exec(`ROLLBACK TO ${savepoint}`);
+                    this.db.exec(`RELEASE ${savepoint}`);
+                }
+            }
+            catch {
+                // A failed ROLLBACK (e.g. the transaction already aborted) must not mask
+                // the original error — swallow it and re-throw the cause below.
+            }
+            throw err;
+        }
+        finally {
+            this.depth--;
+        }
+    }
+    async close() {
+        this.db.close();
+    }
+}
+/**
+ * better-sqlite3 binds only numbers, strings, bigints, buffers, and `null` —
+ * a JS `boolean` throws `TypeError: SQLite3 can only bind …`. SQLite has no
+ * boolean type, so map `true`/`false` to the integers `1`/`0`; this round-trips
+ * with the ORM's `boolean` cast (which reads `0`/`1` back). The mapping covers
+ * raw boolean values that bypass a column cast — an untyped `where('flag', true)`
+ * predicate, or a `query().create({ flag: true })` on a column without a
+ * boolean cast. Other unbindable values (`Date`, plain objects) are passed
+ * through so better-sqlite3 still rejects them with its own clear error.
+ *
+ * Returns the original array reference when nothing needed coercion, so the
+ * common boolean-free path allocates nothing.
+ *
+ * Any future SQLite driver (libsql, op-sqlite for React Native) needs the same
+ * mapping — share this helper rather than re-deriving it per driver.
+ */
+function normalizeBindings(bindings) {
+    let hasBoolean = false;
+    for (const v of bindings) {
+        if (typeof v === 'boolean') {
+            hasBoolean = true;
+            break;
+        }
+    }
+    if (!hasBoolean)
+        return bindings;
+    return bindings.map(v => (typeof v === 'boolean' ? (v ? 1 : 0) : v));
+}
+/** Strip a `file:` scheme and default to an in-memory database. */
+function normalizeFilename(filename) {
+    if (!filename)
+        return ':memory:';
+    return filename.replace(/^file:/, '');
+}
+//# sourceMappingURL=better-sqlite3.js.map

package/dist/native/drivers/better-sqlite3.js.map

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

package/dist/native/drivers/mysql.d.ts

@@ -0,0 +1,30 @@
+import type { Driver, Transaction, Row, AffectingExecutor, AffectingResult, TransactionOptions } from '../driver.js';
+/** Connection config for {@link MysqlDriver.open}. */
+export interface MysqlDriverConfig {
+    /** MySQL connection string, e.g. `mysql://user:pass@host:3306/db`. */
+    url: string;
+    /** Forwarded to `mysql2.createPool()` (e.g. `connectionLimit`, `ssl`). */
+    options?: Record<string, unknown>;
+}
+/**
+ * {@link Driver} backed by `mysql2`. Construct via the static
+ * {@link MysqlDriver.open} factory, which lazy-imports the package, builds a
+ * pool, and validates connectivity up front. Autocommit statements run on the
+ * pool; `transaction()` reserves a dedicated connection.
+ */
+export declare class MysqlDriver implements Driver, AffectingExecutor {
+    private readonly pool;
+    private constructor();
+    /**
+     * Resolve `mysql2`, build a pool for `config.url`, validate the connection, and
+     * return a ready driver. Throws {@link NativeDriverError} with install guidance
+     * when the package is missing, or a connection error when the URL is
+     * unreachable — so failures surface at setup, not deep in a request.
+     */
+    static open(config: MysqlDriverConfig): Promise<MysqlDriver>;
+    execute(sql: string, bindings: readonly unknown[]): Promise<Row[]>;
+    affectingExecute(sql: string, bindings: readonly unknown[]): Promise<AffectingResult>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=mysql.d.ts.map

package/dist/native/drivers/mysql.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mysql.d.ts","sourceRoot":"","sources":["../../../src/native/drivers/mysql.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,iBAAiB,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AA8BpH,sDAAsD;AACtD,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAA;IACX,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AA4DD;;;;;GAKG;AACH,qBAAa,WAAY,YAAW,MAAM,EAAE,iBAAiB;IACvC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAAzC,OAAO;IAEP;;;;;OAKG;WACU,IAAI,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,WAAW,CAAC;IA2ClE,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAIlE,gBAAgB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,eAAe,CAAC;IAU/E,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;IAmB1F,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/native/drivers/mysql.js

@@ -0,0 +1,176 @@
+// ─── MySQL Driver (Node, mysql2/promise) ───────────────────
+//
+// Concrete {@link Driver} over the `mysql2` package (its `mysql2/promise` API).
+// NODE-ONLY: `mysql2` is an optional peer of `@rudderjs/orm`, lazy-`import()`ed
+// inside `open()` so this module never drags the driver into a client bundle at
+// eval time (cross-phase rule 5). Mirrors the postgres driver's shape.
+//
+// Like postgres (and unlike single-connection better-sqlite3), mysql2 pools
+// connections — so a transaction MUST pin one connection. The top-level driver
+// runs autocommit statements on the pool; `transaction()` reserves a connection
+// (`getConnection()` + `beginTransaction`), and nested transactions map to
+// SAVEPOINTs on that pinned connection (same savepoint semantics the prisma/
+// drizzle adapters use).
+//
+// MySQL has no `RETURNING`, so this driver also implements {@link
+// AffectingExecutor}: writes report their auto-increment `insertId` and
+// `affectedRows` from mysql2's `ResultSetHeader`, which the query builder's
+// no-RETURNING path consumes.
+import { NativeDriverError } from '../errors.js';
+import { isolationLevelSql, nestedIsolationError } from '../isolation.js';
+/** Monotonic counter for unique nested-transaction SAVEPOINT names. */
+let savepointSeq = 0;
+/** Run a statement on a queryable and normalize the row result to `Row[]`
+ *  (a write's ResultSetHeader is not an array → no rows). */
+async function runQuery(q, sql, bindings) {
+    const [result] = await q.query(sql, bindings);
+    return Array.isArray(result) ? result : [];
+}
+/** Run a write and read its metadata. A SELECT (array result) reports its row
+ *  count as `affectedRows` and no `insertId`; a write reads the header. */
+async function runAffecting(q, sql, bindings) {
+    const [result] = await q.query(sql, bindings);
+    if (Array.isArray(result))
+        return { insertId: null, affectedRows: result.length };
+    const header = result;
+    const insertId = typeof header.insertId === 'number' && header.insertId > 0 ? header.insertId : null;
+    return { insertId, affectedRows: header.affectedRows ?? 0 };
+}
+/**
+ * A {@link Transaction} scope pinned to one mysql2 connection. Every query on
+ * the scope runs on that connection, so a transaction-scoped query stays on the
+ * transaction's connection; nesting opens a SAVEPOINT on it.
+ */
+class MysqlScope {
+    conn;
+    constructor(conn) {
+        this.conn = conn;
+    }
+    execute(sql, bindings) {
+        return runQuery(this.conn, sql, bindings);
+    }
+    affectingExecute(sql, bindings) {
+        return runAffecting(this.conn, sql, bindings);
+    }
+    // Nested transaction → SAVEPOINT on the current (already-transactional)
+    // connection, so an inner failure rolls back only its own work. An isolation
+    // level is rejected — the open transaction's isolation is already fixed (MySQL
+    // itself errors on SET TRANSACTION while a transaction is in progress).
+    async transaction(fn, opts) {
+        if (opts?.isolationLevel)
+            throw nestedIsolationError();
+        const name = `rudder_sp_${(savepointSeq = (savepointSeq + 1) % Number.MAX_SAFE_INTEGER)}`;
+        await this.conn.query(`SAVEPOINT ${name}`);
+        try {
+            const result = await fn(this);
+            await this.conn.query(`RELEASE SAVEPOINT ${name}`);
+            return result;
+        }
+        catch (err) {
+            try {
+                // Roll back to the savepoint, then release it so the name is discarded.
+                await this.conn.query(`ROLLBACK TO SAVEPOINT ${name}`);
+                await this.conn.query(`RELEASE SAVEPOINT ${name}`);
+            }
+            catch {
+                // A failed rollback must not mask the original error.
+            }
+            throw err;
+        }
+    }
+}
+/**
+ * {@link Driver} backed by `mysql2`. Construct via the static
+ * {@link MysqlDriver.open} factory, which lazy-imports the package, builds a
+ * pool, and validates connectivity up front. Autocommit statements run on the
+ * pool; `transaction()` reserves a dedicated connection.
+ */
+export class MysqlDriver {
+    pool;
+    constructor(pool) {
+        this.pool = pool;
+    }
+    /**
+     * Resolve `mysql2`, build a pool for `config.url`, validate the connection, and
+     * return a ready driver. Throws {@link NativeDriverError} with install guidance
+     * when the package is missing, or a connection error when the URL is
+     * unreachable — so failures surface at setup, not deep in a request.
+     */
+    static async open(config) {
+        let mod;
+        try {
+            // mysql2 ships its promise API at `mysql2/promise`.
+            mod = await import('mysql2/promise');
+        }
+        catch (err) {
+            throw new NativeDriverError(`[RudderJS ORM native] Failed to load "mysql2". It is an optional peer of ` +
+                `@rudderjs/orm — install it with \`pnpm add mysql2\` to use the native MySQL engine.`, { cause: err });
+        }
+        const pool = mod.createPool({
+            uri: config.url,
+            // MySQL has no boolean type — `t.boolean()` columns are `tinyint(1)`
+            // (the BOOLEAN alias). Map them back to JS booleans on read so boolean
+            // columns round-trip like they do on Postgres (whose driver parses the
+            // native bool type). Only display-width-1 TINY columns qualify — a plain
+            // `t.tinyInt()` (width 4) stays numeric. `config.options` can override.
+            typeCast: (field, next) => {
+                if (field.type === 'TINY' && field.length === 1) {
+                    const value = field.string();
+                    return value === null ? null : value === '1';
+                }
+                return next();
+            },
+            ...config.options,
+        });
+        const driver = new MysqlDriver(pool);
+        try {
+            await pool.query('select 1');
+        }
+        catch (err) {
+            await pool.end().catch(() => { });
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new NativeDriverError(`[RudderJS ORM native] Could not connect to MySQL at the configured URL: ${msg}`, { cause: err });
+        }
+        return driver;
+    }
+    execute(sql, bindings) {
+        return runQuery(this.pool, sql, bindings);
+    }
+    affectingExecute(sql, bindings) {
+        return runAffecting(this.pool, sql, bindings);
+    }
+    // Top-level transaction → reserve a connection, BEGIN, COMMIT (ROLLBACK on
+    // throw), always release. Every query inside runs on the pinned connection.
+    // An isolation level is applied via `SET TRANSACTION ISOLATION LEVEL` BEFORE
+    // `beginTransaction` — on MySQL the un-scoped form applies only to the NEXT
+    // transaction started on the connection (issuing it inside one errors), and
+    // it does not persist, so the pooled connection is released clean.
+    async transaction(fn, opts) {
+        const level = opts?.isolationLevel ? isolationLevelSql(opts.isolationLevel) : null;
+        const conn = await this.pool.getConnection();
+        try {
+            if (level)
+                await conn.query(`SET TRANSACTION ISOLATION LEVEL ${level}`);
+            await conn.beginTransaction();
+            try {
+                const result = await fn(new MysqlScope(conn));
+                await conn.commit();
+                return result;
+            }
+            catch (err) {
+                try {
+                    await conn.rollback();
+                }
+                catch { /* best effort */ }
+                throw err;
+            }
+        }
+        finally {
+            conn.release();
+        }
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+//# sourceMappingURL=mysql.js.map

package/dist/native/drivers/mysql.js.map

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

package/dist/native/drivers/postgres.d.ts

@@ -0,0 +1,57 @@
+import type { Driver, Transaction, Row, TransactionOptions } from '../driver.js';
+/**
+ * The structural slice of porsager's `postgres` API we depend on. Typed here
+ * (not via `@types`) so the optional peer carries no compile-time dependency —
+ * same approach as the better-sqlite3 driver.
+ */
+interface PgSql {
+    /** Run raw SQL with positional ($1, $2, …) params; resolves to the result rows
+     *  (empty for statements with no result set). */
+    unsafe(query: string, params?: readonly unknown[]): Promise<unknown[]>;
+    /** Open a transaction; `fn` receives a connection-pinned `sql`. BEGIN/COMMIT,
+     *  ROLLBACK on throw. */
+    begin<T>(fn: (sql: PgSql) => Promise<T>): Promise<T>;
+    /** Open a SAVEPOINT inside a transaction; only valid on a transaction `sql`. */
+    savepoint<T>(fn: (sql: PgSql) => Promise<T>): Promise<T>;
+    /** Drain the pool and close all connections. */
+    end(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}
+/** Connection config for {@link PostgresDriver.open}. */
+export interface PostgresDriverConfig {
+    /** Postgres connection string, e.g. `postgres://user:pass@host:5432/db`. */
+    url: string;
+    /** Forwarded to the porsager `postgres()` factory (e.g. `max`, `ssl`). */
+    options?: Record<string, unknown>;
+}
+/**
+ * A {@link Transaction} scope bound to one porsager `sql` handle — the pool, a
+ * transaction, or a savepoint. Every query on the scope runs on that handle, so
+ * a transaction-scoped query stays on the transaction's pinned connection.
+ */
+declare class PgScope implements Transaction {
+    protected readonly sql: PgSql;
+    constructor(sql: PgSql);
+    execute(query: string, bindings: readonly unknown[]): Promise<Row[]>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+}
+/**
+ * {@link Driver} backed by porsager `postgres`. Construct via the static
+ * {@link PostgresDriver.open} factory, which lazy-imports the package and
+ * validates connectivity up front.
+ */
+export declare class PostgresDriver extends PgScope implements Driver {
+    private constructor();
+    /**
+     * Resolve the `postgres` package, build a pool for `config.url`, validate the
+     * connection, and return a ready driver. Throws {@link NativeDriverError} with
+     * install guidance when the package is missing, or a connection error when the
+     * URL is unreachable — so failures surface at setup, not deep in a request.
+     */
+    static open(config: PostgresDriverConfig): Promise<PostgresDriver>;
+    transaction<T>(fn: (tx: Transaction) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    close(): Promise<void>;
+}
+export {};
+//# sourceMappingURL=postgres.d.ts.map

package/dist/native/drivers/postgres.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"postgres.d.ts","sourceRoot":"","sources":["../../../src/native/drivers/postgres.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAIhF;;;;GAIG;AACH,UAAU,KAAK;IACb;qDACiD;IACjD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAA;IACtE;6BACyB;IACzB,KAAK,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACpD,gFAAgF;IAChF,SAAS,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IACxD,gDAAgD;IAChD,GAAG,CAAC,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACnD;AAGD,yDAAyD;AACzD,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAA;IACX,0EAA0E;IAC1E,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;;GAIG;AACH,cAAM,OAAQ,YAAW,WAAW;IACtB,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,KAAK;gBAAV,GAAG,EAAE,KAAK;IAEnC,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC;IAgBpE,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;CAIjG;AAED;;;;GAIG;AACH,qBAAa,cAAe,SAAQ,OAAQ,YAAW,MAAM;IAC3D,OAAO;IAIP;;;;;OAKG;WACU,IAAI,CAAC,MAAM,EAAE,oBAAoB,GAAG,OAAO,CAAC,cAAc,CAAC;IAyFzD,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;IAQnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B"}

package/dist/native/drivers/postgres.js

@@ -0,0 +1,155 @@
+// ─── postgres Driver (Node, porsager `postgres`) ───────────
+//
+// Concrete {@link Driver} over the `postgres` package (porsager). NODE-ONLY:
+// `postgres` is an optional peer of `@rudderjs/orm`, lazy-`import()`ed inside
+// `open()` so this module never drags the driver into a client bundle at eval
+// time (cross-phase rule 5). Mirrors the same shape used by `@rudderjs/orm-drizzle`.
+//
+// Unlike better-sqlite3 (single synchronous connection), porsager pools
+// connections. So a transaction MUST run on one pinned connection — we use
+// porsager's own `sql.begin()` / `sql.savepoint()`, which reserve a connection
+// for the whole scope, rather than issuing a bare `BEGIN` on the pool (which
+// could land BEGIN and the following statements on different connections).
+import { NativeDriverError } from '../errors.js';
+import { isolationLevelSql, nestedIsolationError } from '../isolation.js';
+/**
+ * A {@link Transaction} scope bound to one porsager `sql` handle — the pool, a
+ * transaction, or a savepoint. Every query on the scope runs on that handle, so
+ * a transaction-scoped query stays on the transaction's pinned connection.
+ */
+class PgScope {
+    sql;
+    constructor(sql) {
+        this.sql = sql;
+    }
+    async execute(query, bindings) {
+        // porsager binds JS booleans / Dates / numbers to their native Postgres
+        // types, so no value coercion is needed (unlike the SQLite driver's
+        // boolean→0/1 mapping). A no-binding call (DDL) goes through the simple
+        // query protocol; statements with no result set resolve to an empty list.
+        const rows = bindings.length
+            ? await this.sql.unsafe(query, bindings)
+            : await this.sql.unsafe(query);
+        return rows;
+    }
+    // Nested transaction → SAVEPOINT on the current (already-transactional)
+    // connection. Reachable only from a scope created inside `begin` (the
+    // top-level driver overrides `transaction` to open the BEGIN), so `savepoint`
+    // is always valid here. An isolation level is rejected — a savepoint runs
+    // inside the open transaction, whose isolation is already fixed.
+    async transaction(fn, opts) {
+        if (opts?.isolationLevel)
+            throw nestedIsolationError();
+        return this.sql.savepoint((sp) => fn(new PgScope(sp)));
+    }
+}
+/**
+ * {@link Driver} backed by porsager `postgres`. Construct via the static
+ * {@link PostgresDriver.open} factory, which lazy-imports the package and
+ * validates connectivity up front.
+ */
+export class PostgresDriver extends PgScope {
+    constructor(sql) {
+        super(sql);
+    }
+    /**
+     * Resolve the `postgres` package, build a pool for `config.url`, validate the
+     * connection, and return a ready driver. Throws {@link NativeDriverError} with
+     * install guidance when the package is missing, or a connection error when the
+     * URL is unreachable — so failures surface at setup, not deep in a request.
+     */
+    static async open(config) {
+        let factory;
+        try {
+            // porsager uses `export =`; a dynamic import wraps it in `.default`.
+            const mod = await import('postgres');
+            factory = mod.default ?? mod;
+        }
+        catch (err) {
+            throw new NativeDriverError(`[RudderJS ORM native] Failed to load "postgres". It is an optional peer of ` +
+                `@rudderjs/orm — install it with \`pnpm add postgres\` to use the native Postgres engine.`, { cause: err });
+        }
+        // Silence Postgres NOTICEs (e.g. "table does not exist, skipping" on DROP IF
+        // EXISTS) so they don't pollute CLI / migration output, and parse int8 /
+        // bigserial (OID 20) as a JS number rather than porsager's default string —
+        // so a model's auto-increment `id` is a number on Postgres just as it is on
+        // SQLite (INTEGER PK → number). Precision caveat: int8 values above 2^53 lose
+        // precision; that's fine for auto-increment ids, and a column needing the
+        // full int8 range should declare a cast.
+        const sql = factory(config.url, {
+            onnotice: () => { },
+            types: {
+                int8AsNumber: {
+                    to: 20,
+                    from: [20],
+                    serialize: (x) => String(x),
+                    parse: (x) => parseInt(x, 10),
+                },
+                // Replace porsager's default `date` type. Its serializer round-trips
+                // EVERY bound value through `new Date(x).toISOString()` — and because
+                // serializers register for all `from` OIDs, a param the server
+                // describes as date/timestamp/timestamptz (1082/1114/1184) hits it
+                // even when the JS value is a plain string. `new Date('2026-01-20
+                // 11:20:45')` parses as MACHINE-LOCAL time, so bound string timestamps
+                // were stored TZ-shifted on any non-UTC machine (silent data
+                // corruption; CI is UTC, which hid it). Strings now pass through
+                // verbatim — Postgres casts text natively, machine-TZ independent.
+                // `Date` values keep the exact previous behavior (`toISOString()`,
+                // same instant) and reads keep porsager's default parse (JS `Date`).
+                date: {
+                    to: 1184,
+                    from: [1082, 1114, 1184],
+                    serialize: (x) => x instanceof Date ? x.toISOString()
+                        : typeof x === 'number' ? new Date(x).toISOString()
+                            : String(x),
+                    parse: (x) => new Date(x),
+                },
+                // Replace porsager's default `json` type for the same reason as `date`
+                // above: its serializer `JSON.stringify`s EVERY bound value a server
+                // describes as json/jsonb (114/3802), so an already-stringified JSON
+                // param — the pg dialect's `jsonContains` binds `JSON.stringify(value)`,
+                // and apps porting sqlite-style code bind JSON text into jsonb columns —
+                // was DOUBLE-encoded: `'"php"'` arrived server-side as the JSON string
+                // `"\"php\""` and `@>` containment silently matched nothing. Strings now
+                // pass through verbatim (Postgres parses the JSON text natively; an
+                // invalid document surfaces as a clear server parse error); non-strings
+                // keep porsager's `JSON.stringify`, and reads keep its `JSON.parse`.
+                json: {
+                    to: 114,
+                    from: [114, 3802],
+                    serialize: (x) => (typeof x === 'string' ? x : JSON.stringify(x)),
+                    parse: (x) => JSON.parse(x),
+                },
+            },
+            ...config.options,
+        });
+        const driver = new PostgresDriver(sql);
+        try {
+            await sql.unsafe('select 1');
+        }
+        catch (err) {
+            await sql.end({ timeout: 1 }).catch(() => { });
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new NativeDriverError(`[RudderJS ORM native] Could not connect to Postgres at the configured URL: ${msg}`, { cause: err });
+        }
+        return driver;
+    }
+    // Top-level transaction → BEGIN/COMMIT (ROLLBACK on throw). porsager's `begin`
+    // reserves a connection for the whole scope, so every query inside runs on it.
+    // An isolation level is applied via `SET TRANSACTION ISOLATION LEVEL` as the
+    // FIRST statement inside the transaction — Postgres allows it any time before
+    // the first query, and `isolationLevelSql` validates the level (the keyword is
+    // spliced, never bound).
+    async transaction(fn, opts) {
+        const level = opts?.isolationLevel ? isolationLevelSql(opts.isolationLevel) : null;
+        return this.sql.begin(async (tx) => {
+            if (level)
+                await tx.unsafe(`SET TRANSACTION ISOLATION LEVEL ${level}`);
+            return fn(new PgScope(tx));
+        });
+    }
+    async close() {
+        await this.sql.end({ timeout: 5 });
+    }
+}
+//# sourceMappingURL=postgres.js.map

package/dist/native/drivers/postgres.js.map

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