@c9up/atlas 0.1.3

package/src/Transaction.ts

@@ -0,0 +1,83 @@
+/**
+ * Transaction — wraps database operations in BEGIN/COMMIT/ROLLBACK.
+ *
+ * @implements MISS-1
+ */
+
+import { randomBytes } from "node:crypto";
+import type { DatabaseConnection } from "./BaseRepository.js";
+import {
+	isTransactionClient,
+	TRANSACTION_BRAND,
+} from "./utils/transactionBrand.js";
+
+export interface TransactionClient extends DatabaseConnection {
+	commit(): Promise<void>;
+	rollback(): Promise<void>;
+	readonly isNested: boolean;
+	readonly [TRANSACTION_BRAND]: true;
+}
+
+export async function transaction<T>(
+	db: DatabaseConnection,
+	callback: (trx: TransactionClient) => Promise<T> | T,
+): Promise<T> {
+	if (isTransactionClient(db)) {
+		const name = `sp_${randomBytes(6).toString("hex")}`;
+		await db.execute(`SAVEPOINT ${name}`, []);
+
+		const trx: TransactionClient = {
+			execute: db.execute.bind(db),
+			query: db.query.bind(db),
+			async commit() {
+				await db.execute(`RELEASE SAVEPOINT ${name}`, []);
+			},
+			async rollback() {
+				await db.execute(`ROLLBACK TO SAVEPOINT ${name}`, []);
+			},
+			isNested: true,
+			[TRANSACTION_BRAND]: true,
+		};
+
+		try {
+			const result = await callback(trx);
+			await trx.commit();
+			return result;
+		} catch (err) {
+			try {
+				await trx.rollback();
+			} catch {
+				/* best-effort */
+			}
+			throw err;
+		}
+	}
+
+	await db.execute("BEGIN", []);
+
+	const trx: TransactionClient = {
+		execute: db.execute.bind(db),
+		query: db.query.bind(db),
+		async commit() {
+			await db.execute("COMMIT", []);
+		},
+		async rollback() {
+			await db.execute("ROLLBACK", []);
+		},
+		isNested: false,
+		[TRANSACTION_BRAND]: true,
+	};
+
+	try {
+		const result = await callback(trx);
+		await trx.commit();
+		return result;
+	} catch (err) {
+		try {
+			await trx.rollback();
+		} catch {
+			/* best-effort */
+		}
+		throw err;
+	}
+}

package/src/adapters/NapiDbAdapter.ts

@@ -0,0 +1,178 @@
+/**
+ * NapiDbAdapter — bridges the Rust atlas-db NAPI binding to Atlas.
+ */
+
+import { dialectFromUrl } from "../utils/dialectFromUrl.js";
+
+/** One `(sql, params)` pair passed to `runInTransaction`. */
+export interface BatchStatement {
+	sql: string;
+	params?: unknown[];
+}
+
+/** Async database connection backed by Rust (sqlx). */
+export interface AsyncDatabaseConnection {
+	/** The dialect this connection targets — derived from the URL scheme at connect time. */
+	readonly dialect: "sqlite" | "postgres" | "mysql";
+	query<T = Record<string, unknown>>(
+		sql: string,
+		params?: unknown[],
+	): Promise<T[]>;
+	execute(sql: string, params?: unknown[]): Promise<{ rowsAffected: number }>;
+	/**
+	 * Run every statement in `batch` atomically inside a single sqlx transaction.
+	 * Either every statement commits or none do — used by MigrationRunner to
+	 * wrap `up()` / `down()` SQL together with the `_migrations` bookkeeping.
+	 */
+	runInTransaction(batch: readonly BatchStatement[]): Promise<number>;
+	close(): Promise<void>;
+	ping(): Promise<void>;
+}
+
+/** Shape of the NAPI ReamDatabase class. */
+interface NapiReamDatabase {
+	query(sql: string, paramsJson: string): Promise<string>;
+	execute(sql: string, paramsJson: string): Promise<number>;
+	runInTransaction(batchJson: string): Promise<number>;
+	close(): Promise<void>;
+	ping(): Promise<void>;
+	poolSize(): number;
+}
+
+interface NapiModule {
+	ReamDatabase: {
+		connect(
+			url: string,
+			min: number,
+			max: number,
+			pragmas?: Array<[string, string]>,
+		): Promise<NapiReamDatabase>;
+	};
+}
+
+/**
+ * Connect to a database via the Rust NAPI driver.
+ *
+ *   const db = await createNapiConnection('sqlite:data/app.db')
+ *   const db = await createNapiConnection('postgres://user:pass@host/db')
+ *   const db = await createNapiConnection('mysql://user:pass@host/db')
+ */
+export async function createNapiConnection(
+	url: string,
+	poolMin = 1,
+	poolMax = 10,
+	pragmas?: Record<string, string | number>,
+): Promise<AsyncDatabaseConnection> {
+	const native = await loadNativeDb();
+	if (!native) {
+		throw new Error(
+			"[ATLAS] Rust DB driver (atlas-db-napi) not available. Build with: cargo build --release",
+		);
+	}
+
+	// Validate sqlite pragmas before crossing the NAPI boundary.
+	// PRAGMA syntax doesn't take bound parameters — the Rust side will
+	// interpolate the (key, value) pair into the statement, so the
+	// alphabet is locked to `[A-Za-z0-9_]+` on both sides. Failing
+	// here gives a clearer error than a Rust panic in `after_connect`.
+	const dialect = dialectFromUrl(url);
+	if (dialect === "sqlite" && pragmas) {
+		const safe = /^[A-Za-z0-9_]+$/;
+		for (const [key, value] of Object.entries(pragmas)) {
+			if (!safe.test(key)) {
+				throw new Error(
+					`[ATLAS] Invalid sqlite pragma key: ${JSON.stringify(key)}`,
+				);
+			}
+			if (!safe.test(String(value))) {
+				throw new Error(
+					`[ATLAS] Invalid sqlite pragma value for '${key}': ${JSON.stringify(value)}`,
+				);
+			}
+		}
+	}
+	// Pragmas are pushed THROUGH the NAPI boundary so the Rust side can
+	// wire them into `SqliteConnectOptions::pragma()`. That's the only
+	// path that guarantees every connection sqlx opens for the pool
+	// starts in the requested journal_mode / synchronous state — running
+	// PRAGMA from the query path can silently no-op when the first
+	// pooled connection already claimed the journal in another mode.
+	const pragmaList: Array<[string, string]> | undefined =
+		dialect === "sqlite" && pragmas
+			? Object.entries(pragmas).map(
+					([k, v]) => [k, String(v)] as [string, string],
+				)
+			: undefined;
+
+	const db = await native.ReamDatabase.connect(
+		url,
+		poolMin,
+		poolMax,
+		pragmaList,
+	);
+
+	return {
+		dialect,
+		async query<T = Record<string, unknown>>(
+			sql: string,
+			params: unknown[] = [],
+		): Promise<T[]> {
+			const json = await db.query(sql, JSON.stringify(params));
+			return JSON.parse(json) as T[];
+		},
+
+		async execute(
+			sql: string,
+			params: unknown[] = [],
+		): Promise<{ rowsAffected: number }> {
+			const affected = await db.execute(sql, JSON.stringify(params));
+			return { rowsAffected: affected };
+		},
+
+		async runInTransaction(batch: readonly BatchStatement[]): Promise<number> {
+			// Rust side expects `[[sql, params], ...]`
+			const payload = batch.map((s) => [s.sql, s.params ?? []]);
+			return db.runInTransaction(JSON.stringify(payload));
+		},
+
+		async close(): Promise<void> {
+			await db.close();
+		},
+
+		async ping(): Promise<void> {
+			await db.ping();
+		},
+	};
+}
+
+// dialectFromUrl moved to ../utils/dialectFromUrl.ts — single source of truth
+// shared with AtlasProvider.
+
+/** Load the native DB binding from the prebuilt `.node` binary in the package root. */
+async function loadNativeDb(): Promise<NapiModule | null> {
+	const platform = process.platform;
+	const arch = process.arch;
+	// Same naming convention as napi-rs / src/query/native.ts: the build emits
+	// `db.win32-x64-msvc.node` and `db.linux-x64-gnu.node`, so win32 needs the
+	// `-msvc` ABI tag and linux the `-gnu` one — a bare `win32-x64` misses the file.
+	const suffix =
+		platform === "linux"
+			? `${platform}-${arch}-gnu`
+			: platform === "win32"
+				? `${platform}-${arch}-msvc`
+				: `${platform}-${arch}`;
+	const binaryName = `db.${suffix}.node`;
+
+	try {
+		const { createRequire } = await import("node:module");
+		const { fileURLToPath } = await import("node:url");
+		const { dirname, join } = await import("node:path");
+		const require = createRequire(import.meta.url);
+		const here = dirname(fileURLToPath(import.meta.url));
+		// The binary lives at the package root (../../db.<suffix>.node from src/adapters/)
+		const binaryPath = join(here, "..", "..", binaryName);
+		return require(binaryPath) as NapiModule;
+	} catch {
+		return null;
+	}
+}

package/src/config.ts

@@ -0,0 +1,7 @@
+import type { AtlasDatabaseConfig } from "./AtlasProvider.js";
+
+export function defineConfig(config: AtlasDatabaseConfig): AtlasDatabaseConfig {
+	return config;
+}
+
+export type { AtlasDatabaseConfig };

package/src/configure.ts

@@ -0,0 +1,37 @@
+interface Codemods {
+	addProvider(importPath: string): Promise<void>;
+	addEnvVars(vars: Record<string, string>): Promise<void>;
+	writeFile(
+		filePath: string,
+		content: string,
+		options?: { force?: boolean },
+	): Promise<void>;
+}
+
+export async function configure(codemods: Codemods): Promise<void> {
+	await codemods.addProvider("@c9up/atlas/provider");
+	await codemods.addEnvVars({
+		DB_CONNECTION: "postgres",
+		DB_HOST: "localhost",
+		DB_PORT: "5432",
+		DB_DATABASE: "ream",
+		DB_USER: "postgres",
+		DB_PASSWORD: "secret",
+	});
+	await codemods.writeFile(
+		"config/database.ts",
+		`import { defineConfig } from '@c9up/atlas'
+
+export default defineConfig({
+  connection: process.env.DB_CONNECTION ?? 'postgres',
+  connections: {
+    postgres: {
+      host: process.env.DB_HOST ?? 'localhost',
+      port: Number(process.env.DB_PORT ?? '5432'),
+      database: process.env.DB_DATABASE ?? 'ream',
+    },
+  },
+})
+`,
+	);
+}