@c9up/atlas 0.2.0 → 0.2.1

package/src/schema/catalog.ts

@@ -7,6 +7,7 @@
  * they are framework introspection, not user queries, so they stay raw SQL.
  */
 
+import { AtlasError } from "../errors.js";
 import type { AtlasDialect } from "../query/native.js";
 
 /**
@@ -22,6 +23,20 @@ export interface CatalogConnection {
 	// Return value is ignored — the two adapter shapes disagree on it
 	// (`void` vs `{ rowsAffected }`), and these helpers only run it for effect.
 	execute(sql: string, params?: unknown[]): Promise<unknown>;
+	/**
+	 * Optional: run a batch of statements atomically on ONE pinned pooled
+	 * connection. When present, {@link runWithoutForeignKeys} uses it so the FK
+	 * toggle and the operations can't scatter across the pool.
+	 */
+	runInTransaction?(
+		batch: readonly { sql: string; params?: unknown[] }[],
+	): Promise<number>;
+	/**
+	 * Optional MANAGED interactive transaction pinned to ONE connection (Lucid
+	 * `db.transaction(cb)`). When present, {@link runWithoutForeignKeys} uses it
+	 * on MySQL so the FK restore runs in a real `finally` on that same connection.
+	 */
+	transaction?<T>(callback: (trx: CatalogConnection) => Promise<T>): Promise<T>;
 }
 
 /**
@@ -37,6 +52,12 @@ export interface ListTablesOptions {
 	 * because it re-creates the tracking table afterwards.
 	 */
 	includeFrameworkTables?: boolean;
+	/**
+	 * PostgreSQL only — restrict the listing to these schemas instead of just the
+	 * current one (Adonis Lucid `schemaGeneration.schemas`). Ignored on
+	 * sqlite/mysql, which have no schema namespace of this kind.
+	 */
+	schemas?: string[];
 }
 
 /** List every base table in the current schema/database, for `dialect`. */
@@ -46,21 +67,33 @@ export async function listUserTables(
 	options: ListTablesOptions = {},
 ): Promise<string[]> {
 	let sql: string;
+	const params: unknown[] = [];
 	switch (dialect) {
 		case "sqlite":
 			sql =
 				"SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'";
 			break;
 		case "postgres":
-			sql =
-				"SELECT tablename AS name FROM pg_tables WHERE schemaname = current_schema()";
+			// Restrict to the given schemas (Lucid `schemas`) or the current one.
+			// Bind each schema as its own scalar placeholder — atlas's driver binds
+			// arrays as text, so `schemaname = ANY($1)` would fail; an IN list works.
+			if (options.schemas && options.schemas.length > 0) {
+				const placeholders = options.schemas.map((_, i) => `$${i + 1}`);
+				params.push(...options.schemas);
+				sql = `SELECT tablename AS name FROM pg_tables WHERE schemaname IN (${placeholders.join(", ")})`;
+			} else {
+				sql =
+					"SELECT tablename AS name FROM pg_tables WHERE schemaname = current_schema()";
+			}
 			break;
 		case "mysql":
+			// CAST to CHAR: MySQL returns information_schema identifier columns as
+			// binary (Uint8Array), which the string filter below would drop.
 			sql =
-				"SELECT table_name AS name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'";
+				"SELECT CAST(table_name AS CHAR) AS name FROM information_schema.tables WHERE table_schema = DATABASE() AND table_type = 'BASE TABLE'";
 			break;
 	}
-	const rows = await db.query<{ name: unknown }>(sql);
+	const rows = await db.query<{ name: unknown }>(sql, params);
 	const names: string[] = [];
 	for (const row of rows) {
 		if (typeof row.name !== "string") continue;
@@ -139,28 +172,65 @@ export async function columnExists(
  * order. Postgres has no session-level switch (it uses `TRUNCATE … CASCADE` /
  * `DROP … CASCADE` instead), so this is a no-op there.
  */
-export async function withoutForeignKeys<T>(
+export async function runWithoutForeignKeys(
 	db: CatalogConnection,
 	dialect: AtlasDialect,
-	fn: () => Promise<T>,
-): Promise<T> {
-	const off =
-		dialect === "sqlite"
-			? "PRAGMA foreign_keys = OFF"
-			: dialect === "mysql"
-				? "SET FOREIGN_KEY_CHECKS = 0"
-				: null;
-	const on =
-		dialect === "sqlite"
-			? "PRAGMA foreign_keys = ON"
-			: dialect === "mysql"
-				? "SET FOREIGN_KEY_CHECKS = 1"
-				: null;
+	statements: ReadonlyArray<{ sql: string; params?: unknown[] }>,
+): Promise<void> {
+	if (statements.length === 0) return;
 
-	if (off) await db.execute(off);
-	try {
-		return await fn();
-	} finally {
-		if (on) await db.execute(on);
+	// MySQL: `SET FOREIGN_KEY_CHECKS` is a SESSION variable (not transactional),
+	// so it MUST be restored in a real `finally` on the SAME pinned connection —
+	// otherwise a mid-batch failure leaves the pooled connection with FK checks
+	// off. Use the managed interactive transaction: SET 0 → ops → finally SET 1,
+	// all on the one pinned connection, restore guaranteed even on error.
+	if (dialect === "mysql") {
+		// MySQL `SET FOREIGN_KEY_CHECKS` is a SESSION variable (not transactional),
+		// so it MUST be restored in a real `finally` on the SAME pinned connection.
+		// That needs the managed interactive transaction: SET 0 → ops → finally
+		// SET 1, restore guaranteed even on error. Without transaction() there is
+		// no safe restore — a mid-batch failure would leave the pooled connection
+		// with FK checks OFF (a poisoned connection). Refuse rather than corrupt.
+		if (!db.transaction) {
+			throw new AtlasError(
+				"E_MYSQL_FK_REQUIRES_TRANSACTION",
+				"Suspending MySQL foreign-key checks needs an interactive transaction() to restore them in a finally — a session-level SET can't be rolled back, so a failure mid-batch would leave the pooled connection with FK checks disabled. This adapter has none.",
+				{
+					hint: "Use a real connection (createNapiConnection) or an adapter that implements transaction().",
+				},
+			);
+		}
+		await db.transaction(async (trx) => {
+			try {
+				await trx.execute("SET FOREIGN_KEY_CHECKS = 0");
+				for (const stmt of statements) {
+					await trx.execute(stmt.sql, stmt.params);
+				}
+			} finally {
+				await trx.execute("SET FOREIGN_KEY_CHECKS = 1");
+			}
+		});
+		return;
+	}
+
+	// sqlite/postgres: run the FK toggle + ops on ONE pinned connection via
+	// runInTransaction so a pool can't scatter the connection-local toggle away
+	// from the ops.
+	//  - sqlite: `PRAGMA defer_foreign_keys` is transaction-scoped and auto-resets
+	//    at txn end (no leak); plain `PRAGMA foreign_keys` is ignored in a txn;
+	//  - postgres: no session toggle — drops use CASCADE and `truncateAll` uses
+	//    `TRUNCATE … CASCADE`, so pg statements are already FK-safe.
+	const batch: Array<{ sql: string; params?: unknown[] }> = [];
+	if (dialect === "sqlite") {
+		batch.push({ sql: "PRAGMA defer_foreign_keys = ON" });
+	}
+	batch.push(...statements);
+	if (db.runInTransaction) {
+		await db.runInTransaction(batch);
+		return;
+	}
+	// No transaction support at all (a bare fake): best effort, single connection.
+	for (const stmt of batch) {
+		await db.execute(stmt.sql, stmt.params);
 	}
 }

package/src/schema/introspect.ts

@@ -49,15 +49,17 @@ export async function introspectTable(
 	db: SchemaIntrospectable,
 	dialect: AtlasDialect,
 	table: string,
+	schema?: string,
 ): Promise<IntrospectedColumn[] | null> {
 	assertIdent(table);
+	if (schema !== undefined) assertIdent(schema);
 	switch (dialect) {
 		case "sqlite":
 			return introspectSqlite(db, table);
 		case "postgres":
-			return introspectPostgres(db, table);
+			return introspectPostgres(db, table, schema);
 		case "mysql":
-			return introspectMysql(db, table);
+			return introspectMysql(db, table, schema);
 	}
 }
 
@@ -79,13 +81,17 @@ async function introspectSqlite(
 async function introspectPostgres(
 	db: SchemaIntrospectable,
 	table: string,
+	schema?: string,
 ): Promise<IntrospectedColumn[] | null> {
+	// Target a specific schema when given (Lucid `schemas`), else the current one.
+	const schemaPred = schema ? "$2" : "current_schema()";
+	const args = schema ? [table, schema] : [table];
 	const cols = await db.query(
 		`SELECT column_name, data_type, is_nullable, column_default
 		 FROM information_schema.columns
-		 WHERE table_schema = current_schema() AND table_name = $1
+		 WHERE table_schema = ${schemaPred} AND table_name = $1
 		 ORDER BY ordinal_position`,
-		[table],
+		args,
 	);
 	if (cols.length === 0) return null;
 	const pkRows = await db.query(
@@ -94,8 +100,9 @@ async function introspectPostgres(
 		 JOIN information_schema.key_column_usage kcu
 		   ON kcu.constraint_name = tc.constraint_name
 		  AND kcu.table_schema = tc.table_schema
-		 WHERE tc.table_name = $1 AND tc.constraint_type = 'PRIMARY KEY'`,
-		[table],
+		 WHERE tc.table_name = $1 AND tc.constraint_type = 'PRIMARY KEY'
+		   AND tc.table_schema = ${schemaPred}`,
+		args,
 	);
 	const pks = new Set(pkRows.map((r) => String(r.column_name)));
 	return cols.map((r) => ({
@@ -110,13 +117,23 @@ async function introspectPostgres(
 async function introspectMysql(
 	db: SchemaIntrospectable,
 	table: string,
+	schema?: string,
 ): Promise<IntrospectedColumn[] | null> {
+	// In MySQL a "schema" IS a database; target it when given, else DATABASE().
+	const schemaPred = schema ? "?" : "DATABASE()";
+	const args = schema ? [schema, table] : [table];
+	// CAST the identifier/enum columns to CHAR: MySQL returns information_schema
+	// text as binary (Uint8Array), which `String(...)` would turn into byte lists.
 	const rows = await db.query(
-		`SELECT column_name, data_type, is_nullable, column_default, column_key
+		`SELECT CAST(column_name AS CHAR) AS column_name,
+		        CAST(data_type AS CHAR) AS data_type,
+		        CAST(is_nullable AS CHAR) AS is_nullable,
+		        column_default,
+		        CAST(column_key AS CHAR) AS column_key
 		 FROM information_schema.columns
-		 WHERE table_schema = DATABASE() AND table_name = ?
+		 WHERE table_schema = ${schemaPred} AND table_name = ?
 		 ORDER BY ordinal_position`,
-		[table],
+		args,
 	);
 	if (rows.length === 0) return null;
 	return rows.map((r) => ({

package/src/seeders.ts

@@ -0,0 +1,16 @@
+/**
+ * `@c9up/atlas/seeders` — Adonis Lucid seeders parity subpath. The `BaseSeeder`
+ * base class plus the runners and the `make:seeder` / `db:seed` console commands.
+ */
+
+export {
+	dbSeedCommand,
+	makeSeederCommand,
+	type SeederCommandOptions,
+} from "./console/seederCommands.js";
+export {
+	BaseSeeder,
+	runSeederDirectory,
+	runSeeders,
+	Seeder,
+} from "./schema/Seeder.js";

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 {
 	/**
-	 * 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>;
 }
 
 let instance: AsyncDatabaseConnection | undefined;
@@ -49,51 +164,248 @@ export function getDb(): AsyncDatabaseConnection | undefined {
 	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<string, AsyncDatabaseConnection>();
+// 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 a named connection (called by AtlasProvider.boot per connection). */
+/**
+ * @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 {
-	namedConnections.set(name, connection);
+	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: string,
 	connection: AsyncDatabaseConnection,
 ): void {
-	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: string,
 ): AsyncDatabaseConnection | undefined {
-	return namedConnections.get(name);
+	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
 }
 
-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.",
+/** 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),
+			);
+		},
+		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),
 			);
-		}
-		const value = Reflect.get(instance, prop, instance);
-		return typeof value === "function" ? value.bind(instance) : value;
-	},
+		},
+		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;