fix: remove fake APIs from README, add explain/getColumns to Driver (#11)

- Remove nonexistent APIs from README: Users.ddl(), Posts.ensureColumn(),
  Posts.ensureIndex(), Users.copyColumn()
- Document real APIs: db.ensureTable(), db.ensureView(), db.ensureConstraints(),
  db.copyColumn(), db.explain()
- Make getColumns required on Driver interface (was optional)
- Add explain() to Driver interface - each driver owns its EXPLAIN syntax
- Remove dialect-switching fallback from database.ts #checkColumnExists

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: brainkim

README.md

@@ -595,14 +595,16 @@ IndexedDB-style event-based migrations:
 db.addEventListener("upgradeneeded", (e) => {
   e.waitUntil((async () => {
     if (e.oldVersion < 1) {
-      await db.exec`${Users.ddl()}`;
-      await db.exec`${Posts.ddl()}`;
+      await db.ensureTable(Users);
+      await db.ensureTable(Posts);
     }
     if (e.oldVersion < 2) {
-      await db.exec`${Posts.ensureColumn("views")}`;
+      // Add a new column - just update the schema and call ensureTable again
+      await db.ensureTable(Posts); // Adds missing "views" column
     }
     if (e.oldVersion < 3) {
-      await db.exec`${Posts.ensureIndex(["title"])}`;
+      // Add constraints after data cleanup
+      await db.ensureConstraints(Posts);
     }
   })());
 });
@@ -623,42 +625,51 @@ await db.open(3); // Opens at version 3, fires upgradeneeded if needed
 zen provides idempotent helpers that encourage safe, additive-only migrations:
 
 ```typescript
-// Add a new column (reads from schema)
+// Add a new column - update schema and call ensureTable
 const Posts = table("posts", {
   id: z.string().db.primary(),
   title: z.string(),
   views: z.number().db.inserted(() => 0), // NEW - add to schema
 });
 
 if (e.oldVersion < 2) {
-  await db.exec`${Posts.ensureColumn("views")}`;
+  await db.ensureTable(Posts); // Adds missing columns from schema
 }
-// → ALTER TABLE "posts" ADD COLUMN IF NOT EXISTS "views" REAL DEFAULT 0
+// → ALTER TABLE "posts" ADD COLUMN "views" REAL DEFAULT 0
+
+// Add indexes - defined in schema, applied by ensureTable
+const Posts = table("posts", {
+  id: z.string().db.primary(),
+  title: z.string().db.index(), // NEW - add index
+  views: z.number().db.inserted(() => 0),
+});
 
-// Add an index
 if (e.oldVersion < 3) {
-  await db.exec`${Posts.ensureIndex(["title", "views"])}`;
+  await db.ensureTable(Posts); // Adds missing indexes
 }
-// → CREATE INDEX IF NOT EXISTS "idx_posts_title_views" ON "posts"("title", "views")
+// → CREATE INDEX IF NOT EXISTS "idx_posts_title" ON "posts"("title")
 
 // Safe column rename (additive, non-destructive)
 const Users = table("users", {
-  emailAddress: z.string().email(), // renamed from "email"
+  id: z.string().db.primary(),
+  email: z.string().email(), // Keep old column
+  emailAddress: z.string().email(), // NEW - add new column
 });
 
 if (e.oldVersion < 4) {
-  await db.exec`${Users.ensureColumn("emailAddress")}`;
-  await db.exec`${Users.copyColumn("email", "emailAddress")}`;
+  await db.ensureTable(Users); // Adds emailAddress column
+  await db.copyColumn(Users, "email", "emailAddress"); // Copy data
   // Keep old "email" column for backwards compat
   // Drop it in a later migration if needed (manual SQL)
 }
 // → UPDATE "users" SET "emailAddress" = "email" WHERE "emailAddress" IS NULL
 ```
 
 **Helper methods:**
-- `table.ensureColumn(fieldName, options?)` - Idempotent ALTER TABLE ADD COLUMN
-- `table.ensureIndex(fields, options?)` - Idempotent CREATE INDEX
-- `table.copyColumn(from, to)` - Copy data between columns (for safe renames)
+- `db.ensureTable(table)` - Idempotent CREATE TABLE / ADD COLUMN / CREATE INDEX
+- `db.ensureView(view)` - Idempotent DROP + CREATE VIEW
+- `db.ensureConstraints(table)` - Add unique/FK constraints (with preflight checks)
+- `db.copyColumn(table, from, to)` - Copy data between columns (for safe renames)
 
 All helpers read from your table schema (single source of truth) and are safe to run multiple times (idempotent).
 
@@ -937,25 +948,9 @@ const query = db.print`SELECT * FROM ${Posts} WHERE ${Posts.cols.published} = ${
 console.log(query.sql);     // SELECT * FROM "posts" WHERE "posts"."published" = ?
 console.log(query.params);  // [true]
 
-// Inspect DDL generation
-const ddl = db.print`${Posts.ddl()}`;
-console.log(ddl.sql);  // CREATE TABLE IF NOT EXISTS "posts" (...)
-
-// Analyze query execution plan
-const plan = await db.explain`
-  SELECT * FROM ${Posts}
-  WHERE ${Posts.cols.authorId} = ${userId}
-`;
-console.log(plan);
-// SQLite: [{ detail: "SEARCH posts USING INDEX idx_posts_authorId (authorId=?)" }]
-// PostgreSQL: [{ "QUERY PLAN": "Index Scan using idx_posts_authorId on posts" }]
-
 // Debug fragments
 console.log(Posts.set({ title: "Updated" }).toString());
 // SQLFragment { sql: "\"title\" = ?", params: ["Updated"] }
-
-console.log(Posts.ddl().toString());
-// DDLFragment { type: "create-table", table: "posts" }
 ```
 
 ## Dialect Support
@@ -1085,12 +1080,6 @@ const Posts = table("posts", {
 
 const rows = [{id: "u1", email: "alice@example.com", deletedAt: null}];
 
-// DDL Generation
-Users.ddl();                     // DDLFragment for CREATE TABLE
-Users.ensureColumn("emailAddress"); // DDLFragment for ALTER TABLE ADD COLUMN
-Users.ensureIndex(["email"]);    // DDLFragment for CREATE INDEX
-Users.copyColumn("email", "emailAddress"); // SQLFragment for UPDATE (copy data)
-
 // Query Fragments
 Users.set({email: "alice@example.com"}); // SQLFragment for SET clause
 Users.values(rows);                      // SQLFragment for INSERT VALUES
@@ -1157,9 +1146,15 @@ await db.transaction(async (tx) => {
   await tx.exec`SELECT 1`;
 });
 
+// Schema Management
+await db.ensureTable(Users);           // CREATE TABLE / ADD COLUMN / CREATE INDEX
+await db.ensureView(AdminUsers);       // DROP + CREATE VIEW
+await db.ensureConstraints(Users);     // Add unique/FK constraints
+await db.copyColumn(Users, "old", "new"); // Copy data between columns
+
 // Debugging
-db.print`SELECT 1`;
-await db.explain`SELECT * FROM ${Users}`;
+db.print`SELECT 1`;                       // Returns { sql, params } without executing
+await db.explain`SELECT * FROM ${Users}`; // Returns query execution plan
 ```
 
 ### Driver Exports

src/bun.ts

@@ -532,6 +532,8 @@ export default class BunDriver implements Driver {
 				transaction: async () => {
 					throw new Error("Nested transactions are not supported");
 				},
+				getColumns: this.getColumns.bind(this),
+				explain: this.explain.bind(this),
 			};
 
 			return await fn(txDriver);
@@ -733,6 +735,20 @@ export default class BunDriver implements Driver {
 		return await this.#getColumns(tableName);
 	}
 
+	async explain(
+		strings: TemplateStringsArray,
+		values: unknown[],
+	): Promise<Record<string, unknown>[]> {
+		await this.#ensureSqliteInit();
+		const {sql, params} = buildSQL(strings, values, this.#dialect);
+		const explainPrefix =
+			this.#dialect === "sqlite" ? "EXPLAIN QUERY PLAN " : "EXPLAIN ";
+		return (await this.#sql.unsafe(
+			explainPrefix + sql,
+			params as any[],
+		)) as Record<string, unknown>[];
+	}
+
 	// ==========================================================================
 	// Introspection Helpers (private)
 	// ==========================================================================

src/impl/database.ts

@@ -28,7 +28,6 @@ import {
 	makeTemplate,
 } from "./template.js";
 import {EnsureError} from "./errors.js";
-
 // ============================================================================
 // DB Expressions - Runtime values evaluated by the database
 // ============================================================================
@@ -458,10 +457,16 @@ export interface Driver {
 		toField: string,
 	): Promise<number>;
 
-	/** Optional introspection: list columns for a table (name, type, nullability). */
-	getColumns?(
+	/** Introspection: list columns for a table (name, type, nullability). */
+	getColumns(
 		tableName: string,
 	): Promise<{name: string; type?: string; notnull?: boolean}[]>;
+
+	/** Get the query execution plan for a SQL query. */
+	explain(
+		strings: TemplateStringsArray,
+		values: unknown[],
+	): Promise<Record<string, unknown>[]>;
 }
 
 // ============================================================================
@@ -3103,6 +3108,30 @@ export class Database extends EventTarget {
 		return {sql, params: expandedValues};
 	}
 
+	/**
+	 * Get the query execution plan without running the query.
+	 *
+	 * Returns the database's EXPLAIN output for the given query.
+	 * The format varies by database:
+	 * - SQLite: EXPLAIN QUERY PLAN output
+	 * - PostgreSQL: EXPLAIN output
+	 * - MySQL: EXPLAIN output
+	 *
+	 * @example
+	 * const plan = await db.explain`SELECT * FROM ${Users} WHERE email = ${"test@example.com"}`;
+	 * console.log(plan);
+	 */
+	async explain(
+		strings: TemplateStringsArray,
+		...values: unknown[]
+	): Promise<Record<string, unknown>[]> {
+		const {strings: expandedStrings, values: expandedValues} = expandFragments(
+			strings,
+			values,
+		);
+		return await this.#driver.explain(expandedStrings, expandedValues);
+	}
+
 	// ==========================================================================
 	// Schema Ensure Methods
 	// ==========================================================================
@@ -3316,41 +3345,8 @@ export class Database extends EventTarget {
 		tableName: string,
 		columnName: string,
 	): Promise<boolean> {
-		// Use driver's getColumns if available
-		if (this.#driver.getColumns) {
-			const columns = await this.#driver.getColumns(tableName);
-			return columns.some((col) => col.name === columnName);
-		}
-
-		// Try PRAGMA table_info first (SQLite)
-		try {
-			const pragmaStrings = makeTemplate(["PRAGMA table_info(", ")"]);
-			const pragmaValues = [ident(tableName)];
-			const columns = await this.#driver.all<{name: string}>(
-				pragmaStrings,
-				pragmaValues,
-			);
-			if (columns.length > 0) {
-				return columns.some((col) => col.name === columnName);
-			}
-		} catch {
-			// Not SQLite, try information_schema
-		}
-
-		// Fallback: information_schema (PostgreSQL/MySQL)
-		try {
-			const schemaStrings = makeTemplate([
-				"SELECT column_name FROM information_schema.columns WHERE table_name = ",
-				" AND column_name = ",
-				" LIMIT 1",
-			]);
-			const schemaValues = [tableName, columnName];
-			const result = await this.#driver.all(schemaStrings, schemaValues);
-			return result.length > 0;
-		} catch {
-			// Last resort: assume column exists and let the UPDATE fail naturally
-			return true;
-		}
+		const columns = await this.#driver.getColumns(tableName);
+		return columns.some((col) => col.name === columnName);
 	}
 
 	// ==========================================================================

src/mysql.ts

@@ -379,6 +379,8 @@ export default class MySQLDriver implements Driver {
 				transaction: async () => {
 					throw new Error("Nested transactions are not supported");
 				},
+				getColumns: this.getColumns.bind(this),
+				explain: this.explain.bind(this),
 			};
 
 			const result = await fn(txDriver);
@@ -604,7 +606,7 @@ export default class MySQLDriver implements Driver {
 		return ((rows as any[])[0]?.count ?? 0) > 0;
 	}
 
-	async #getColumns(
+	async getColumns(
 		tableName: string,
 	): Promise<{name: string; type: string; notnull: boolean}[]> {
 		const [rows] = await this.#pool.execute<mysql.RowDataPacket[]>(
@@ -619,6 +621,15 @@ export default class MySQLDriver implements Driver {
 		}));
 	}
 
+	async explain(
+		strings: TemplateStringsArray,
+		values: unknown[],
+	): Promise<Record<string, unknown>[]> {
+		const {sql, params} = buildSQL(strings, values);
+		const [rows] = await this.#pool.execute(`EXPLAIN ${sql}`, params);
+		return rows as Record<string, unknown>[];
+	}
+
 	async #getIndexes(
 		tableName: string,
 	): Promise<{name: string; columns: string[]; unique: boolean}[]> {
@@ -698,7 +709,7 @@ export default class MySQLDriver implements Driver {
 	}
 
 	async #ensureMissingColumns(table: Table): Promise<boolean> {
-		const existingCols = await this.#getColumns(table.name);
+		const existingCols = await this.getColumns(table.name);
 		const existingColNames = new Set(existingCols.map((c) => c.name));
 		const schemaFields = Object.keys(table.schema.shape);
 

src/postgres.ts

@@ -331,6 +331,8 @@ export default class PostgresDriver implements Driver {
 				transaction: async () => {
 					throw new Error("Nested transactions are not supported");
 				},
+				getColumns: this.getColumns.bind(this),
+				explain: this.explain.bind(this),
 			};
 
 			return await fn(txDriver);
@@ -541,7 +543,7 @@ export default class PostgresDriver implements Driver {
 		return result[0]?.exists ?? false;
 	}
 
-	async #getColumns(
+	async getColumns(
 		tableName: string,
 	): Promise<{name: string; type: string; notnull: boolean}[]> {
 		const result = await this.#sql<
@@ -561,6 +563,17 @@ export default class PostgresDriver implements Driver {
 		}));
 	}
 
+	async explain(
+		strings: TemplateStringsArray,
+		values: unknown[],
+	): Promise<Record<string, unknown>[]> {
+		const {sql, params} = buildSQL(strings, values);
+		return await this.#sql.unsafe<Record<string, unknown>[]>(
+			`EXPLAIN ${sql}`,
+			params as any[],
+		);
+	}
+
 	async #getIndexes(
 		tableName: string,
 	): Promise<{name: string; columns: string[]; unique: boolean}[]> {
@@ -651,7 +664,7 @@ export default class PostgresDriver implements Driver {
 	}
 
 	async #ensureMissingColumns(table: Table): Promise<boolean> {
-		const existingCols = await this.#getColumns(table.name);
+		const existingCols = await this.getColumns(table.name);
 		const existingColNames = new Set(existingCols.map((c) => c.name));
 		const schemaFields = Object.keys(table.schema.shape);
 

src/sqlite.ts

@@ -482,7 +482,7 @@ export default class SQLiteDriver implements Driver {
 		return result.length > 0;
 	}
 
-	async #getColumns(
+	async getColumns(
 		tableName: string,
 	): Promise<{name: string; type: string; notnull: boolean}[]> {
 		const result = this.#db
@@ -495,6 +495,16 @@ export default class SQLiteDriver implements Driver {
 		}));
 	}
 
+	async explain(
+		strings: TemplateStringsArray,
+		values: unknown[],
+	): Promise<Record<string, unknown>[]> {
+		const {sql, params} = buildSQL(strings, values);
+		return this.#db
+			.prepare(`EXPLAIN QUERY PLAN ${sql}`)
+			.all(...params) as Record<string, unknown>[];
+	}
+
 	async #getIndexes(
 		tableName: string,
 	): Promise<{name: string; columns: string[]; unique: boolean}[]> {
@@ -579,7 +589,7 @@ export default class SQLiteDriver implements Driver {
 	async #ensureMissingColumns<T extends Table<any>>(
 		table: T,
 	): Promise<boolean> {
-		const existingCols = await this.#getColumns(table.name);
+		const existingCols = await this.getColumns(table.name);
 		const existingColNames = new Set(existingCols.map((c) => c.name));
 		const schemaFields = Object.keys(table.schema.shape);