@c9up/atlas 0.2.0 → 0.2.1

package/src/AtlasProvider.ts

@@ -17,8 +17,8 @@
  *     }
  *
  *     // Code
- *     const primary = app.container.resolve('db')              // default
- *     const tenant1 = app.container.resolve('db:tenant1')     // named
+ *     const primary = await app.container.resolve('db')          // default
+ *     const tenant1 = await app.container.resolve('db:tenant1') // named
  */
 
 import {
@@ -50,10 +50,30 @@ export interface AtlasAppContext {
 			token: string | symbol | (new (...args: never[]) => unknown),
 			factory: () => unknown,
 		): void;
+		/**
+		 * Optional reader — present on ream's real container. Used to look up the
+		 * app emitter (`events`) so query events are bridged onto it as `db:query`
+		 * (AdonisJS parity: `emitter.on('db:query', …)`). Structural, async-capable.
+		 */
+		resolve?(
+			token: string | symbol | (new (...args: never[]) => unknown),
+		): unknown | Promise<unknown>;
 	};
 	config: { get<T = unknown>(key: string): T | undefined };
 }
 
+/** True when `x` looks like an event emitter with `emit(event, data)`. */
+function hasEmit(
+	x: unknown,
+): x is { emit: (event: string, data: unknown) => void } {
+	return (
+		typeof x === "object" &&
+		x !== null &&
+		"emit" in x &&
+		typeof x.emit === "function"
+	);
+}
+
 /**
  * Canonical sqlite production pragma recipe.
  *
@@ -75,12 +95,26 @@ export const SQLITE_PROD_PRAGMAS = Object.freeze({
 
 /** One connection's settings. */
 export interface ConnectionConfig {
-	/** Connection URL: "sqlite:data/app.db", "postgres://...", "mysql://..." */
-	url: string;
-	/** Minimum pool connections (default: 1) */
+	/**
+	 * Connection URL: "sqlite:data/app.db", "postgres://...", "mysql://...".
+	 * Lucid names this per-connection key `connection` — {@link connection} is
+	 * accepted as an alias, so at least one of the two must be set.
+	 */
+	url?: string;
+	/**
+	 * Lucid's per-connection URL key (`connections: { primary: { connection: '…' } }`).
+	 * Alias of {@link url}; `url` wins when both are present.
+	 */
+	connection?: string;
+	/** Minimum pool connections (default: 1). Prefer the Lucid-shaped {@link pool}. */
 	poolMin?: number;
-	/** Maximum pool connections (default: 10) */
+	/** Maximum pool connections (default: 10). Prefer the Lucid-shaped {@link pool}. */
 	poolMax?: number;
+	/**
+	 * Connection-pool sizing, Lucid-shaped — `pool: { min: 2, max: 10 }`. Takes
+	 * precedence over the flat `poolMin`/`poolMax` when both are set.
+	 */
+	pool?: { min?: number; max?: number };
 	/**
 	 * Emit a `db:query` event for every statement on this connection (Lucid's
 	 * `debug` connection option). Off by default — subscribe with `onDbQuery`
@@ -115,18 +149,48 @@ export interface ConnectionConfig {
 
 /** Full database config — single-connection (legacy) OR multi-connection. */
 export interface AtlasDatabaseConfig extends ConnectionConfig {
-	/** Name of the default connection when `connections` is set. Defaults to `"primary"`. */
+	/**
+	 * Name of the default connection when `connections` is set (Lucid's top-level
+	 * `connection`). `default` is a deprecated alias — `connection` wins when both
+	 * are set. Defaults to `"primary"`.
+	 */
+	connection?: string;
+	/** @deprecated Use {@link connection} (the Lucid key). */
 	default?: string;
 	/** Named connections. When present, top-level `url` is treated as `connections[default].url`. */
 	connections?: Record<string, ConnectionConfig>;
 	migrations?: {
+		/** @deprecated Use the Lucid-shaped {@link paths}. */
 		path?: string;
+		/** Migration directories, Lucid-shaped — `paths: ['database/migrations']`. */
+		paths?: string[];
 		/**
 		 * Custom name for the migrations tracking table. Defaults to `"ream_migrations"`.
 		 * Must match `/^[A-Za-z_][A-Za-z0-9_]*$/` — the `MigrationRunner` constructor
 		 * throws `AtlasError("MIGRATION_INVALID_TABLE_NAME")` otherwise.
 		 */
 		table?: string;
+		/**
+		 * Allow the boot-time auto-migrate in production. OFF by default:
+		 * starting the app should NOT silently mutate the schema in prod (Adonis
+		 * Lucid runs migrations only via the explicit `migration:run` command).
+		 * In non-production, boot auto-migrate stays on for dev convenience. The
+		 * CLI's `REAM_SKIP_BOOT_MIGRATE=1` always wins.
+		 */
+		autoRunInProduction?: boolean;
+		/**
+		 * Sort migration files with a numeric-aware comparator (`2_x` before
+		 * `10_x`). Adonis Lucid `migrations.naturalSort`. Defaults to `false`
+		 * (plain lexicographic, correct for `make:migration`'s fixed-width prefix).
+		 */
+		naturalSort?: boolean;
+		/**
+		 * Run every migration OUTSIDE a transaction. Adonis Lucid
+		 * `migrations.disableTransactions`. A single migration can also opt out with
+		 * `static disableTransactions = true`; the effective value is their OR.
+		 * Defaults to `false`.
+		 */
+		disableTransactions?: boolean;
 	};
 	/**
 	 * Boot-time schema verification. When set, atlas reconciles each listed
@@ -146,11 +210,86 @@ export default class AtlasProvider {
 	/** Map of connection name → open connection. Populated at boot. */
 	#connections = new Map<string, AsyncDatabaseConnection>();
 	#defaultName = "primary";
+	/** Unsubscribe for the `db:query` → app-emitter bridge, torn down on shutdown. */
+	#dbQueryBridge?: () => void;
 
 	constructor(protected app: AtlasAppContext) {}
 
+	/** Resolve a live connection by name, or throw — never hand out a closed one
+	 * (used by the `db`/`db:<name>` container factories so a failed-boot or
+	 * post-shutdown lookup fails loudly instead of returning a dead handle). */
+	#requireConnection(name: string): AsyncDatabaseConnection {
+		const conn = this.#connections.get(name);
+		if (!conn) {
+			throw new Error(
+				`AtlasProvider: connection '${name}' is not available (boot failed or the provider was shut down).`,
+			);
+		}
+		return conn;
+	}
+
 	register() {}
 
+	/**
+	 * Bridge atlas's `db:query` observability onto the app emitter so consumers
+	 * use the AdonisJS API — `emitter.on('db:query', (query) => …)`. The agnostic
+	 * `onDbQuery(listener)` primitive stays available for hosts without an emitter.
+	 * No-op when the container exposes no `events` emitter.
+	 */
+	async #bridgeDbQueryEvents(): Promise<void> {
+		const resolve = this.app.container.resolve;
+		if (typeof resolve !== "function") return;
+		let emitter: unknown;
+		try {
+			emitter = await resolve.call(this.app.container, "events");
+		} catch {
+			return; // no emitter bound — `onDbQuery` remains the way to observe
+		}
+		if (!hasEmit(emitter)) return;
+		const { onDbQuery } = await import("./events.js");
+		this.#dbQueryBridge?.();
+		this.#dbQueryBridge = onDbQuery((event) => {
+			emitter.emit("db:query", event);
+		});
+	}
+
+	/** Teardown for the connection-lifecycle → app-emitter bridge. */
+	#connectionBridge?: () => void;
+
+	/**
+	 * Bridge the connection manager's lifecycle events onto the app emitter as
+	 * AdonisJS's `db:connection:connect` / `db:connection:disconnect` /
+	 * `db:connection:error` (`[error, node]`). No-op without an `events` emitter.
+	 */
+	async #bridgeConnectionEvents(): Promise<void> {
+		const resolve = this.app.container.resolve;
+		if (typeof resolve !== "function") return;
+		let emitter: unknown;
+		try {
+			emitter = await resolve.call(this.app.container, "events");
+		} catch {
+			return;
+		}
+		if (!hasEmit(emitter)) return;
+		const { connectionManager } = await import("./services/db.js");
+		const mgr = connectionManager();
+		this.#connectionBridge?.();
+		const onConnect = (node: unknown) =>
+			emitter.emit("db:connection:connect", node);
+		const onDisconnect = (node: unknown) =>
+			emitter.emit("db:connection:disconnect", node);
+		const onError = (node: unknown, err?: unknown) =>
+			emitter.emit("db:connection:error", [err, node]);
+		mgr.on("connect", onConnect);
+		mgr.on("disconnect", onDisconnect);
+		mgr.on("error", onError);
+		this.#connectionBridge = () => {
+			mgr.off("connect", onConnect);
+			mgr.off("disconnect", onDisconnect);
+			mgr.off("error", onError);
+		};
+	}
+
 	async boot() {
 		const config = this.app.config.get<AtlasDatabaseConfig>("database");
 		if (!config) return;
@@ -159,6 +298,18 @@ export default class AtlasProvider {
 		const { connections, defaultName } = this.#resolveConnections(config);
 		this.#defaultName = defaultName;
 
+		// Bridge query observability onto the app emitter — AdonisJS parity, so
+		// consumers write `emitter.on('db:query', …)` (see #bridgeDbQueryEvents).
+		await this.#bridgeDbQueryEvents();
+		// Bridge connection lifecycle events too, BEFORE opening pools so the boot
+		// `connect` events reach the app emitter (`db:connection:connect`).
+		await this.#bridgeConnectionEvents();
+
+		// Import the services/db proxy BEFORE opening any pool: if this import ever
+		// failed (packaging/bundle issue), we must not have leaked open connections,
+		// and the cleanup catch below needs it available.
+		const dbServices = await import("./services/db.js");
+
 		// Open every connection in parallel — multi-database apps with slow-to-
 		// handshake drivers (Postgres over TLS, RDS proxies) previously paid the
 		// sum of the round-trip times on boot; now it's the max.
@@ -168,12 +319,17 @@ export default class AtlasProvider {
 		// close every successful one before rethrowing so a partial boot never
 		// leaks pools/sockets.
 		const entries = Object.entries(connections);
+		// Register every connection's config up front (Lucid `manager.add`), so the
+		// manager knows all connections — including any that fail to open below.
+		for (const [name, settings] of entries) {
+			dbServices.connectionManager().add(name, settings);
+		}
 		const results = await Promise.allSettled(
 			entries.map(([name, settings]) =>
 				createNapiConnection(
 					settings.url,
-					settings.poolMin ?? 1,
-					settings.poolMax ?? 10,
+					settings.pool?.min ?? settings.poolMin ?? 1,
+					settings.pool?.max ?? settings.poolMax ?? 10,
 					settings.pragmas,
 					{
 						retries: settings.connectRetries,
@@ -193,6 +349,11 @@ export default class AtlasProvider {
 			else failures.push({ name, error: r.reason });
 		});
 		if (failures.length > 0) {
+			// Surface each failure through the manager → app emitter as
+			// `db:connection:error` ([error, node]) before rolling back.
+			for (const f of failures) {
+				dbServices.connectionManager().reportConnectError(f.name, f.error);
+			}
 			// Tear down the successes so we don't leak any pool that the runtime
 			// has already opened. Closures run in parallel with allSettled so a
 			// stuck close doesn't block the rollback path.
@@ -208,46 +369,85 @@ export default class AtlasProvider {
 					(others ? ` (also: ${others})` : ""),
 			);
 		}
-		for (const { name, conn } of successes) {
-			this.#connections.set(name, conn);
-			this.app.container.singleton(`db:${name}`, () => conn);
-		}
+		// Everything past this point runs AFTER the pools are open — an invalid
+		// default connection, a boot-time migration crash, etc. must not leak the
+		// sockets/pools we just opened. On any failure, tear them all down and
+		// undo the registry/service bindings before rethrowing.
+		try {
+			// Validate the default connection opened BEFORE binding anything: a bad
+			// default must fail while the container/registry are still untouched, so
+			// we never leave handles pointing at connections we're about to close.
+			const defaultEntry = successes.find((s) => s.name === defaultName);
+			if (!defaultEntry) {
+				throw new Error(
+					`AtlasProvider: default connection '${defaultName}' is not defined in config.database.connections`,
+				);
+			}
+			const defaultConn = defaultEntry.conn;
 
-		// Expose the default under the short aliases `db` and `db.connection`.
-		const defaultConn = this.#connections.get(defaultName);
-		if (!defaultConn) {
-			throw new Error(
-				`AtlasProvider: default connection '${defaultName}' is not defined in config.database.connections`,
+			// Bind connections into the container AND the named-connection registry
+			// (the latter is what `BaseModel.connection` / `Factory.connection()` /
+			// `getConnection(name)` read). The container factories resolve through
+			// `#connections` (not a captured handle) so that if boot fails after
+			// binding — the catch clears `#connections` — or after shutdown, resolving
+			// `db`/`db:<name>` throws instead of handing out a CLOSED connection.
+			for (const { name, conn } of successes) {
+				this.#connections.set(name, conn);
+				dbServices.registerConnection(name, conn, connections[name]);
+				this.app.container.singleton(`db:${name}`, () =>
+					this.#requireConnection(name),
+				);
+			}
+
+			// Expose the default under the short aliases `db` and `db.connection`.
+			this.app.container.singleton("db", () =>
+				this.#requireConnection(this.#defaultName),
+			);
+			this.app.container.singleton("db.connection", () =>
+				this.#requireConnection(this.#defaultName),
 			);
-		}
-		this.app.container.singleton("db", () => defaultConn);
-		this.app.container.singleton("db.connection", () => defaultConn);
 
-		// Populate the `@c9up/atlas/services/db` proxy so apps can
-		// `import db from '@c9up/atlas/services/db'` from anywhere.
-		// Done inside the lazy-import to avoid pulling the services
-		// module at construction time when the provider is type-imported
-		// by `@c9up/ream`'s discovery scan.
-		const { setDb } = await import("./services/db.js");
-		setDb(defaultConn);
+			// Populate the `@c9up/atlas/services/db` proxy so apps can
+			// `import db from '@c9up/atlas/services/db'` from anywhere.
+			dbServices.setDb(defaultConn);
 
-		// The dialect set module-wide is the DEFAULT connection's dialect.
-		// Per-connection dialect (when a user hits a non-default) is read from
-		// the connection URL at query time by each call site that cares.
-		setAtlasDialect(dialectFromUrl(connections[defaultName]?.url));
+			// The dialect set module-wide is the DEFAULT connection's dialect.
+			// Per-connection dialect (when a user hits a non-default) is read from
+			// the connection URL at query time by each call site that cares.
+			setAtlasDialect(dialectFromUrl(connections[defaultName]?.url));
 
-		// Auto-run migrations on boot — EXCEPT when a CLI migration command
-		// (`ream migrate` / `migrate:rollback` / `migrate:status`) booted us: it
-		// drives migrations explicitly, so a boot-time pass would double-apply
-		// (and silently re-apply right before a rollback/status). The CLI sets
-		// `REAM_SKIP_BOOT_MIGRATE=1`; default (unset) preserves boot-migrate.
-		if (config.migrations?.path && process.env.REAM_SKIP_BOOT_MIGRATE !== "1") {
-			await this.#runMigrations(
-				config.migrations.path,
-				connections[defaultName]?.url,
-				defaultConn,
-				config.migrations.table,
-			);
+			// Auto-run migrations on boot — but NOT in production unless explicitly
+			// opted in: starting the app should not silently mutate the schema in
+			// prod (Adonis Lucid only migrates via `migration:run`). Skipped too
+			// when a CLI migration command booted us (`REAM_SKIP_BOOT_MIGRATE=1`),
+			// which drives migrations explicitly.
+			const inProduction = process.env.NODE_ENV === "production";
+			const autoMigrateAllowed =
+				!inProduction || config.migrations?.autoRunInProduction === true;
+			if (
+				(config.migrations?.paths?.[0] ?? config.migrations?.path) &&
+				process.env.REAM_SKIP_BOOT_MIGRATE !== "1" &&
+				autoMigrateAllowed
+			) {
+				await this.#runMigrations(
+					config.migrations?.paths?.[0] ?? config.migrations?.path ?? "",
+					connections[defaultName]?.url,
+					defaultConn,
+					config.migrations.table,
+					{
+						naturalSort: config.migrations.naturalSort,
+						disableTransactions: config.migrations.disableTransactions,
+					},
+				);
+			}
+		} catch (err) {
+			await Promise.allSettled(successes.map((s) => s.conn.close()));
+			for (const { name, conn } of successes) {
+				dbServices.clearDb(conn);
+				dbServices.unregisterConnection(name, conn);
+			}
+			this.#connections.clear();
+			throw err;
 		}
 	}
 
@@ -261,6 +461,12 @@ export default class AtlasProvider {
 		//   - any rejection is aggregated into a single `AggregateError` thrown
 		//     at the end so supervisors / health-checks see a non-zero exit
 		//     signal instead of a silent "everything is fine" shutdown
+		// Detach the db:query → emitter bridge so a re-boot doesn't double-emit.
+		this.#dbQueryBridge?.();
+		this.#dbQueryBridge = undefined;
+		this.#connectionBridge?.();
+		this.#connectionBridge = undefined;
+
 		const named = [...this.#connections.entries()];
 		const results = await Promise.allSettled(named.map(([, c]) => c.close()));
 		this.#connections.clear();
@@ -268,9 +474,15 @@ export default class AtlasProvider {
 		// Release the module-level singletons this provider populated at boot so a
 		// re-boot starts clean and `db.*` can't dereference a now-closed handle.
 		// `clearDb` is ownership-guarded, so clearing every connection only unbinds
-		// the one still owning the singleton.
-		const { clearDb } = await import("./services/db.js");
-		for (const [, conn] of named) clearDb(conn);
+		// the one still owning the singleton. Also drop the named-connection
+		// registry entries (boot registered them), so `getConnection(name)` /
+		// `BaseModel.connection` / `Factory.connection()` can't hand out a CLOSED
+		// handle after shutdown.
+		const { clearDb, unregisterConnection } = await import("./services/db.js");
+		for (const [name, conn] of named) {
+			clearDb(conn);
+			unregisterConnection(name, conn);
+		}
 		clearCastRegistry();
 		const errors = results
 			.map((r, i) =>
@@ -309,23 +521,51 @@ export default class AtlasProvider {
 
 	/** Normalize the config into a `{ name → ConnectionConfig }` map + default name. */
 	#resolveConnections(config: AtlasDatabaseConfig): {
-		connections: Record<string, ConnectionConfig>;
+		connections: Record<string, ConnectionConfig & { url: string }>;
 		defaultName: string;
 	} {
 		if (config.connections && Object.keys(config.connections).length > 0) {
+			// Normalize each block's URL from Lucid's `connection` key (alias of `url`).
+			const connections: Record<string, ConnectionConfig & { url: string }> =
+				{};
+			for (const [name, block] of Object.entries(config.connections)) {
+				const url = block.url ?? block.connection;
+				if (!url) {
+					throw new Error(
+						`[atlas] connection '${name}' has no URL — set 'url' (or Lucid's 'connection') in config.database.connections.${name}.`,
+					);
+				}
+				connections[name] = { ...block, url };
+			}
 			return {
-				connections: config.connections,
-				defaultName: config.default ?? "primary",
+				connections,
+				// Lucid's `connection` (default selector); `default` is the alias.
+				defaultName: config.connection ?? config.default ?? "primary",
 			};
 		}
-		// Legacy single-connection shape — promote to multi-connection under "primary".
+		// Legacy single-connection shape — promote to multi-connection under
+		// "primary". Carry EVERY top-level option through: dropping debug /
+		// connectRetries / connectBackoffMs / connectTimeoutMs here silently
+		// disabled retry/timeout/query-debug for anyone still on the flat config.
+		// (Top-level `connection` is the default-selector, so the flat form's URL
+		// comes from `url` only — Lucid's `connection`-as-URL is a nested-block key.)
+		if (!config.url) {
+			throw new Error(
+				"[atlas] no database URL — set 'url' at the top level, or use 'connections: { … }' with a per-connection 'url'/'connection'.",
+			);
+		}
 		return {
 			connections: {
 				primary: {
 					url: config.url,
 					poolMin: config.poolMin,
 					poolMax: config.poolMax,
+					pool: config.pool,
 					pragmas: config.pragmas,
+					debug: config.debug,
+					connectRetries: config.connectRetries,
+					connectBackoffMs: config.connectBackoffMs,
+					connectTimeoutMs: config.connectTimeoutMs,
 				},
 			},
 			defaultName: "primary",
@@ -337,6 +577,7 @@ export default class AtlasProvider {
 		url: string,
 		db: AsyncDatabaseConnection,
 		tableName: string | undefined,
+		options?: { naturalSort?: boolean; disableTransactions?: boolean },
 	): Promise<void> {
 		const { existsSync } = await import("node:fs");
 		if (!existsSync(migrationsPath)) return;
@@ -353,11 +594,16 @@ export default class AtlasProvider {
 			// `ream_migrations` bookkeeping row together). Without this, the runner
 			// silently falls back to non-transactional execution.
 			runInTransaction: async (batch) => db.runInTransaction(batch),
+			// Managed interactive transaction, so this.defer() migrations run
+			// atomically (schema + deferred + tracking committed together).
+			transaction: db.transaction?.bind(db),
 		};
 		const runner = new MigrationRunner(adapter, {
 			migrationsDir: migrationsPath,
 			dialect: dialectFromUrl(url),
 			tableName,
+			naturalSort: options?.naturalSort,
+			disableTransactions: options?.disableTransactions,
 		});
 		await runner.migrate();
 	}

package/src/BaseEntity.ts

@@ -139,6 +139,35 @@ export interface BelongsToRelationProxy extends BulkRelationProxy {
  */
 export interface ManyToManyRelationProxy extends BulkRelationProxy {
 	readonly type: "manyToMany";
+	/**
+	 * Persist a new related row AND its pivot link, optionally with pivot column
+	 * values (Adonis Lucid `create(values, pivotAttributes)`).
+	 */
+	create(
+		data: Record<string, unknown>,
+		pivotAttributes?: Record<string, unknown>,
+	): Promise<BaseEntity>;
+	/** Persist an existing related instance + pivot link, with optional pivot values. */
+	save(
+		related: BaseEntity,
+		pivotAttributes?: Record<string, unknown>,
+	): Promise<void>;
+	/** Bulk {@link create}; `pivotAttributes[i]` applies to `rows[i]`. */
+	createMany(
+		rows: Array<Record<string, unknown>>,
+		pivotAttributes?: Array<Record<string, unknown>>,
+	): Promise<BaseEntity[]>;
+	/** Bulk {@link save}; `pivotAttributes[i]` applies to `related[i]`. */
+	saveMany(
+		related: BaseEntity[],
+		pivotAttributes?: Array<Record<string, unknown>>,
+	): Promise<BaseEntity[]>;
+	/**
+	 * A query builder on the PIVOT table itself, scoped to this parent (Adonis
+	 * Lucid `pivotQuery`) — read/update/delete pivot rows directly, beyond
+	 * attach/detach/sync. Returns the connection-level query builder.
+	 */
+	pivotQuery(): import("./query/DatabaseQueryBuilder.js").DatabaseQueryBuilder;
 	/** Insert pivot rows. Accepts `id[]` or `{ id: extras }`. */
 	attach(
 		ids: Array<string | number> | Record<string, Record<string, unknown>>,