@c9up/atlas 0.1.19 → 0.2.1

package/src/services/db.ts

@@ -13,18 +13,133 @@
  * 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";
+import {
+	RawQueryBuilder,
+	resolveRawBindings,
+} from "../query/RawQueryBuilder.js";
+import { truncateAll } from "../testing/DatabaseCleanup.js";
 
-/** The `db` singleton surface: the bound connection plus the AdonisJS-style `db.raw()` builder. */
-export interface DbService extends AsyncDatabaseConnection {
+/** 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 {
+	/**
+	 * `'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>;
 	/**
-	 * Build a raw SQL expression — AdonisJS `db.raw()` / `Database.raw()`. Use it
-	 * for query fragments and for column defaults that are SQL expressions:
+	 * 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`.
+	 */
+	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).
 	 */
-	raw(sql: string, params?: unknown[]): RawSql;
+	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>;
 }
 
 let instance: AsyncDatabaseConnection | undefined;
@@ -49,23 +164,248 @@ export function getDb(): AsyncDatabaseConnection | undefined {
 	return instance;
 }
 
-const db: DbService = new Proxy({} as DbService, {
-	get(_target, prop) {
-		// `raw` is a pure builder (no connection needed) — available pre-boot too.
-		if (prop === "raw") {
-			return (sql: string, params: unknown[] = []) => 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.",
+// 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: string,
+	connection: AsyncDatabaseConnection,
+	config: ConnectionConfig = {},
+): void {
+	manager.register(name, config, connection);
+}
+
+/** @internal Unregister a named connection IF it still points at `connection` (no close). */
+export function unregisterConnection(
+	name: string,
+	connection: AsyncDatabaseConnection,
+): void {
+	manager.deregister(name, connection);
+}
+
+/** @internal Resolve a live named connection (for `BaseModel.connection`), or `undefined`. */
+export function getConnection(
+	name: string,
+): AsyncDatabaseConnection | undefined {
+	return manager.connection(name);
+}
+
+/** @internal The shared connection manager (for the AtlasProvider lifecycle-event bridge). */
+export function connectionManager(): 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: string | number): number {
+	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: string, dialect: AtlasDialect): string {
+	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}'`,
+				);
+			}
+			return `${q}${seg}${q}`;
+		})
+		.join(".");
+}
+
+/** Build a {@link DbService} over a resolver that yields the live connection. */
+export function createDbService(
+	resolve: () => AsyncDatabaseConnection,
+	readOnly = false,
+): DbService {
+	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?: DbQueryOptions) =>
+		readOnly || options?.mode === "read" ? { readOnly: true } : undefined;
+	return {
+		query(options) {
+			const conn = resolve();
+			return new DatabaseQueryBuilder(
+				options?.client ?? conn,
+				conn.dialect,
+				"",
+				optsFor(options),
 			);
-		}
-		const value = Reflect.get(instance, prop, instance);
-		return typeof value === "function" ? value.bind(instance) : value;
-	},
+		},
+		from(
+			source:
+				| string
+				| DatabaseQueryBuilder
+				| ((query: DatabaseQueryBuilder) => void),
+			alias?: string,
+		) {
+			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 as unknown[]);
+			}
+			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<{ locked: boolean }>(
+					"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<{ locked: number }>(
+				"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<{ released: boolean }>(
+					"SELECT pg_advisory_unlock($1) AS released",
+					[advisoryLockKey(key)],
+				);
+				return Boolean(rows[0]?.released);
+			}
+			const rows = await conn.query<{ released: number }>(
+				"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: DbService = 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;

package/src/testing/DatabaseCleanup.ts

@@ -5,44 +5,97 @@
  */
 
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
-import { compileStatementNative, getAtlasDialect } from "../query/native.js";
+import { AtlasError } from "../errors.js";
+import { compileStatementNative } from "../query/native.js";
+import { listUserTables, runWithoutForeignKeys } from "../schema/catalog.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 async function useTransaction(
 	db: AsyncDatabaseConnection,
-): Promise<() => Promise<void>> {
-	await db.execute("SAVEPOINT test_savepoint");
-	return async () => {
-		await db.execute("ROLLBACK TO SAVEPOINT test_savepoint");
-		await db.execute("RELEASE SAVEPOINT test_savepoint");
-	};
+): Promise<TestTransaction> {
+	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() };
 }
 
 /**
- * Truncate all user tables (excludes ream_* framework tables and SQLite internals).
+ * 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.
  *
- * The SELECT on `sqlite_master` is SQLite-specific introspection and is kept
- * as raw SQL intentionally — it's not a user query. The resulting DELETEs
- * go through the Rust compiler.
+ * Foreign keys are suspended for the duration so the delete order doesn't
+ * 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: AsyncDatabaseConnection): Promise<void> {
-	// SQL LIKE `_` is a single-char wildcard, not a literal underscore, so the
-	// `ESCAPE '\'` clause makes `\_` a literal underscore. The exclusion targets
-	// names starting with `ream_` (the convention for framework-private tables,
-	// including `ream_migrations`) and SQLite's own `sqlite_%` tables.
-	const tables = await db.query(
-		"SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'ream\\_%' ESCAPE '\\' AND name NOT LIKE 'sqlite_%'",
+export async function truncateAll(
+	db: AsyncDatabaseConnection,
+	ignoreTables: readonly string[] = [],
+): Promise<void> {
+	// 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 ignore = new Set(ignoreTables);
+	const tables = (await listUserTables(db, dialect)).filter(
+		(t) => !ignore.has(t),
 	);
-	const dialect = getAtlasDialect();
-	for (const row of tables) {
-		const name = row.name;
-		if (typeof name !== "string") continue;
+	if (tables.length === 0) return;
+
+	// 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,
 		);
-		await db.execute(compiled.statements[0], compiled.params);
-	}
+		return { sql: compiled.statements[0], params: compiled.params };
+	});
+	await runWithoutForeignKeys(db, dialect, statements);
 }

package/src/testing/DbAssertions.ts

@@ -0,0 +1,127 @@
+/**
+ * `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>[]>;
+}
+
+/** Reject identifiers that could break out of the quoted context. */
+function quoteIdent(name: string): string {
+	if (!/^[A-Za-z_][A-Za-z0-9_.]*$/.test(name)) {
+		throw new Error(`db assertion: unsafe identifier ${JSON.stringify(name)}`);
+	}
+	return `"${name.replace(/\./g, '"."')}"`;
+}
+
+async function countRows(
+	conn: DbConnectionLike,
+	table: string,
+	payload?: Record<string, unknown>,
+): Promise<number> {
+	let where = "";
+	let params: unknown[] = [];
+	if (payload) {
+		const keys = Object.keys(payload);
+		if (keys.length > 0) {
+			where = ` WHERE ${keys.map((k) => `${quoteIdent(k)} = ?`).join(" AND ")}`;
+			params = keys.map((k) => payload[k]);
+		}
+	}
+	const rows = await conn.query(
+		`SELECT COUNT(*) AS c FROM ${quoteIdent(table)}${where}`,
+		params,
+	);
+	return Number(rows[0]?.c ?? 0);
+}
+
+/** 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 function createDbAssertions(conn: DbConnectionLike): DbAssertions {
+	return {
+		async assertHas(table, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n === 0) {
+				throw new Error(
+					`Expected "${table}" to have a row matching ${JSON.stringify(payload)}, found none.`,
+				);
+			}
+		},
+		async assertMissing(table, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n > 0) {
+				throw new Error(
+					`Expected "${table}" to have NO row matching ${JSON.stringify(payload)}, found ${n}.`,
+				);
+			}
+		},
+		async assertCount(table, expected, payload) {
+			const n = await countRows(conn, table, payload);
+			if (n !== expected) {
+				const scope = payload ? ` matching ${JSON.stringify(payload)}` : "";
+				throw new Error(
+					`Expected "${table}" to have ${expected} row(s)${scope}, found ${n}.`,
+				);
+			}
+		},
+		async assertEmpty(table) {
+			const n = await countRows(conn, table);
+			if (n > 0) {
+				throw new Error(`Expected "${table}" to be empty, found ${n} row(s).`);
+			}
+		},
+	};
+}
+
+/** The `db()` helix plugin — registers {@link DbAssertions} as `ctx.db`. */
+export function db(conn: DbConnectionLike): Plugin {
+	const assertions = createDbAssertions(conn);
+	return (api) => {
+		api.context.macro("db", assertions);
+	};
+}
+
+// Typing side of the plugin — importing `@c9up/atlas/testing` augments the
+// helix test context with `db` (the Japa pattern).
+declare module "@c9up/helix" {
+	interface TestContext {
+		db: DbAssertions;
+	}
+}