@c9up/atlas 0.1.18 → 0.2.0

package/src/schema/catalog.ts

@@ -0,0 +1,166 @@
+/**
+ * Dialect-aware catalog queries — "which base tables exist right now".
+ *
+ * The single source of truth for listing user tables, shared by the migration
+ * runner's drop/wipe and the test-time `truncateAll`. Each query hits the
+ * dialect's own catalog (`sqlite_master`, `pg_tables`, `information_schema`);
+ * they are framework introspection, not user queries, so they stay raw SQL.
+ */
+
+import type { AtlasDialect } from "../query/native.js";
+
+/**
+ * The minimal connection surface these helpers need — just `query`/`execute`.
+ * Narrower than `AsyncDatabaseConnection` on purpose, so the migration runner's
+ * `DatabaseAdapter` (which has no `dialect`/`ping`) satisfies it too.
+ */
+export interface CatalogConnection {
+	query<T = Record<string, unknown>>(
+		sql: string,
+		params?: unknown[],
+	): Promise<T[]>;
+	// 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>;
+}
+
+/**
+ * Prefix for framework-private tables (migrations bookkeeping), following the
+ * same `ream_`-prefix convention as AdonisJS's `adonis_`.
+ */
+const FRAMEWORK_PREFIX = "ream_";
+
+export interface ListTablesOptions {
+	/**
+	 * Include `ream_*` framework tables (the migrations table). Off by default
+	 * so cleanup helpers leave the bookkeeping intact; `fresh()` turns it on
+	 * because it re-creates the tracking table afterwards.
+	 */
+	includeFrameworkTables?: boolean;
+}
+
+/** List every base table in the current schema/database, for `dialect`. */
+export async function listUserTables(
+	db: CatalogConnection,
+	dialect: AtlasDialect,
+	options: ListTablesOptions = {},
+): Promise<string[]> {
+	let sql: string;
+	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()";
+			break;
+		case "mysql":
+			sql =
+				"SELECT table_name 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 names: string[] = [];
+	for (const row of rows) {
+		if (typeof row.name !== "string") continue;
+		if (
+			!options.includeFrameworkTables &&
+			row.name.startsWith(FRAMEWORK_PREFIX)
+		) {
+			continue;
+		}
+		names.push(row.name);
+	}
+	return names;
+}
+
+/**
+ * Does base table `name` exist right now, for `dialect`? The name is passed as a
+ * bound parameter (never interpolated) so this is injection-safe on every
+ * dialect. Backs `Schema.hasTable` (Adonis Lucid parity).
+ */
+export async function tableExists(
+	db: CatalogConnection,
+	dialect: AtlasDialect,
+	name: string,
+): Promise<boolean> {
+	const ph = dialect === "postgres" ? "$1" : "?";
+	let sql: string;
+	switch (dialect) {
+		case "sqlite":
+			sql = `SELECT 1 FROM sqlite_master WHERE type='table' AND name = ${ph}`;
+			break;
+		case "postgres":
+			sql = `SELECT 1 FROM pg_tables WHERE schemaname = current_schema() AND tablename = ${ph}`;
+			break;
+		case "mysql":
+			sql = `SELECT 1 FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ${ph} AND table_type = 'BASE TABLE'`;
+			break;
+	}
+	const rows = await db.query(sql, [name]);
+	return rows.length > 0;
+}
+
+/**
+ * Does column `column` exist on table `table` right now, for `dialect`? Both
+ * names are bound parameters. Backs `Schema.hasColumn` (Adonis Lucid parity).
+ */
+export async function columnExists(
+	db: CatalogConnection,
+	dialect: AtlasDialect,
+	table: string,
+	column: string,
+): Promise<boolean> {
+	if (dialect === "sqlite") {
+		// PRAGMA introspection via the table-valued function form, which accepts a
+		// bound table-name argument (unlike `PRAGMA table_info(x)`).
+		const rows = await db.query(
+			"SELECT 1 FROM pragma_table_info(?) WHERE name = ?",
+			[table, column],
+		);
+		return rows.length > 0;
+	}
+	const [p1, p2] = dialect === "postgres" ? ["$1", "$2"] : ["?", "?"];
+	const schemaPredicate =
+		dialect === "postgres"
+			? "table_schema = current_schema()"
+			: "table_schema = DATABASE()";
+	const rows = await db.query(
+		`SELECT 1 FROM information_schema.columns WHERE ${schemaPredicate} AND table_name = ${p1} AND column_name = ${p2}`,
+		[table, column],
+	);
+	return rows.length > 0;
+}
+
+/**
+ * Run `fn` with foreign-key enforcement suspended, then restore it — the toggle
+ * runs even if `fn` throws. Lets a bulk drop/truncate ignore inter-table FK
+ * 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>(
+	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;
+
+	if (off) await db.execute(off);
+	try {
+		return await fn();
+	} finally {
+		if (on) await db.execute(on);
+	}
+}

package/src/schema/introspect.ts

@@ -65,9 +65,7 @@ async function introspectSqlite(
 	db: SchemaIntrospectable,
 	table: string,
 ): Promise<IntrospectedColumn[] | null> {
-	const rows = await db.query(
-		`SELECT * FROM pragma_table_info('${table}')`,
-	);
+	const rows = await db.query(`SELECT * FROM pragma_table_info('${table}')`);
 	if (rows.length === 0) return null; // unknown table → no columns
 	return rows.map((r) => ({
 		name: String(r.name),
@@ -128,6 +126,7 @@ async function introspectMysql(
 		hasDefault:
 			(r.column_default ?? r.COLUMN_DEFAULT) !== null &&
 			(r.column_default ?? r.COLUMN_DEFAULT) !== undefined,
-		primaryKey: String(r.column_key ?? r.COLUMN_KEY ?? "").toUpperCase() === "PRI",
+		primaryKey:
+			String(r.column_key ?? r.COLUMN_KEY ?? "").toUpperCase() === "PRI",
 	}));
 }

package/src/schema/types.ts

@@ -6,33 +6,69 @@
 export type ColumnType =
 	| "string"
 	| "text"
+	| "mediumtext"
+	| "longtext"
 	| "integer"
+	| "tinyint"
+	| "smallint"
+	| "mediumint"
 	| "bigInteger"
 	| "decimal"
+	| "float"
+	| "double"
 	| "boolean"
 	| "date"
+	| "time"
 	| "timestamp"
 	| "timestamptz"
 	| "uuid"
 	| "json"
-	| "binary";
+	| "jsonb"
+	| "binary"
+	| "enum"
+	| "specificType";
 
 /** Maps our logical type names to the ColumnTypeKind expected by the Rust compiler. */
 export const TYPE_KIND_MAP: Record<ColumnType, string> = {
 	string: "string",
 	text: "text",
+	mediumtext: "mediumText",
+	longtext: "longText",
 	integer: "integer",
+	tinyint: "tinyInt",
+	smallint: "smallInt",
+	mediumint: "mediumInt",
 	bigInteger: "bigInteger",
 	decimal: "decimal",
+	float: "float",
+	double: "double",
 	boolean: "boolean",
 	date: "date",
+	time: "time",
 	timestamp: "timestamp",
 	timestamptz: "timestamptz",
 	uuid: "uuid",
 	json: "json",
+	jsonb: "jsonb",
 	binary: "binary",
+	enum: "enum",
+	specificType: "specificType",
 };
 
+/** MySQL text width (Lucid/Knex `text(name, textType)`). `TEXT` on pg/sqlite. */
+export type TextVariant = "text" | "mediumtext" | "longtext";
+
+/**
+ * SQL referential action for a foreign key's `ON DELETE` / `ON UPDATE`
+ * (Lucid parity). Validated case-insensitively by the Rust compiler.
+ */
+export type ReferentialAction =
+	| "cascade"
+	| "restrict"
+	| "set null"
+	| "set default"
+	| "no action";
+
 export interface ColumnDefinition {
 	name: string;
 	type: ColumnType;
@@ -44,8 +80,29 @@ export interface ColumnDefinition {
 	/** Dialect-appropriate auto-increment / identity column (Lucid `increments`). Implies primary key. */
 	autoIncrement?: boolean;
 	unique: boolean;
+	/** MySQL `UNSIGNED` numeric modifier (Lucid `unsigned()`). No-op on pg/sqlite. */
+	unsigned?: boolean;
+	/** Allowed values for an `enum` column. */
+	values?: string[];
+	/**
+	 * Verbatim SQL type for a `specificType` column. Validated by the Rust
+	 * compiler against a narrow grammar before it reaches DDL — it is
+	 * interpolated, not bound.
+	 */
+	rawType?: string;
+	/** Column comment. Inline on MySQL, `COMMENT ON COLUMN` on pg, dropped on SQLite. */
+	comment?: string;
+	/** Column collation, e.g. `utf8mb4_unicode_ci`. Validated as an identifier. */
+	collate?: string;
+	/** MySQL-only placement of an added column (`FIRST` / `AFTER col`). */
+	position?: ColumnPosition;
 	defaultValue?: string;
-	references?: { table: string; column: string };
+	references?: {
+		table: string;
+		column: string;
+		onDelete?: ReferentialAction;
+		onUpdate?: ReferentialAction;
+	};
 }
 
 export interface IndexDefinition {
@@ -53,3 +110,81 @@ export interface IndexDefinition {
 	columns: string[];
 	unique: boolean;
 }
+
+/** MySQL-only placement of an added column. Mirrors the Rust `ColumnPosition`. */
+export type ColumnPosition = { at: "first" } | { at: "after"; column: string };
+
+/** A scalar a CHECK constraint can compare against. DDL cannot bind params — these are quoted, not bound. */
+export type CheckValue = string | number | boolean | null;
+
+/**
+ * A CHECK predicate. Structured rather than free-form SQL so each variant is
+ * safe by construction; `raw` is the escape hatch and is exactly as trusted as
+ * `schema.raw()`. Mirrors the Rust `CheckExpr` tagged union.
+ */
+export type CheckExpression =
+	| { check: "positive"; column: string }
+	| { check: "negative"; column: string }
+	| { check: "in"; column: string; values: CheckValue[] }
+	| { check: "notIn"; column: string; values: CheckValue[] }
+	| { check: "between"; column: string; ranges: CheckValue[][] }
+	| { check: "length"; column: string; operator: string; length: number }
+	| { check: "regex"; column: string; pattern: string }
+	| { check: "raw"; predicate: string };
+
+/** Comparison operator accepted by `checkLength` (Lucid/Knex). */
+export type CheckOperator = "=" | "!=" | "<>" | "<" | "<=" | ">" | ">=";
+
+/** A multi-column foreign key target. Mirrors the Rust `ForeignKeyRefMulti`. */
+export interface ForeignKeyReference {
+	table: string;
+	columns: string[];
+	onDelete?: ReferentialAction;
+	onUpdate?: ReferentialAction;
+}
+
+/** A table-level constraint. Mirrors the Rust `TableConstraint` tagged union. */
+export type TableConstraintSpec =
+	| { constraint: "primary"; name?: string; columns: string[] }
+	| { constraint: "unique"; name?: string; columns: string[] }
+	| {
+			constraint: "foreign";
+			name?: string;
+			columns: string[];
+			references: ForeignKeyReference;
+	  }
+	| { constraint: "check"; name?: string; expr: CheckExpression };
+
+/** Storage options for `CREATE TABLE`. Mirrors the Rust `TableOptions`. */
+export interface TableOptionsSpec {
+	engine?: string;
+	charset?: string;
+	collate?: string;
+	comment?: string;
+}
+
+/**
+ * One ALTER TABLE operation, in call order (Lucid/Knex semantics). Mirrors the
+ * Rust `AlterOp` tagged union — the `op` tags and field names are the wire
+ * contract with `compile_alter_table`.
+ */
+export type AlterOperation =
+	| { op: "addColumn"; column: ColumnDefinition }
+	| { op: "dropColumn"; name: string }
+	| { op: "renameColumn"; from: string; to: string }
+	| {
+			op: "alterColumn";
+			column: ColumnDefinition;
+			/**
+			 * Tri-state. `undefined` leaves nullability untouched so a bare type
+			 * change never silently adds a NOT NULL — only an explicit
+			 * `.nullable()` / `.notNullable()` before `.alter()` sets it.
+			 */
+			setNullable?: boolean;
+	  }
+	| { op: "setNullable"; name: string; nullable: boolean }
+	| { op: "addConstraint"; constraint: TableConstraintSpec }
+	| { op: "dropConstraint"; name: string }
+	| { op: "dropPrimary"; name?: string }
+	| { op: "dropUnique"; name: string }
+	| { op: "dropForeign"; name: string };

package/src/services/db.ts

@@ -49,6 +49,34 @@ 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>();
+
+/** @internal Register a named connection (called by AtlasProvider.boot per connection). */
+export function registerConnection(
+	name: string,
+	connection: AsyncDatabaseConnection,
+): void {
+	namedConnections.set(name, connection);
+}
+
+/** @internal Unregister a named connection IF it still points at `connection`. */
+export function unregisterConnection(
+	name: string,
+	connection: AsyncDatabaseConnection,
+): void {
+	if (namedConnections.get(name) === connection) namedConnections.delete(name);
+}
+
+/** @internal Resolve a named connection (for `BaseModel.connection`), or `undefined`. */
+export function getConnection(
+	name: string,
+): AsyncDatabaseConnection | undefined {
+	return namedConnections.get(name);
+}
+
 const db: DbService = new Proxy({} as DbService, {
 	get(_target, prop) {
 		// `raw` is a pure builder (no connection needed) — available pre-boot too.

package/src/testing/DatabaseCleanup.ts

@@ -5,7 +5,8 @@
  */
 
 import type { AsyncDatabaseConnection } from "../adapters/NapiDbAdapter.js";
-import { compileStatementNative, getAtlasDialect } from "../query/native.js";
+import { compileStatementNative } from "../query/native.js";
+import { listUserTables, withoutForeignKeys } from "../schema/catalog.js";
 
 /**
  * Wrap a test in a savepoint that is rolled back after.
@@ -21,28 +22,28 @@ export async function useTransaction(
 }
 
 /**
- * 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, 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).
  */
 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_%'",
-	);
-	const dialect = getAtlasDialect();
-	for (const row of tables) {
-		const name = row.name;
-		if (typeof name !== "string") continue;
-		const compiled = compileStatementNative(
-			{ kind: "delete", table: name, wheres: [] },
-			dialect,
-		);
-		await db.execute(compiled.statements[0], compiled.params);
-	}
+	// 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);
+	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);
+		}
+	});
 }