@c9up/atlas 0.1.19 → 0.2.1

package/src/schema/catalog.ts

@@ -0,0 +1,236 @@
+/**
+ * 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 { AtlasError } from "../errors.js";
+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>;
+	/**
+	 * 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>;
+}
+
+/**
+ * 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;
+	/**
+	 * 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`. */
+export async function listUserTables(
+	db: CatalogConnection,
+	dialect: AtlasDialect,
+	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":
+			// 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 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, params);
+	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 runWithoutForeignKeys(
+	db: CatalogConnection,
+	dialect: AtlasDialect,
+	statements: ReadonlyArray<{ sql: string; params?: unknown[] }>,
+): Promise<void> {
+	if (statements.length === 0) return;
+
+	// 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/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/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";