@rudderjs/database 1.1.0 → 1.2.0

package/README.md

@@ -0,0 +1,70 @@
+# @rudderjs/database
+
+The SQL data-layer foundation for RudderJS — the `DB` facade, raw expressions, and the **built-in native SQL engine** (query compiler, schema builder, migrations, and drivers for SQLite / PostgreSQL / MySQL). `@rudderjs/orm` (the Eloquent-style `Model` layer) is built on top of this package and installs it automatically — most apps never add it by hand.
+
+```bash
+pnpm add @rudderjs/orm        # pulls in @rudderjs/database
+```
+
+Node-only: never import this package from client-bundle-reachable code.
+
+## `DB` facade
+
+Laravel-style raw-SQL entry point. Resolves the **same** active adapter your Models use (native, Prisma, or Drizzle) — one connection, never a second:
+
+```ts
+import { DB, raw } from '@rudderjs/database'
+
+const rows  = await DB.select('SELECT * FROM users WHERE active = ?', [true])
+const count = await DB.update('UPDATE posts SET draft = ? WHERE author_id = ?', [false, 7])
+
+await DB.transaction(async () => {
+  // Model.* AND DB.* calls in here join the same transaction
+})
+
+DB.listen((e) => console.log(e.sql, e.duration))      // query events
+const reporting = DB.connection('reporting')           // named connections
+```
+
+## Native engine
+
+The first-party SQL engine behind `engine: 'native'` connections — no external ORM. Headline API on the main entry:
+
+```ts
+// database/migrations/2026_06_02_120000_create_posts_table.ts
+import { Migration, Schema } from '@rudderjs/database'
+
+export default class extends Migration {
+  async up()   { await Schema.create('posts', (t) => { t.id(); t.string('title'); t.timestamps() }) }
+  async down() { await Schema.dropIfExists('posts') }
+}
+```
+
+Standalone (no framework — any Node app):
+
+```ts
+import { NativeAdapter, BetterSqlite3Driver } from '@rudderjs/database'
+```
+
+The full engine surface (compiler, dialects, `NativeQueryBuilder`, introspection, the schema→TS type generator) lives on the `./native` subpath. Drivers are optional peers — install the one you use: `better-sqlite3`, `postgres`, or `mysql2`.
+
+> Historical note: the engine originally shipped inside `@rudderjs/orm` at `@rudderjs/orm/native`. That subpath remains as a permanent re-export of this package, so existing migration files and imports keep working unchanged.
+
+## Sticky-read scope (`./sticky`)
+
+For read/write-split connections with `sticky: true`, reads after a write inside a request route to the writer. Outside a request scope (queue jobs, commands) wrap the work yourself:
+
+```ts
+import { runWithDatabaseContext } from '@rudderjs/database/sticky'
+
+await runWithDatabaseContext(async () => {
+  await Order.create({ ... })
+  await Order.query().latest().first()   // routed to the writer
+})
+```
+
+## Docs
+
+- Database guide: https://rudderjs.com/guide/database
+- Native engine: https://rudderjs.com/guide/database/native
+- Connections, read/write split: https://rudderjs.com/guide/database/connections

package/dist/db.d.ts

@@ -1,4 +1,4 @@
-import type { QueryListener, Row } from '@rudderjs/contracts';
+import type { QueryListener, Row, TransactionOptions } from '@rudderjs/contracts';
 import { Expression } from './expression.js';
 /**
  * A scoped facade over one NAMED connection — what `DB.connection('reporting')`
@@ -13,7 +13,8 @@ export interface DBConnection {
     update(sql: string, bindings?: readonly unknown[]): Promise<number>;
     delete(sql: string, bindings?: readonly unknown[]): Promise<number>;
     statement(sql: string, bindings?: readonly unknown[]): Promise<number>;
-    transaction<T>(fn: () => Promise<T>): Promise<T>;
+    transaction<T>(fn: () => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    afterCommit(fn: () => void | Promise<void>): Promise<void>;
     listen(listener: QueryListener): Promise<void>;
 }
 /**
@@ -41,10 +42,27 @@ export declare const DB: {
      * rejects. Nested `DB.transaction()` / `Model.transaction()` calls map to
      * savepoints where the driver supports them.
      *
+     * `opts.isolationLevel` sets the transaction's isolation level (`'read
+     * uncommitted' | 'read committed' | 'repeatable read' | 'serializable'`) —
+     * outermost call only; SQLite-backed adapters throw (no isolation levels).
+     *
      * @throws if no transaction runner is registered (no database provider loaded),
      *   or if the active adapter doesn't implement `transaction()`.
      */
-    readonly transaction: <T>(fn: () => Promise<T>) => Promise<T>;
+    readonly transaction: <T>(fn: () => Promise<T>, opts?: TransactionOptions) => Promise<T>;
+    /**
+     * Queue `fn` to run after the transaction open in the current async context
+     * commits, mirroring Laravel's `DB::afterCommit` — the standard pattern for
+     * side effects that must not fire on a rollback (emails, webhooks, queue
+     * dispatches). Runs only when the OUTERMOST transaction commits; a rollback
+     * (or an enclosing savepoint's rollback) drops the callback. With no open
+     * transaction, `fn` runs immediately. Shares the queue with `transaction()` /
+     * `Model.transaction()` — the runner is `@rudderjs/orm`'s `afterCommit()`.
+     *
+     * @throws if no after-commit runner is registered (no database provider
+     *   loaded, or `@rudderjs/orm` predates after-commit support).
+     */
+    readonly afterCommit: (fn: () => void | Promise<void>) => Promise<void>;
     /**
      * Register a query listener, mirroring Laravel's `DB::listen`. The listener
      * fires once per executed query with `{ sql, bindings, duration }` (duration

package/dist/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAc,aAAa,EAAE,GAAG,EAAE,MAAM,qBAAqB,CAAA;AAOzE,OAAO,EAAE,UAAU,EAAO,MAAM,iBAAiB,CAAA;AAoCjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAChD,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AAIH,eAAO,MAAM,EAAE;IACb,0DAA0D;2BACxC,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IAI5E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,6EAA6E;8BACxD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAIhF;;;;;;;;;;;OAWG;2BACe,CAAC,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,CAAC;IAItD;;;;;;;;;;;;OAYG;gCACc,aAAa,KAAG,IAAI;IAIrC,0EAA0E;0BAC/D,MAAM,GAAG,MAAM,KAAG,UAAU;IAIvC;;;;;;;;;;;OAWG;gCACc,MAAM,KAAG,YAAY;CA0B9B,CAAA"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAc,aAAa,EAAE,GAAG,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAA;AAQ7F,OAAO,EAAE,UAAU,EAAO,MAAM,iBAAiB,CAAA;AAoCjD;;;;;;GAMG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,GAAG,EAAE,CAAC,CAAA;IAClE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,MAAM,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACnE,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,SAAS,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IACtE,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3E,WAAW,CAAC,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC1D,MAAM,CAAC,QAAQ,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/C;AAED;;;;GAIG;AAIH,eAAO,MAAM,EAAE;IACb,0DAA0D;2BACxC,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,GAAG,EAAE,CAAC;IAI5E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,mEAAmE;2BACjD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAI7E,6EAA6E;8BACxD,MAAM,aAAY,SAAS,OAAO,EAAE,KAAQ,OAAO,CAAC,MAAM,CAAC;IAIhF;;;;;;;;;;;;;;;OAeG;2BACe,CAAC,MAAM,MAAM,OAAO,CAAC,CAAC,CAAC,SAAS,kBAAkB,KAAG,OAAO,CAAC,CAAC,CAAC;IAIjF;;;;;;;;;;;OAWG;+BACmB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAG,OAAO,CAAC,IAAI,CAAC;IAIhE;;;;;;;;;;;;OAYG;gCACc,aAAa,KAAG,IAAI;IAIrC,0EAA0E;0BAC/D,MAAM,GAAG,MAAM,KAAG,UAAU;IAIvC;;;;;;;;;;;OAWG;gCACc,MAAM,KAAG,YAAY;CA6B9B,CAAA"}

package/dist/db.js

@@ -10,7 +10,7 @@
 // One adapter instance is shared with the Models — no second connection. If the
 // active adapter doesn't implement the seam (older/partial adapters), each method
 // throws a clear error naming that adapter.
-import { resolveAdapter, resolveTransactionRunner, resolveConnectionResolver, resolveNamedTransactionRunner, } from './registry-bridge.js';
+import { resolveAdapter, resolveTransactionRunner, resolveConnectionResolver, resolveNamedTransactionRunner, resolveAfterCommitRunner, } from './registry-bridge.js';
 import { raw } from './expression.js';
 function adapterName(adapter) {
     return adapter.constructor?.name ?? 'the active adapter';
@@ -74,11 +74,30 @@ export const DB = {
      * rejects. Nested `DB.transaction()` / `Model.transaction()` calls map to
      * savepoints where the driver supports them.
      *
+     * `opts.isolationLevel` sets the transaction's isolation level (`'read
+     * uncommitted' | 'read committed' | 'repeatable read' | 'serializable'`) —
+     * outermost call only; SQLite-backed adapters throw (no isolation levels).
+     *
      * @throws if no transaction runner is registered (no database provider loaded),
      *   or if the active adapter doesn't implement `transaction()`.
      */
-    async transaction(fn) {
-        return resolveTransactionRunner()(fn);
+    async transaction(fn, opts) {
+        return resolveTransactionRunner()(fn, opts);
+    },
+    /**
+     * Queue `fn` to run after the transaction open in the current async context
+     * commits, mirroring Laravel's `DB::afterCommit` — the standard pattern for
+     * side effects that must not fire on a rollback (emails, webhooks, queue
+     * dispatches). Runs only when the OUTERMOST transaction commits; a rollback
+     * (or an enclosing savepoint's rollback) drops the callback. With no open
+     * transaction, `fn` runs immediately. Shares the queue with `transaction()` /
+     * `Model.transaction()` — the runner is `@rudderjs/orm`'s `afterCommit()`.
+     *
+     * @throws if no after-commit runner is registered (no database provider
+     *   loaded, or `@rudderjs/orm` predates after-commit support).
+     */
+    async afterCommit(fn) {
+        return resolveAfterCommitRunner()(fn);
     },
     /**
      * Register a query listener, mirroring Laravel's `DB::listen`. The listener
@@ -130,8 +149,11 @@ export const DB = {
             async statement(sql, bindings = []) {
                 return requireAffecting(await adapterFor())(sql, bindings);
             },
-            async transaction(fn) {
-                return resolveNamedTransactionRunner()(name, fn);
+            async transaction(fn, opts) {
+                return resolveNamedTransactionRunner()(name, fn, opts);
+            },
+            async afterCommit(fn) {
+                return resolveAfterCommitRunner()(fn, { connection: name });
             },
             async listen(listener) {
                 requireOnQuery(await adapterFor())(listener);

package/dist/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../src/db.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAC9D,EAAE;AACF,6EAA6E;AAC7E,yEAAyE;AACzE,8DAA8D;AAC9D,yEAAyE;AACzE,oFAAoF;AACpF,8DAA8D;AAC9D,EAAE;AACF,gFAAgF;AAChF,kFAAkF;AAClF,4CAA4C;AAG5C,OAAO,EACL,cAAc,EACd,wBAAwB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,wBAAwB,GACzB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAc,GAAG,EAAE,MAAM,iBAAiB,CAAA;AAEjD,SAAS,WAAW,CAAC,OAAmB;IACtC,OAAO,OAAO,CAAC,WAAW,EAAE,IAAI,IAAI,oBAAoB,CAAA;AAC1D,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAmB;IAC3C,IAAI,OAAO,OAAO,CAAC,SAAS,KAAK,UAAU,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CACb,iBAAiB,WAAW,CAAC,OAAO,CAAC,oCAAoC;YACvE,kDAAkD,CACrD,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAC,SAAS,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACxC,CAAC;AAED,SAAS,gBAAgB,CAAC,OAAmB;IAC3C,IAAI,OAAO,OAAO,CAAC,kBAAkB,KAAK,UAAU,EAAE,CAAC;QACrD,MAAM,IAAI,KAAK,CACb,iBAAiB,WAAW,CAAC,OAAO,CAAC,6CAA6C;YAChF,8EAA8E,CACjF,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACjD,CAAC;AAED,SAAS,cAAc,CAAC,OAAmB;IACzC,IAAI,OAAO,OAAO,CAAC,OAAO,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,KAAK,CACb,iBAAiB,WAAW,CAAC,OAAO,CAAC,kCAAkC;YACrE,yFAAyF,CAC5F,CAAA;IACH,CAAC;IACD,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;AACtC,CAAC;AAoBD;;;;GAIG;AACH,+EAA+E;AAC/E,iFAAiF;AACjF,kFAAkF;AAClF,MAAM,CAAC,MAAM,EAAE,GAAG;IAChB,0DAA0D;IAC1D,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,WAA+B,EAAE;QACzD,OAAO,gBAAgB,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,WAA+B,EAAE;QACzD,OAAO,gBAAgB,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,WAA+B,EAAE;QACzD,OAAO,gBAAgB,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAM,CAAC,GAAW,EAAE,WAA+B,EAAE;QACzD,OAAO,gBAAgB,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED,6EAA6E;IAC7E,KAAK,CAAC,SAAS,CAAC,GAAW,EAAE,WAA+B,EAAE;QAC5D,OAAO,gBAAgB,CAAC,cAAc,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;IAC1D,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,KAAK,CAAC,WAAW,CAAI,EAAoB,EAAE,IAAyB;QAClE,OAAO,wBAAwB,EAAE,CAAC,EAAE,EAAE,IAAI,CAAC,CAAA;IAC7C,CAAC;IAED;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,WAAW,CAAC,EAA8B;QAC9C,OAAO,wBAAwB,EAAE,CAAC,EAAE,CAAC,CAAA;IACvC,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,MAAM,CAAC,QAAuB;QAC5B,cAAc,CAAC,cAAc,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;IAC5C,CAAC;IAED,0EAA0E;IAC1E,GAAG,CAAC,KAAsB;QACxB,OAAO,GAAG,CAAC,KAAK,CAAC,CAAA;IACnB,CAAC;IAED;;;;;;;;;;;OAWG;IACH,UAAU,CAAC,IAAY;QACrB,MAAM,UAAU,GAAG,KAAK,IAAyB,EAAE,CAAC,yBAAyB,EAAE,CAAC,IAAI,CAAC,CAAA;QACrF,OAAO;YACL,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE;gBAC7B,OAAO,gBAAgB,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE;gBAC7B,OAAO,gBAAgB,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE;gBAC7B,OAAO,gBAAgB,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE;gBAC7B,OAAO,gBAAgB,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,SAAS,CAAC,GAAG,EAAE,QAAQ,GAAG,EAAE;gBAChC,OAAO,gBAAgB,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5D,CAAC;YACD,KAAK,CAAC,WAAW,CAAC,EAAE,EAAE,IAAI;gBACxB,OAAO,6BAA6B,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,CAAA;YACxD,CAAC;YACD,KAAK,CAAC,WAAW,CAAC,EAAE;gBAClB,OAAO,wBAAwB,EAAE,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC,CAAA;YAC7D,CAAC;YACD,KAAK,CAAC,MAAM,CAAC,QAAQ;gBACnB,cAAc,CAAC,MAAM,UAAU,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAA;YAC9C,CAAC;SACF,CAAA;IACH,CAAC;CACO,CAAA"}

package/dist/index.d.ts

@@ -1,8 +1,20 @@
 export { DB } from './db.js';
 export type { DBConnection } from './db.js';
 export { Expression, raw } from './expression.js';
-export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, __resetAdapterResolver, } from './registry-bridge.js';
-export type { TransactionRunner, ConnectionResolver, NamedTransactionRunner } from './registry-bridge.js';
+export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, registerAfterCommitRunner, resolveAfterCommitRunner, __resetAdapterResolver, } from './registry-bridge.js';
+export type { TransactionRunner, ConnectionResolver, NamedTransactionRunner, AfterCommitRunner } from './registry-bridge.js';
 export type { Row, Executor, Transaction, Connection } from './execution.js';
 export type { QueryEvent, QueryListener } from '@rudderjs/contracts';
+export { Migration } from './native/schema/migration.js';
+export { Schema, withSchema } from './native/schema/schema-facade.js';
+export { Migrator, discoverMigrations } from './native/schema/migrator.js';
+export { SchemaBuilder } from './native/schema/schema-builder.js';
+export { Blueprint } from './native/schema/blueprint.js';
+export { NativeAdapter, native } from './native/adapter.js';
+export type { NativeConfig, NativeDriverName } from './native/adapter.js';
+export { BetterSqlite3Driver } from './native/drivers/better-sqlite3.js';
+export { PostgresDriver } from './native/drivers/postgres.js';
+export { MysqlDriver } from './native/drivers/mysql.js';
+export type { Dialect } from './native/dialect.js';
+export type { Driver } from './native/driver.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAA;AACzG,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5E,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AAC3C,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAC7B,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAA;AAC5H,YAAY,EAAE,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAC5E,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAA;AAOpE,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAA;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAC3D,YAAY,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAA;AACzE,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA;AACvD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,YAAY,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/index.js

@@ -1,9 +1,28 @@
 // @rudderjs/database — the SQL data-layer foundation.
 //
-// PR1 establishes the package boundary + the public `DB` facade contract. The
-// query-builder breadth, connection manager, and native-engine internals land in
-// later PRs (see docs/plans/2026-06-01-database-package-extraction-PR1.md).
+// The `DB` facade + registry bridge (Phase 1, #823) and — since the Phase-2
+// relocation (docs/plans/2026-06-04-database-extraction-phase-2.md) — the
+// native SQL engine's home. The full engine surface lives on the node-only
+// `./native` subpath; the headline API apps touch (`Migration`, `Schema`,
+// `NativeAdapter`, the drivers) is re-exported below so
+// `import { Migration, Schema } from '@rudderjs/database'` is the canonical
+// migration-file form going forward (`@rudderjs/orm/native` keeps working as a
+// back-compat shim).
 export { DB } from './db.js';
 export { Expression, raw } from './expression.js';
-export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, __resetAdapterResolver, } from './registry-bridge.js';
+export { registerAdapterResolver, resolveAdapter, registerTransactionRunner, resolveTransactionRunner, registerConnectionResolver, resolveConnectionResolver, registerNamedTransactionRunner, resolveNamedTransactionRunner, registerAfterCommitRunner, resolveAfterCommitRunner, __resetAdapterResolver, } from './registry-bridge.js';
+// ─── Native engine — headline API ──────────────────────────
+// The full engine surface (compiler, dialects, schema internals, …) is on the
+// `./native` subpath; these are the names apps write daily. Node-only — this
+// main entry is not client-bundle-reachable (the orm-side `db-bridge` is only
+// imported from adapter providers).
+export { Migration } from './native/schema/migration.js';
+export { Schema, withSchema } from './native/schema/schema-facade.js';
+export { Migrator, discoverMigrations } from './native/schema/migrator.js';
+export { SchemaBuilder } from './native/schema/schema-builder.js';
+export { Blueprint } from './native/schema/blueprint.js';
+export { NativeAdapter, native } from './native/adapter.js';
+export { BetterSqlite3Driver } from './native/drivers/better-sqlite3.js';
+export { PostgresDriver } from './native/drivers/postgres.js';
+export { MysqlDriver } from './native/drivers/mysql.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,8EAA8E;AAC9E,iFAAiF;AACjF,4EAA4E;AAE5E,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAE5B,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,sBAAsB,GACvB,MAAM,sBAAsB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,sDAAsD;AACtD,EAAE;AACF,4EAA4E;AAC5E,0EAA0E;AAC1E,2EAA2E;AAC3E,0EAA0E;AAC1E,wDAAwD;AACxD,4EAA4E;AAC5E,+EAA+E;AAC/E,qBAAqB;AAErB,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAE5B,OAAO,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,iBAAiB,CAAA;AACjD,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,yBAAyB,EACzB,wBAAwB,EACxB,0BAA0B,EAC1B,yBAAyB,EACzB,8BAA8B,EAC9B,6BAA6B,EAC7B,yBAAyB,EACzB,wBAAwB,EACxB,sBAAsB,GACvB,MAAM,sBAAsB,CAAA;AAK7B,8DAA8D;AAC9D,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,oCAAoC;AACpC,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,kCAAkC,CAAA;AACrE,OAAO,EAAE,QAAQ,EAAE,kBAAkB,EAAE,MAAM,6BAA6B,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAA;AACjE,OAAO,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAA;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAE3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,oCAAoC,CAAA;AACxE,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAA;AAC7D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAA"}

package/dist/native/adapter.d.ts

@@ -0,0 +1,202 @@
+import type { OrmAdapter, OrmAdapterProvider, QueryBuilder, OrmAdapterQueryOpts, QueryListener, TransactionOptions } from '@rudderjs/contracts';
+import type { Dialect } from './dialect.js';
+import type { Driver, Row } from './driver.js';
+import type { ReadReplicaPicker } from './replica-picker.js';
+import { SchemaBuilder } from './schema/schema-builder.js';
+import type { ModelCastInfo } from './schema/schema-types.js';
+/** Supported native drivers. SQLite (better-sqlite3), Postgres (porsager
+ *  `postgres`), and MySQL (`mysql2`). */
+export type NativeDriverName = 'sqlite' | 'pg' | 'mysql';
+/** Config for {@link native} / {@link NativeAdapter.make}. */
+export interface NativeConfig {
+    /**
+     * Pre-built {@link Driver} — skips driver setup and HMR caching. Use for
+     * tests or hand-wired setups (you own the driver's lifecycle).
+     */
+    driverInstance?: Driver;
+    /** Dialect to pair with a {@link driverInstance}. Defaults to SQLite — pass
+     *  `new PgDialect()` when hand-wiring a Postgres driver. Ignored when a
+     *  built-in `driver` is named (that path picks the matching dialect). */
+    dialect?: Dialect;
+    /** Which built-in driver to open. Defaults to `'sqlite'`. */
+    driver?: NativeDriverName;
+    /**
+     * Connection URL / path. For SQLite: a file path, `file:` URL, or `':memory:'`.
+     * For Postgres: a `postgres://…` connection string. Falls back to
+     * `DATABASE_URL`, then `:memory:` (SQLite only — a Postgres driver with no URL
+     * fails fast with a clear connection error).
+     */
+    url?: string;
+    /** Default primary-key column for models that don't override it. */
+    primaryKey?: string;
+    /**
+     * The `config/database.ts` connection name this adapter serves (passed by
+     * the provider / ConnectionManager factory). Keys the dev-HMR driver cache
+     * so each named connection holds its own driver and a config edit disposes
+     * only that connection's superseded client. Omitted for standalone use.
+     */
+    connectionName?: string;
+    /**
+     * Read-replica URLs (read/write split). When set, un-locked SELECTs (and
+     * `selectRaw`) round-robin across these; writes, DDL, locked selects, and
+     * every transaction run on the write connection (`url`). Same driver as the
+     * write connection.
+     */
+    readUrls?: string[];
+    /**
+     * How reads pick a replica: `'round-robin'` (default), `'random'`, a
+     * weights array (one non-negative weight per replica, in `readUrls` order),
+     * or a custom `(count) => index` function. See {@link ReadReplicaPicker}.
+     * Only meaningful with `readUrls`.
+     */
+    readPicker?: ReadReplicaPicker;
+    /**
+     * Sticky reads: after a write on this connection within the current request
+     * scope (see `@rudderjs/orm/sticky`), subsequent reads in that scope route
+     * to the write connection — read-your-writes under replication lag. Only
+     * meaningful with `readUrls`.
+     */
+    sticky?: boolean;
+}
+export declare class NativeAdapter implements OrmAdapter {
+    /** Where a (nested) transaction is opened. Top-level: the {@link Driver};
+     *  scoped: the active {@link Transaction} (so nesting → SAVEPOINT). */
+    private readonly scope;
+    private readonly dialect;
+    private readonly primaryKey;
+    /** The owned connection — present only on the top-level adapter, `null` on
+     *  a transaction-scoped one (it must not close the shared connection). */
+    private readonly driver;
+    /** Query listeners (`onQuery` / `DB.listen`). Shared BY REFERENCE with every
+     *  transaction-scoped adapter spawned from this one, so a listener registered
+     *  on the top-level adapter also sees queries run inside `transaction()`. */
+    private readonly listeners;
+    /** Connection name reported on query events — the `config/database.ts`
+     *  connection name when the provider passed one, else the driver name
+     *  (`'sqlite'` / `'pg'` / `'mysql'`); `undefined` for a caller-supplied
+     *  {@link NativeConfig.driverInstance}. */
+    private readonly connection;
+    /** Read-replica drivers (read/write split). Owned by the top-level adapter
+     *  (closed by `disconnect()`); always empty on a transaction-scoped one. */
+    private readonly readDrivers;
+    /** Sticky reads enabled for this connection (only meaningful with a split). */
+    private readonly sticky;
+    /** Where queries run — the top-level connection, or a transaction scope,
+     *  wrapped with query-listener instrumentation (see {@link instrumentExecutor}). */
+    private readonly executor;
+    /** Read-executor picker — set only on a split connection (`readUrls`).
+     *  Strategy from `readPicker` (round-robin default). Returns the write
+     *  executor on a sticky hit. The QB calls it per read terminal; locked
+     *  selects bypass it (see `_readExecutor`). */
+    private readonly readPick;
+    private constructor();
+    /** `'write'` when this adapter participates in a read/write split (directly
+     *  or as a transaction scope spawned from one) — the query-event tag. */
+    private readonly splitTag;
+    /** Direct relations (`hasOne`/`hasMany`/`belongsTo`/`belongsToMany`) resolve
+     *  in the ORM's Model layer — one batched `WHERE … IN` per relation, stitched
+     *  onto the parents (same machinery as Drizzle and the polymorphic loader).
+     *  The native QB's own `with()` stays a warn-only no-op: the adapter contract
+     *  passes relation NAMES only, with no join shape to compile from. */
+    readonly eagerLoadStrategy: "model-layer";
+    /** Build a `NativeAdapter`, opening the configured driver (lazy import). */
+    static make(config?: NativeConfig): Promise<NativeAdapter>;
+    /** The adapter that owns the connection — queries and transactions both run
+     *  on `driver`; `disconnect()` may close it. */
+    private static _topLevel;
+    query<T>(table: string, opts?: OrmAdapterQueryOpts): QueryBuilder<T>;
+    /**
+     * Raw `SELECT` for the `DB` facade (`DB.select`) — on a split connection
+     * routes to the read pool (sticky-aware, Laravel parity for `DB::select`);
+     * otherwise runs on this adapter's executor (the top-level connection, or
+     * the transaction scope when inside `transaction()`).
+     */
+    selectRaw(sql: string, bindings: readonly unknown[]): Promise<Row[]>;
+    /**
+     * Raw writing statement for the `DB` facade (`DB.insert`/`update`/`delete`/
+     * `statement`). On SQLite/Postgres the caller's `RETURNING *` makes
+     * `Executor.execute` resolve to the affected rows, so the count is
+     * `rows.length`. On MySQL (no RETURNING) the affected count comes from the
+     * driver's result metadata via {@link AffectingExecutor} instead.
+     */
+    affectingStatement(sql: string, bindings: readonly unknown[]): Promise<number>;
+    /**
+     * A {@link SchemaBuilder} bound to this adapter's connection — the DDL surface
+     * the migration runner drives. Runs on the same executor as queries, so a
+     * transaction-scoped adapter's schema builder participates in the transaction.
+     */
+    schemaBuilder(): SchemaBuilder;
+    /**
+     * A {@link SchemaBuilder} bound to a *recording* executor: every statement it
+     * would run is handed to `record` instead of touching the database. Powers
+     * `migrate --pretend` — the migrator binds this to a migration's `up()` and
+     * collects the DDL it would emit. Catalog reads (`hasTable`/`hasColumn`)
+     * resolve to "absent" (empty rows), which is the correct dry-run default.
+     */
+    pretendSchemaBuilder(record: (sql: string, bindings: readonly unknown[]) => void): SchemaBuilder;
+    /**
+     * Generate `app/Models/__schema/registry.d.ts` from THIS connection's live
+     * schema (GATE 7-types) — introspect every table, fold in each model's
+     * declared `casts`, and (re)write the registry. Node-only; the fs-writing
+     * orchestrator is lazily imported so the adapter's static eval graph stays
+     * import-light. Returns the written path + table count for the CLI to report.
+     */
+    generateSchemaTypes(cwd: string, models?: ModelCastInfo[]): Promise<{
+        path: string;
+        tableCount: number;
+    }>;
+    /**
+     * Database overview for `rudder db:show` — dialect, version, database name,
+     * and every user table (with sizes where the dialect can report them, row
+     * counts/views on request). Lazily imported like {@link generateSchemaTypes}
+     * to keep the adapter's static eval graph import-light.
+     */
+    inspectDatabase(opts?: {
+        counts?: boolean;
+        views?: boolean;
+    }): Promise<import('./schema/inspect.js').DatabaseInfo>;
+    /**
+     * Single-table detail for `rudder db:table <name>` — columns, indexes,
+     * foreign keys, row count. Null when the table doesn't exist.
+     */
+    inspectTable(table: string): Promise<import('./schema/inspect.js').TableInfo | null>;
+    /**
+     * Run `fn` inside a transaction (or a SAVEPOINT when already inside one),
+     * passing it a transaction-scoped `NativeAdapter` whose queries execute on the
+     * transaction's connection. The Model layer threads that scoped adapter
+     * through `AsyncLocalStorage` so existing `Model.query()` calls inside `fn`
+     * transparently join the transaction. Commits on resolve; rolls back and
+     * re-throws on reject.
+     *
+     * `opts.isolationLevel` is forwarded to the driver: SET TRANSACTION ISOLATION
+     * LEVEL at transaction start on Postgres/MySQL; SQLite throws (no isolation
+     * levels); any driver throws when this scope is already a SAVEPOINT.
+     */
+    transaction<T>(fn: (tx: OrmAdapter) => Promise<T>, opts?: TransactionOptions): Promise<T>;
+    /**
+     * Register a query listener ({@link OrmAdapter.onQuery}) — fired once per
+     * successfully executed query with the SQL, bindings, and wall-clock duration
+     * in ms. The app-facing entry point is `DB.listen()` (`@rudderjs/database`);
+     * Telescope's QueryCollector and Pulse's slow-query recorder hook in here too.
+     * Listener errors are swallowed — they never break the query. Registering on
+     * a transaction-scoped adapter registers on the shared (top-level) listener
+     * list. Transaction control statements (BEGIN/COMMIT/SAVEPOINT) run inside
+     * the driver and are not reported.
+     */
+    onQuery(listener: QueryListener): void;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+}
+/**
+ * Build the native ORM adapter provider — the `OrmAdapterProvider` shape the
+ * database provider consumes (mirrors `drizzle(...)` / the prisma factory).
+ *
+ * @example
+ * import { native } from '@rudderjs/database'
+ * database({
+ *   default: 'main',
+ *   connections: { main: native({ driver: 'sqlite', url: 'file:./dev.db' }) },
+ * })
+ */
+export declare function native(config?: NativeConfig): OrmAdapterProvider;
+//# sourceMappingURL=adapter.d.ts.map

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

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