@c9up/atlas 0.2.0 → 0.2.1

package/dist/services/db.d.ts

@@ -12,17 +12,121 @@
  * swap in a custom `AsyncDatabaseConnection` through the provider's
  * container hooks).
  */
+import type { ConnectionConfig } from "../AtlasProvider.js";
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import { ConnectionManager } from "../ConnectionManager.js";
+import { DatabaseQueryBuilder, type QueryExecutor } from "../query/DatabaseQueryBuilder.js";
+import type { AtlasDialect } from "../query/native.js";
 import { RawSql } from "../query/QueryBuilder.js";
-/** The `db` singleton surface: the bound connection plus the AdonisJS-style `db.raw()` builder. */
-export interface DbService extends AsyncDatabaseConnection {
+import { RawQueryBuilder } from "../query/RawQueryBuilder.js";
+/** Options accepted by the Lucid query-builder entry points. */
+export interface DbQueryOptions {
+    /** Route the query through this transaction client (Lucid `{ client: trx }`). */
+    client?: QueryExecutor;
+    /** `'read'` rejects writes on this builder (Lucid `db.query({ mode: 'read' })`). */
+    mode?: "read" | "write";
+}
+/** Options for {@link DbService.connection} (Lucid read/write replica routing). */
+export interface ConnectionOptions {
     /**
-     * Build a raw SQL expression — AdonisJS `db.raw()` / `Database.raw()`. Use it
-     * for query fragments and for column defaults that are SQL expressions:
+     * `'read'` scopes the returned service to reads: its query builders reject
+     * writes (insert/update/delete/increment/decrement). `'write'` (default) is
+     * unrestricted. Atlas has no replica pool, so `mode` is a write-guard rather
+     * than a routing hint — the guard is the security-relevant half of Lucid's
+     * read/write modes.
+     */
+    mode?: "read" | "write";
+}
+/**
+ * The `db` service surface — Adonis Lucid's `Database` service. Exposes the
+ * query builders (`query`/`from`/`table`/`insertQuery`), raw execution
+ * (`rawQuery`), the `raw()` fragment builder, connection scoping (`connection`),
+ * and the transaction/DDL methods forwarded from the bound connection.
+ */
+export interface DbService {
+    /** A connection-level query builder (Lucid `db.query()`), optionally on a trx. */
+    query(options?: DbQueryOptions): DatabaseQueryBuilder;
+    /** Query builder with the table pre-selected (Lucid `db.from(table)`). */
+    from(table: string): DatabaseQueryBuilder;
+    /**
+     * Query builder on a derived-table source (Lucid `db.from(subquery, alias)`) —
+     * a builder OR a callback that builds one.
+     */
+    from(subquery: DatabaseQueryBuilder | ((query: DatabaseQueryBuilder) => void), alias?: string): DatabaseQueryBuilder;
+    /** Insert/write builder with the table pre-selected (Lucid `db.table(table)`). */
+    table(table: string): DatabaseQueryBuilder;
+    /** An insert builder (Lucid `db.insertQuery()`), optionally on a trx. */
+    insertQuery(options?: DbQueryOptions): DatabaseQueryBuilder;
+    /**
+     * A chainable raw query (Lucid `db.rawQuery(sql, bindings)`). Thenable — can be
+     * awaited directly — and exposes `toSQL`/`toQuery`/`debug`/`timeout`/
+     * `reporterData`. Bindings may be positional (`?`/`??`) or named (`:name`/`:name:`).
+     */
+    rawQuery<T = Record<string, unknown>>(sql: string, bindings?: unknown[] | Record<string, unknown>): RawQueryBuilder<T>;
+    /**
+     * Scope the service to a connection (Lucid `db.connection(name)`). Called with
+     * no name it returns the default connection's service (Lucid `db.connection()`).
+     * Pass `{ mode: 'read' }` to reject writes on the returned service (Lucid
+     * `db.connection(name, { mode: 'read' })`).
+     */
+    connection(name?: string, options?: ConnectionOptions): DbService;
+    /**
+     * Query builder for a model whose class is resolved at runtime (Lucid
+     * `db.modelQuery(Model)`). For static code prefer `Model.query()` directly.
+     */
+    modelQuery<Q>(model: {
+        query(): Q;
+    }): Q;
+    /**
+     * Build a raw SQL expression — AdonisJS `db.raw()`. For query fragments and
+     * column defaults that are SQL expressions:
      *
      *   t.uuid('id').defaultTo(db.raw('gen_random_uuid()'))
+     *
+     * Bindings may be positional (`?`/`??`) or named (`:name`/`:name:`).
+     */
+    raw(sql: string, params?: unknown[] | Record<string, unknown>): RawSql;
+    /**
+     * A column reference — Adonis Lucid `db.ref('posts.created_at')`. Use it where
+     * a value position must be read as a column (e.g. `orderBy(db.ref(col), 'desc')`).
+     * The identifier is validated and dialect-quoted; it is NOT a value binding.
+     */
+    ref(column: string): RawSql;
+    /** Run a statement for effect (forwarded to the connection). */
+    execute(sql: string, params?: unknown[]): Promise<{
+        rowsAffected: number;
+    }>;
+    /** Managed/manual interactive transaction (forwarded, Lucid `db.transaction`). */
+    transaction: AsyncDatabaseConnection["transaction"];
+    /** Atomic batch (forwarded). */
+    runInTransaction: AsyncDatabaseConnection["runInTransaction"];
+    /**
+     * Empty a table (Lucid `truncate`). `TRUNCATE TABLE` on Postgres/MySQL (with
+     * `CASCADE` when `cascade` is set, Postgres only); `DELETE FROM` on SQLite,
+     * which has no `TRUNCATE`.
      */
-    raw(sql: string, params?: unknown[]): RawSql;
+    truncate(table: string, cascade?: boolean): Promise<void>;
+    /**
+     * Empty every user table (Lucid `truncateAllTables`). Framework tables
+     * (`ream_*`) and dialect internals are left alone; pass `ignoreTables` to spare
+     * more. Foreign keys are suspended so delete order doesn't matter.
+     */
+    truncateAllTables(ignoreTables?: readonly string[]): Promise<void>;
+    /**
+     * Try to acquire a session-level advisory lock, non-blocking (Lucid
+     * `getAdvisoryLock`). Postgres `pg_try_advisory_lock`, MySQL `GET_LOCK(key, 0)`.
+     * A string key is hashed to the integer Postgres requires. Returns whether the
+     * lock was acquired. **Throws on SQLite** (no advisory locks — Lucid parity).
+     */
+    getAdvisoryLock(key: string | number): Promise<boolean>;
+    /** Release an advisory lock taken with {@link getAdvisoryLock}. Throws on SQLite. */
+    releaseAdvisoryLock(key: string | number): Promise<boolean>;
+    /** The full Lucid connection manager (`add`/`connect`/`patch`/`release`/nodes/events). */
+    readonly manager: ConnectionManager;
+    /** The bound connection's dialect. */
+    readonly dialect: AtlasDialect;
+    ping(): Promise<void>;
+    close(): Promise<void>;
 }
 /** @internal Bind the singleton (called by AtlasProvider). */
 export declare function setDb(connection: AsyncDatabaseConnection): void;
@@ -35,12 +139,19 @@ export declare function setDb(connection: AsyncDatabaseConnection): void;
 export declare function clearDb(connection: AsyncDatabaseConnection): void;
 /** @internal Read the singleton (or `undefined` pre-boot). */
 export declare function getDb(): AsyncDatabaseConnection | undefined;
-/** @internal Register a named connection (called by AtlasProvider.boot per connection). */
-export declare function registerConnection(name: string, connection: AsyncDatabaseConnection): void;
-/** @internal Unregister a named connection IF it still points at `connection`. */
+/**
+ * @internal Register an already-open named connection (called by AtlasProvider,
+ * which opens connections itself). Records the config on the node too.
+ */
+export declare function registerConnection(name: string, connection: AsyncDatabaseConnection, config?: ConnectionConfig): void;
+/** @internal Unregister a named connection IF it still points at `connection` (no close). */
 export declare function unregisterConnection(name: string, connection: AsyncDatabaseConnection): void;
-/** @internal Resolve a named connection (for `BaseModel.connection`), or `undefined`. */
+/** @internal Resolve a live named connection (for `BaseModel.connection`), or `undefined`. */
 export declare function getConnection(name: string): AsyncDatabaseConnection | undefined;
+/** @internal The shared connection manager (for the AtlasProvider lifecycle-event bridge). */
+export declare function connectionManager(): ConnectionManager;
+/** Build a {@link DbService} over a resolver that yields the live connection. */
+export declare function createDbService(resolve: () => AsyncDatabaseConnection, readOnly?: boolean): DbService;
 declare const db: DbService;
 export default db;
 //# sourceMappingURL=db.d.ts.map

package/dist/services/db.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/services/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAC5E,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAElD,mGAAmG;AACnG,MAAM,WAAW,SAAU,SAAQ,uBAAuB;IACzD;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC;CAC7C;AAID,8DAA8D;AAC9D,wBAAgB,KAAK,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAE/D;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,UAAU,EAAE,uBAAuB,GAAG,IAAI,CAEjE;AAED,8DAA8D;AAC9D,wBAAgB,KAAK,IAAI,uBAAuB,GAAG,SAAS,CAE3D;AAOD,2FAA2F;AAC3F,wBAAgB,kBAAkB,CACjC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,uBAAuB,GACjC,IAAI,CAEN;AAED,kFAAkF;AAClF,wBAAgB,oBAAoB,CACnC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,uBAAuB,GACjC,IAAI,CAEN;AAED,yFAAyF;AACzF,wBAAgB,aAAa,CAC5B,IAAI,EAAE,MAAM,GACV,uBAAuB,GAAG,SAAS,CAErC;AAED,QAAA,MAAM,EAAE,EAAE,SAiBR,CAAC;AAEH,eAAe,EAAE,CAAC"}
+{"version":3,"file":"db.d.ts","sourceRoot":"","sources":["../../src/services/db.ts"],"names":[],"mappings":"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"}

package/dist/services/db.js

@@ -12,7 +12,11 @@
  * swap in a custom `AsyncDatabaseConnection` through the provider's
  * container hooks).
  */
+import { ConnectionManager } from "../ConnectionManager.js";
+import { DatabaseQueryBuilder, } from "../query/DatabaseQueryBuilder.js";
 import { RawSql } from "../query/QueryBuilder.js";
+import { RawQueryBuilder, resolveRawBindings, } from "../query/RawQueryBuilder.js";
+import { truncateAll } from "../testing/DatabaseCleanup.js";
 let instance;
 /** @internal Bind the singleton (called by AtlasProvider). */
 export function setDb(connection) {
@@ -32,38 +36,190 @@ export function clearDb(connection) {
 export function getDb() {
     return instance;
 }
-// Named-connection registry — backs `BaseModel.connection = 'analytics'` so a
-// model can resolve a non-default connection from a plain import (AdonisJS
-// `static connection`). Populated by AtlasProvider for every opened connection.
-const namedConnections = new Map();
-/** @internal Register a named connection (called by AtlasProvider.boot per connection). */
-export function registerConnection(name, connection) {
-    namedConnections.set(name, connection);
+// The shared connection manager (Lucid `db.manager`) — the single owner of named
+// connections. Backs `BaseModel.connection = 'analytics'` so a model resolves a
+// non-default connection from a plain import (AdonisJS `static connection`).
+const manager = new ConnectionManager();
+/**
+ * @internal Register an already-open named connection (called by AtlasProvider,
+ * which opens connections itself). Records the config on the node too.
+ */
+export function registerConnection(name, connection, config = {}) {
+    manager.register(name, config, connection);
 }
-/** @internal Unregister a named connection IF it still points at `connection`. */
+/** @internal Unregister a named connection IF it still points at `connection` (no close). */
 export function unregisterConnection(name, connection) {
-    if (namedConnections.get(name) === connection)
-        namedConnections.delete(name);
+    manager.deregister(name, connection);
 }
-/** @internal Resolve a named connection (for `BaseModel.connection`), or `undefined`. */
+/** @internal Resolve a live named connection (for `BaseModel.connection`), or `undefined`. */
 export function getConnection(name) {
-    return namedConnections.get(name);
+    return manager.connection(name);
 }
-const db = new Proxy({}, {
-    get(_target, prop) {
-        // `raw` is a pure builder (no connection needed) — available pre-boot too.
-        if (prop === "raw") {
-            return (sql, params = []) => new RawSql(sql, params);
-        }
-        if (!instance) {
-            throw new Error("[atlas] db singleton accessed before AtlasProvider.boot() ran. " +
-                "Check that `@c9up/atlas/provider` is listed in your reamrc.ts " +
-                "providers and that `config/database.ts` defines at least one " +
-                "connection.");
+/** @internal The shared connection manager (for the AtlasProvider lifecycle-event bridge). */
+export function connectionManager() {
+    return manager;
+}
+/**
+ * Coerce an advisory-lock key to the integer Postgres `pg_*_advisory_lock`
+ * requires. Numeric keys pass through; string keys are hashed deterministically
+ * (FNV-1a, 32-bit) so lock and unlock agree. Stable within a process is all that
+ * matters — atlas never shares a lock namespace with Knex.
+ */
+function advisoryLockKey(key) {
+    if (typeof key === "number")
+        return Math.trunc(key);
+    let hash = 0x811c9dc5;
+    for (let i = 0; i < key.length; i++) {
+        hash ^= key.charCodeAt(i);
+        hash = Math.imul(hash, 0x01000193);
+    }
+    return hash | 0; // signed 32-bit — fits Postgres int/bigint
+}
+/** Validate + dialect-quote a (dot-qualified) identifier. Rejects anything unsafe. */
+function quoteIdent(name, dialect) {
+    const q = dialect === "mysql" ? "`" : '"';
+    return name
+        .split(".")
+        .map((seg) => {
+        if (seg === "*")
+            return seg;
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(seg)) {
+            throw new Error(`atlas: invalid identifier segment '${seg}' in '${name}'`);
         }
-        const value = Reflect.get(instance, prop, instance);
-        return typeof value === "function" ? value.bind(instance) : value;
-    },
+        return `${q}${seg}${q}`;
+    })
+        .join(".");
+}
+/** Build a {@link DbService} over a resolver that yields the live connection. */
+export function createDbService(resolve, readOnly = false) {
+    const opts = readOnly ? { readOnly } : undefined;
+    // Per-call `{ mode: 'read' }` also yields a write-guarded builder, even on an
+    // unscoped service (Lucid `db.query({ mode: 'read' })`).
+    const optsFor = (options) => readOnly || options?.mode === "read" ? { readOnly: true } : undefined;
+    return {
+        query(options) {
+            const conn = resolve();
+            return new DatabaseQueryBuilder(options?.client ?? conn, conn.dialect, "", optsFor(options));
+        },
+        from(source, alias) {
+            const conn = resolve();
+            const builder = new DatabaseQueryBuilder(conn, conn.dialect, "", opts);
+            return typeof source === "string"
+                ? builder.from(source)
+                : builder.from(source, alias);
+        },
+        table(table) {
+            const conn = resolve();
+            return new DatabaseQueryBuilder(conn, conn.dialect, table, opts);
+        },
+        insertQuery(options) {
+            const conn = resolve();
+            return new DatabaseQueryBuilder(options?.client ?? conn, conn.dialect, "", optsFor(options));
+        },
+        rawQuery(sql, bindings = []) {
+            const conn = resolve();
+            return new RawQueryBuilder(conn, conn.dialect, sql, bindings);
+        },
+        connection(name, connOptions) {
+            // No name → the default connection's service (Lucid `db.connection()`).
+            if (name === undefined) {
+                return createDbService(resolve, connOptions?.mode === "read");
+            }
+            return createDbService(() => {
+                const conn = getConnection(name);
+                if (!conn) {
+                    throw new Error(`[atlas] no connection registered under '${name}'. Is it in config/database.ts connections?`);
+                }
+                return conn;
+            }, connOptions?.mode === "read");
+        },
+        modelQuery(model) {
+            return model.query();
+        },
+        raw(sql, params = []) {
+            // Resolve `??`/named bindings only when present, so the common
+            // positional/no-binding path (and Postgres `::casts`) is untouched.
+            const hasNamed = !Array.isArray(params);
+            const hasIdent = typeof sql === "string" && sql.includes("??");
+            if (!hasNamed && !hasIdent) {
+                return new RawSql(sql, params);
+            }
+            const resolved = resolveRawBindings(sql, params, resolve().dialect);
+            return new RawSql(resolved.sql, resolved.params);
+        },
+        ref(column) {
+            return new RawSql(quoteIdent(column, resolve().dialect), []);
+        },
+        async truncate(table, cascade) {
+            const conn = resolve();
+            const t = quoteIdent(table, conn.dialect);
+            // SQLite has no TRUNCATE — DELETE clears the table (Lucid does the same).
+            const sql = conn.dialect === "sqlite"
+                ? `DELETE FROM ${t}`
+                : conn.dialect === "postgres"
+                    ? `TRUNCATE TABLE ${t}${cascade ? " CASCADE" : ""}`
+                    : `TRUNCATE TABLE ${t}`;
+            await conn.execute(sql, []);
+        },
+        truncateAllTables(ignoreTables = []) {
+            return truncateAll(resolve(), ignoreTables);
+        },
+        async getAdvisoryLock(key) {
+            const conn = resolve();
+            if (conn.dialect === "sqlite") {
+                throw new Error("[atlas] advisory locks are not supported on SQLite (Postgres/MySQL only).");
+            }
+            if (conn.dialect === "postgres") {
+                const rows = await conn.query("SELECT pg_try_advisory_lock($1) AS locked", [advisoryLockKey(key)]);
+                return Boolean(rows[0]?.locked);
+            }
+            // MySQL: GET_LOCK(name, 0) → non-blocking try (1 acquired, 0 busy).
+            const rows = await conn.query("SELECT GET_LOCK(?, 0) AS locked", [String(key)]);
+            return Number(rows[0]?.locked) === 1;
+        },
+        async releaseAdvisoryLock(key) {
+            const conn = resolve();
+            if (conn.dialect === "sqlite") {
+                throw new Error("[atlas] advisory locks are not supported on SQLite (Postgres/MySQL only).");
+            }
+            if (conn.dialect === "postgres") {
+                const rows = await conn.query("SELECT pg_advisory_unlock($1) AS released", [advisoryLockKey(key)]);
+                return Boolean(rows[0]?.released);
+            }
+            const rows = await conn.query("SELECT RELEASE_LOCK(?) AS released", [String(key)]);
+            return Number(rows[0]?.released) === 1;
+        },
+        get manager() {
+            return manager;
+        },
+        execute(sql, params) {
+            return resolve().execute(sql, params);
+        },
+        get transaction() {
+            return resolve().transaction?.bind(resolve());
+        },
+        runInTransaction(batch) {
+            return resolve().runInTransaction(batch);
+        },
+        get dialect() {
+            return resolve().dialect;
+        },
+        ping() {
+            return resolve().ping();
+        },
+        close() {
+            return resolve().close();
+        },
+    };
+}
+const db = createDbService(() => {
+    if (!instance) {
+        throw new Error("[atlas] db singleton accessed before AtlasProvider.boot() ran. " +
+            "Check that `@c9up/atlas/provider` is listed in your reamrc.ts " +
+            "providers and that `config/database.ts` defines at least one " +
+            "connection.");
+    }
+    return instance;
 });
 export default db;
 //# sourceMappingURL=db.js.map

package/dist/services/db.js.map

@@ -1 +1 @@
-{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/services/db.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,MAAM,EAAE,MAAM,0BAA0B,CAAC;AAalD,IAAI,QAA6C,CAAC;AAElD,8DAA8D;AAC9D,MAAM,UAAU,KAAK,CAAC,UAAmC;IACxD,QAAQ,GAAG,UAAU,CAAC;AACvB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,UAAmC;IAC1D,IAAI,QAAQ,KAAK,UAAU;QAAE,QAAQ,GAAG,SAAS,CAAC;AACnD,CAAC;AAED,8DAA8D;AAC9D,MAAM,UAAU,KAAK;IACpB,OAAO,QAAQ,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,2EAA2E;AAC3E,gFAAgF;AAChF,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAAmC,CAAC;AAEpE,2FAA2F;AAC3F,MAAM,UAAU,kBAAkB,CACjC,IAAY,EACZ,UAAmC;IAEnC,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,oBAAoB,CACnC,IAAY,EACZ,UAAmC;IAEnC,IAAI,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,UAAU;QAAE,gBAAgB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;AAC9E,CAAC;AAED,yFAAyF;AACzF,MAAM,UAAU,aAAa,CAC5B,IAAY;IAEZ,OAAO,gBAAgB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACnC,CAAC;AAED,MAAM,EAAE,GAAc,IAAI,KAAK,CAAC,EAAe,EAAE;IAChD,GAAG,CAAC,OAAO,EAAE,IAAI;QAChB,2EAA2E;QAC3E,IAAI,IAAI,KAAK,KAAK,EAAE,CAAC;YACpB,OAAO,CAAC,GAAW,EAAE,SAAoB,EAAE,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;QACD,IAAI,CAAC,QAAQ,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACd,iEAAiE;gBAChE,gEAAgE;gBAChE,+DAA+D;gBAC/D,aAAa,CACd,CAAC;QACH,CAAC;QACD,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,EAAE,QAAQ,CAAC,CAAC;QACpD,OAAO,OAAO,KAAK,KAAK,UAAU,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;IACnE,CAAC;CACD,CAAC,CAAC;AAEH,eAAe,EAAE,CAAC"}
+{"version":3,"file":"db.js","sourceRoot":"","sources":["../../src/services/db.ts"],"names":[],"mappings":"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"}

package/dist/testing/DatabaseCleanup.d.ts

@@ -4,19 +4,42 @@
  * @implements MISS-19
  */
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
+import type { TransactionClient } from "../Transaction.js";
+/** What {@link useTransaction} hands back: the pinned trx plus its teardown. */
+export interface TestTransaction {
+    /**
+     * The interactive transaction, pinned to ONE pooled connection. Run every
+     * query the test makes through THIS handle (`trx.query` / `trx.execute`, or
+     * `repo.useTransaction(trx)`), never the pooled `db` — that is what makes the
+     * rollback isolate the test.
+     */
+    trx: TransactionClient;
+    /** Roll everything the test did back and return the connection to the pool. */
+    rollback: () => Promise<void>;
+}
 /**
- * Wrap a test in a savepoint that is rolled back after.
+ * Isolate a test by running it inside a transaction that is rolled back after
+ * (Adonis Lucid parity — Lucid's tests use `db.transaction()` the same way).
+ *
+ * The earlier implementation issued `SAVEPOINT` / `ROLLBACK` through the pooled
+ * `db`, so with `poolMax > 1` the savepoint and its rollback — and the test's
+ * own queries — could each land on a DIFFERENT pooled connection, and the
+ * "isolation" silently did nothing. This pins a single interactive transaction
+ * instead: every query on the returned `trx` runs on that one connection, and
+ * `rollback()` reverts them together, correctly on any pool size.
  */
-export declare function useTransaction(db: AsyncDatabaseConnection): Promise<() => Promise<void>>;
+export declare function useTransaction(db: AsyncDatabaseConnection): Promise<TestTransaction>;
 /**
  * Empty every user table (leaves `ream_*` framework tables and dialect
  * internals alone). Works on all three dialects — the table list comes from the
  * shared dialect-aware catalog helper, not a SQLite-only `sqlite_master` query.
  *
  * Foreign keys are suspended for the duration so the delete order doesn't
- * matter, and restored even if a statement throws. The row removal itself goes
- * through the Rust compiler (`DELETE` — cross-dialect and transaction-friendly,
- * unlike `TRUNCATE` which auto-commits on MySQL).
+ * matter. The FK toggle and every DELETE run on ONE pinned connection (via
+ * `runWithoutForeignKeys` → `runInTransaction`), so a connection pool can't
+ * scatter the connection-local `PRAGMA`/`SET` away from the deletes. The row
+ * removal goes through the Rust compiler (`DELETE` — cross-dialect, unlike
+ * `TRUNCATE` which auto-commits on MySQL).
  */
-export declare function truncateAll(db: AsyncDatabaseConnection): Promise<void>;
+export declare function truncateAll(db: AsyncDatabaseConnection, ignoreTables?: readonly string[]): Promise<void>;
 //# sourceMappingURL=DatabaseCleanup.d.ts.map

package/dist/testing/DatabaseCleanup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DatabaseCleanup.d.ts","sourceRoot":"","sources":["../../src/testing/DatabaseCleanup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAI5E;;GAEG;AACH,wBAAsB,cAAc,CACnC,EAAE,EAAE,uBAAuB,GACzB,OAAO,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,CAM9B;AAED;;;;;;;;;GASG;AACH,wBAAsB,WAAW,CAAC,EAAE,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAe5E"}
+{"version":3,"file":"DatabaseCleanup.d.ts","sourceRoot":"","sources":["../../src/testing/DatabaseCleanup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AAI5E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,gFAAgF;AAChF,MAAM,WAAW,eAAe;IAC/B;;;;;OAKG;IACH,GAAG,EAAE,iBAAiB,CAAC;IACvB,+EAA+E;IAC/E,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CACnC,EAAE,EAAE,uBAAuB,GACzB,OAAO,CAAC,eAAe,CAAC,CAc1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,WAAW,CAChC,EAAE,EAAE,uBAAuB,EAC3B,YAAY,GAAE,SAAS,MAAM,EAAO,GAClC,OAAO,CAAC,IAAI,CAAC,CA+Bf"}

package/dist/testing/DatabaseCleanup.js

@@ -3,17 +3,30 @@
  *
  * @implements MISS-19
  */
+import { AtlasError } from "../errors.js";
 import { compileStatementNative } from "../query/native.js";
-import { listUserTables, withoutForeignKeys } from "../schema/catalog.js";
+import { listUserTables, runWithoutForeignKeys } from "../schema/catalog.js";
 /**
- * Wrap a test in a savepoint that is rolled back after.
+ * Isolate a test by running it inside a transaction that is rolled back after
+ * (Adonis Lucid parity — Lucid's tests use `db.transaction()` the same way).
+ *
+ * The earlier implementation issued `SAVEPOINT` / `ROLLBACK` through the pooled
+ * `db`, so with `poolMax > 1` the savepoint and its rollback — and the test's
+ * own queries — could each land on a DIFFERENT pooled connection, and the
+ * "isolation" silently did nothing. This pins a single interactive transaction
+ * instead: every query on the returned `trx` runs on that one connection, and
+ * `rollback()` reverts them together, correctly on any pool size.
  */
 export async function useTransaction(db) {
-    await db.execute("SAVEPOINT test_savepoint");
-    return async () => {
-        await db.execute("ROLLBACK TO SAVEPOINT test_savepoint");
-        await db.execute("RELEASE SAVEPOINT test_savepoint");
-    };
+    if (typeof db.transaction !== "function") {
+        throw new AtlasError("E_NO_INTERACTIVE_TRANSACTION", "useTransaction() needs a connection with an interactive transaction() (a real napi connection); this adapter has none.", {
+            hint: "Use createNapiConnection(), or drive rollback yourself if your adapter can't pin a connection.",
+        });
+    }
+    // Manual (callback-less) mode: a pinned TransactionClient the test drives and
+    // tears down via rollback() — no cross-pool savepoint scatter.
+    const trx = await db.transaction();
+    return { trx, rollback: () => trx.rollback() };
 }
 /**
  * Empty every user table (leaves `ream_*` framework tables and dialect
@@ -21,22 +34,36 @@ export async function useTransaction(db) {
  * shared dialect-aware catalog helper, not a SQLite-only `sqlite_master` query.
  *
  * Foreign keys are suspended for the duration so the delete order doesn't
- * matter, and restored even if a statement throws. The row removal itself goes
- * through the Rust compiler (`DELETE` — cross-dialect and transaction-friendly,
- * unlike `TRUNCATE` which auto-commits on MySQL).
+ * matter. The FK toggle and every DELETE run on ONE pinned connection (via
+ * `runWithoutForeignKeys` → `runInTransaction`), so a connection pool can't
+ * scatter the connection-local `PRAGMA`/`SET` away from the deletes. The row
+ * removal goes through the Rust compiler (`DELETE` — cross-dialect, unlike
+ * `TRUNCATE` which auto-commits on MySQL).
  */
-export async function truncateAll(db) {
+export async function truncateAll(db, ignoreTables = []) {
     // The connection's own dialect, not the module default — correct even when
     // an app runs several connections on different engines.
     const dialect = db.dialect;
-    const tables = await listUserTables(db, dialect);
+    const ignore = new Set(ignoreTables);
+    const tables = (await listUserTables(db, dialect)).filter((t) => !ignore.has(t));
     if (tables.length === 0)
         return;
-    await withoutForeignKeys(db, dialect, async () => {
-        for (const name of tables) {
-            const compiled = compileStatementNative({ kind: "delete", table: name, wheres: [] }, dialect);
-            await db.execute(compiled.statements[0], compiled.params);
-        }
+    // Postgres: a plain DELETE respects FKs immediately (atlas FKs aren't
+    // DEFERRABLE), so deleting a parent before its children raises 23503 — and
+    // nothing orders the tables. `TRUNCATE … CASCADE` is transactional on pg,
+    // order-independent, and needs no session-level FK toggle to leak. (Names
+    // come from the DB catalog; quote them for identifiers with embedded quotes.)
+    if (dialect === "postgres") {
+        const list = tables.map((t) => `"${t.replace(/"/g, '""')}"`).join(", ");
+        await db.execute(`TRUNCATE ${list} RESTART IDENTITY CASCADE`);
+        return;
+    }
+    // MySQL/SQLite: DELETE (TRUNCATE auto-commits on MySQL, breaking test
+    // transaction isolation), with FK suspension on ONE pinned connection.
+    const statements = tables.map((name) => {
+        const compiled = compileStatementNative({ kind: "delete", table: name, wheres: [] }, dialect);
+        return { sql: compiled.statements[0], params: compiled.params };
     });
+    await runWithoutForeignKeys(db, dialect, statements);
 }
 //# sourceMappingURL=DatabaseCleanup.js.map

package/dist/testing/DatabaseCleanup.js.map

@@ -1 +1 @@
-{"version":3,"file":"DatabaseCleanup.js","sourceRoot":"","sources":["../../src/testing/DatabaseCleanup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1E;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,EAA2B;IAE3B,MAAM,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC;IAC7C,OAAO,KAAK,IAAI,EAAE;QACjB,MAAM,EAAE,CAAC,OAAO,CAAC,sCAAsC,CAAC,CAAC;QACzD,MAAM,EAAE,CAAC,OAAO,CAAC,kCAAkC,CAAC,CAAC;IACtD,CAAC,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,EAA2B;IAC5D,2EAA2E;IAC3E,wDAAwD;IACxD,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;IAC3B,MAAM,MAAM,GAAG,MAAM,cAAc,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC;IACjD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAChC,MAAM,kBAAkB,CAAC,EAAE,EAAE,OAAO,EAAE,KAAK,IAAI,EAAE;QAChD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;YAC3B,MAAM,QAAQ,GAAG,sBAAsB,CACtC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAC3C,OAAO,CACP,CAAC;YACF,MAAM,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC3D,CAAC;IACF,CAAC,CAAC,CAAC;AACJ,CAAC"}
+{"version":3,"file":"DatabaseCleanup.js","sourceRoot":"","sources":["../../src/testing/DatabaseCleanup.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAgB7E;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CACnC,EAA2B;IAE3B,IAAI,OAAO,EAAE,CAAC,WAAW,KAAK,UAAU,EAAE,CAAC;QAC1C,MAAM,IAAI,UAAU,CACnB,8BAA8B,EAC9B,wHAAwH,EACxH;YACC,IAAI,EAAE,gGAAgG;SACtG,CACD,CAAC;IACH,CAAC;IACD,8EAA8E;IAC9E,+DAA+D;IAC/D,MAAM,GAAG,GAAG,MAAM,EAAE,CAAC,WAAW,EAAE,CAAC;IACnC,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,GAAG,EAAE,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC;AAChD,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAChC,EAA2B,EAC3B,eAAkC,EAAE;IAEpC,2EAA2E;IAC3E,wDAAwD;IACxD,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;IAC3B,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,CAAC;IACrC,MAAM,MAAM,GAAG,CAAC,MAAM,cAAc,CAAC,EAAE,EAAE,OAAO,CAAC,CAAC,CAAC,MAAM,CACxD,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CACrB,CAAC;IACF,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEhC,sEAAsE;IACtE,2EAA2E;IAC3E,0EAA0E;IAC1E,0EAA0E;IAC1E,8EAA8E;IAC9E,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;QAC5B,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACxE,MAAM,EAAE,CAAC,OAAO,CAAC,YAAY,IAAI,2BAA2B,CAAC,CAAC;QAC9D,OAAO;IACR,CAAC;IAED,sEAAsE;IACtE,uEAAuE;IACvE,MAAM,UAAU,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QACtC,MAAM,QAAQ,GAAG,sBAAsB,CACtC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAC3C,OAAO,CACP,CAAC;QACF,OAAO,EAAE,GAAG,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,CAAC;IACjE,CAAC,CAAC,CAAC;IACH,MAAM,qBAAqB,CAAC,EAAE,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC;AACtD,CAAC"}

package/dist/testing/DbAssertions.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `db()` — a helix plugin (AdonisJS Lucid database-assertions parity) that
+ * injects database assertions on the test context as `ctx.db`:
+ *
+ *   // tests/bootstrap.ts
+ *   import { configure } from "@c9up/helix";
+ *   import { db } from "@c9up/atlas/testing";
+ *   await configure({ plugins: [db(connection)] });
+ *
+ *   test("registers the user", async ({ db }) => {
+ *     await db.assertHas("users", { email: "a@b.c" });
+ *     await db.assertCount("users", 1);
+ *   });
+ *
+ * Values are always bound as parameters; table/column identifiers are validated
+ * against a strict pattern (letters, digits, `_`, `.`) and quoted, so neither a
+ * value nor an identifier can inject SQL.
+ *
+ * NOTE (namespace): the AdonisJS docs expose these as `db.assert*`; the exact
+ * surface is re-verified against the Adonis docs when available. Model-based
+ * `assertModelExists`/`assertModelMissing` (entity PK metadata) are pending.
+ */
+import type { Plugin } from "@c9up/helix";
+/** The minimal connection the assertions need — a parameterized query runner. */
+export interface DbConnectionLike {
+    query(sql: string, params?: unknown[]): Promise<Record<string, unknown>[]>;
+}
+/** The `ctx.db` assertion surface (AdonisJS Lucid database-assertions parity). */
+export interface DbAssertions {
+    /** At least one row in `table` matches every column in `payload`. */
+    assertHas(table: string, payload: Record<string, unknown>): Promise<void>;
+    /** No row in `table` matches `payload`. */
+    assertMissing(table: string, payload: Record<string, unknown>): Promise<void>;
+    /** `table` has exactly `expected` rows (optionally matching `payload`). */
+    assertCount(table: string, expected: number, payload?: Record<string, unknown>): Promise<void>;
+    /** `table` has no rows at all. */
+    assertEmpty(table: string): Promise<void>;
+}
+/** Build the assertion surface bound to a connection. */
+export declare function createDbAssertions(conn: DbConnectionLike): DbAssertions;
+/** The `db()` helix plugin — registers {@link DbAssertions} as `ctx.db`. */
+export declare function db(conn: DbConnectionLike): Plugin;
+declare module "@c9up/helix" {
+    interface TestContext {
+        db: DbAssertions;
+    }
+}
+//# sourceMappingURL=DbAssertions.d.ts.map

package/dist/testing/DbAssertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DbAssertions.d.ts","sourceRoot":"","sources":["../../src/testing/DbAssertions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAE1C,iFAAiF;AACjF,MAAM,WAAW,gBAAgB;IAChC,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC3E;AA+BD,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC5B,qEAAqE;IACrE,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,2CAA2C;IAC3C,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9E,2EAA2E;IAC3E,WAAW,CACV,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB,kCAAkC;IAClC,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,yDAAyD;AACzD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAkCvE;AAED,4EAA4E;AAC5E,wBAAgB,EAAE,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAKjD;AAID,OAAO,QAAQ,aAAa,CAAC;IAC5B,UAAU,WAAW;QACpB,EAAE,EAAE,YAAY,CAAC;KACjB;CACD"}