@b9g/zen 0.1.0

package/src/mysql.d.ts

@@ -0,0 +1,62 @@
+/**
+ * mysql2 adapter for @b9g/zen
+ *
+ * Provides a Driver implementation for mysql2.
+ * Uses connection pooling - call close() when done to end all connections.
+ *
+ * Requires: mysql2
+ */
+import type { Driver, Table, EnsureResult } from "./zen.js";
+/**
+ * Options for the mysql adapter.
+ */
+export interface MySQLOptions {
+    /** Maximum number of connections in the pool (default: 10) */
+    connectionLimit?: number;
+    /** Idle timeout in milliseconds (default: 60000) */
+    idleTimeout?: number;
+    /** Connection timeout in milliseconds (default: 10000) */
+    connectTimeout?: number;
+}
+/**
+ * MySQL driver using mysql2.
+ *
+ * @example
+ * import MySQLDriver from "@b9g/zen/mysql";
+ * import {Database} from "@b9g/zen";
+ *
+ * const driver = new MySQLDriver("mysql://localhost/mydb");
+ * const db = new Database(driver);
+ *
+ * db.addEventListener("upgradeneeded", (e) => {
+ *   e.waitUntil(runMigrations(e));
+ * });
+ *
+ * await db.open(1);
+ *
+ * // When done:
+ * await driver.close();
+ */
+export default class MySQLDriver implements Driver {
+    #private;
+    readonly supportsReturning = false;
+    constructor(url: string, options?: MySQLOptions);
+    all<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T[]>;
+    get<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    run(strings: TemplateStringsArray, values: unknown[]): Promise<number>;
+    val<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    close(): Promise<void>;
+    transaction<T>(fn: (txDriver: Driver) => Promise<T>): Promise<T>;
+    withMigrationLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Ensure table exists with the specified structure.
+     * Creates table if missing, adds missing columns/indexes.
+     * Throws SchemaDriftError if constraints are missing.
+     */
+    ensureTable<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Ensure constraints exist on the table.
+     * Applies unique and foreign key constraints with preflight checks.
+     */
+    ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+}

package/src/mysql.js

@@ -0,0 +1,573 @@
+/// <reference types="./mysql.d.ts" />
+import {
+  quoteIdent,
+  renderDDL
+} from "../chunk-2IEEEMRN.js";
+import {
+  generateColumnDDL,
+  generateDDL
+} from "../chunk-QXGEP5PB.js";
+import {
+  ConstraintPreflightError,
+  EnsureError,
+  SchemaDriftError,
+  getTableMeta,
+  resolveSQLBuiltin
+} from "../chunk-56M5Z3A6.js";
+
+// src/mysql.ts
+import {
+  ConstraintViolationError,
+  isSQLBuiltin,
+  isSQLIdentifier
+} from "./zen.js";
+import mysql from "mysql2/promise";
+var DIALECT = "mysql";
+function quoteIdent2(name) {
+  return quoteIdent(name, DIALECT);
+}
+function buildSQL(strings, values) {
+  let sql = strings[0];
+  const params = [];
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    if (isSQLBuiltin(value)) {
+      sql += resolveSQLBuiltin(value) + strings[i + 1];
+    } else if (isSQLIdentifier(value)) {
+      sql += quoteIdent2(value.name) + strings[i + 1];
+    } else {
+      sql += "?" + strings[i + 1];
+      params.push(value);
+    }
+  }
+  return { sql, params };
+}
+var MySQLDriver = class {
+  supportsReturning = false;
+  #pool;
+  constructor(url, options = {}) {
+    this.#pool = mysql.createPool({
+      uri: url,
+      connectionLimit: options.connectionLimit ?? 10,
+      idleTimeout: options.idleTimeout ?? 6e4,
+      connectTimeout: options.connectTimeout ?? 1e4
+    });
+  }
+  /**
+   * Convert MySQL errors to Zealot errors.
+   */
+  #handleError(error) {
+    if (error && typeof error === "object" && "code" in error) {
+      const code = error.code;
+      const message = error.message || String(error);
+      let kind = "unknown";
+      let constraint;
+      let table;
+      let column;
+      if (code === "ER_DUP_ENTRY") {
+        kind = "unique";
+        const keyMatch = message.match(/for key '([^']+)'/i);
+        constraint = keyMatch ? keyMatch[1] : void 0;
+        if (constraint) {
+          const parts = constraint.split(".");
+          if (parts.length > 1) {
+            table = parts[0];
+          }
+        }
+      } else if (code === "ER_NO_REFERENCED_ROW_2" || code === "ER_ROW_IS_REFERENCED_2") {
+        kind = "foreign_key";
+        const constraintMatch = message.match(/CONSTRAINT `([^`]+)`/i);
+        constraint = constraintMatch ? constraintMatch[1] : void 0;
+        const tableMatch = message.match(/`([^`]+)`\.`([^`]+)`/);
+        if (tableMatch) {
+          table = tableMatch[2];
+        }
+      }
+      if (code === "ER_DUP_ENTRY" || code === "ER_NO_REFERENCED_ROW_2" || code === "ER_ROW_IS_REFERENCED_2") {
+        throw new ConstraintViolationError(
+          message,
+          {
+            kind,
+            constraint,
+            table,
+            column
+          },
+          {
+            cause: error
+          }
+        );
+      }
+    }
+    throw error;
+  }
+  async all(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const [rows] = await this.#pool.execute(sql, params);
+      return rows;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async get(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const [rows] = await this.#pool.execute(sql, params);
+      return rows[0] ?? null;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async run(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const [result] = await this.#pool.execute(sql, params);
+      return result.affectedRows ?? 0;
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async val(strings, values) {
+    try {
+      const { sql, params } = buildSQL(strings, values);
+      const [rows] = await this.#pool.execute(sql, params);
+      const row = rows[0];
+      if (!row)
+        return null;
+      const rowValues = Object.values(row);
+      return rowValues[0];
+    } catch (error) {
+      return this.#handleError(error);
+    }
+  }
+  async close() {
+    await this.#pool.end();
+  }
+  async transaction(fn) {
+    const connection = await this.#pool.getConnection();
+    const handleError = this.#handleError.bind(this);
+    try {
+      await connection.query("START TRANSACTION");
+      const txDriver = {
+        supportsReturning: false,
+        all: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const [rows] = await connection.execute(sql, params);
+            return rows;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        get: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const [rows] = await connection.execute(sql, params);
+            return rows[0] ?? null;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        run: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const [result2] = await connection.execute(sql, params);
+            return result2.affectedRows ?? 0;
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        val: async (strings, values) => {
+          try {
+            const { sql, params } = buildSQL(strings, values);
+            const [rows] = await connection.execute(sql, params);
+            const row = rows[0];
+            if (!row)
+              return null;
+            const rowValues = Object.values(row);
+            return rowValues[0];
+          } catch (error) {
+            return handleError(error);
+          }
+        },
+        close: async () => {
+        },
+        transaction: async () => {
+          throw new Error("Nested transactions are not supported");
+        }
+      };
+      const result = await fn(txDriver);
+      await connection.query("COMMIT");
+      return result;
+    } catch (error) {
+      await connection.query("ROLLBACK");
+      throw error;
+    } finally {
+      connection.release();
+    }
+  }
+  async withMigrationLock(fn) {
+    const LOCK_NAME = "zen_migration";
+    const LOCK_TIMEOUT = 10;
+    const [lockResult] = await this.#pool.execute(`SELECT GET_LOCK(?, ?)`, [
+      LOCK_NAME,
+      LOCK_TIMEOUT
+    ]);
+    const acquired = lockResult[0]?.["GET_LOCK(?, ?)"] === 1;
+    if (!acquired) {
+      throw new Error(
+        `Failed to acquire migration lock after ${LOCK_TIMEOUT}s. Another migration may be in progress.`
+      );
+    }
+    try {
+      return await fn();
+    } finally {
+      await this.#pool.execute(`SELECT RELEASE_LOCK(?)`, [LOCK_NAME]);
+    }
+  }
+  // ========================================================================
+  // Schema Management Methods
+  // ========================================================================
+  /**
+   * Ensure table exists with the specified structure.
+   * Creates table if missing, adds missing columns/indexes.
+   * Throws SchemaDriftError if constraints are missing.
+   */
+  async ensureTable(table) {
+    const tableName = table.name;
+    let step = 0;
+    let applied = false;
+    try {
+      const exists = await this.#tableExists(tableName);
+      if (!exists) {
+        step = 1;
+        const ddlTemplate = generateDDL(table, { dialect: DIALECT });
+        const ddlSQL = renderDDL(ddlTemplate[0], ddlTemplate.slice(1), DIALECT);
+        for (const stmt of ddlSQL.split(";").filter((s) => s.trim())) {
+          await this.#pool.execute(stmt.trim(), []);
+        }
+        applied = true;
+      } else {
+        step = 2;
+        const columnsApplied = await this.#ensureMissingColumns(table);
+        applied = applied || columnsApplied;
+        step = 3;
+        const indexesApplied = await this.#ensureMissingIndexes(table);
+        applied = applied || indexesApplied;
+        step = 4;
+        await this.#checkMissingConstraints(table);
+      }
+      return { applied };
+    } catch (error) {
+      if (error instanceof SchemaDriftError || error instanceof ConstraintPreflightError) {
+        throw error;
+      }
+      throw new EnsureError(
+        `Failed to ensure table "${tableName}" exists (step ${step})`,
+        {
+          operation: "ensureTable",
+          table: tableName,
+          step
+        },
+        {
+          cause: error
+        }
+      );
+    }
+  }
+  /**
+   * Ensure constraints exist on the table.
+   * Applies unique and foreign key constraints with preflight checks.
+   */
+  async ensureConstraints(table) {
+    const tableName = table.name;
+    let step = 0;
+    let applied = false;
+    try {
+      step = 1;
+      const existingConstraints = await this.#getConstraints(tableName);
+      step = 2;
+      const uniqueApplied = await this.#ensureUniqueConstraints(
+        table,
+        existingConstraints
+      );
+      applied = applied || uniqueApplied;
+      step = 3;
+      const fkApplied = await this.#ensureForeignKeys(
+        table,
+        existingConstraints
+      );
+      applied = applied || fkApplied;
+      return { applied };
+    } catch (error) {
+      if (error instanceof SchemaDriftError || error instanceof ConstraintPreflightError) {
+        throw error;
+      }
+      throw new EnsureError(
+        `Failed to ensure constraints on table "${tableName}" (step ${step})`,
+        {
+          operation: "ensureConstraints",
+          table: tableName,
+          step
+        },
+        {
+          cause: error
+        }
+      );
+    }
+  }
+  // ========================================================================
+  // Private Helper Methods
+  // ========================================================================
+  async #tableExists(tableName) {
+    const [rows] = await this.#pool.execute(
+      `SELECT COUNT(*) as count FROM information_schema.tables WHERE table_schema = DATABASE() AND table_name = ?`,
+      [tableName]
+    );
+    return (rows[0]?.count ?? 0) > 0;
+  }
+  async #getColumns(tableName) {
+    const [rows] = await this.#pool.execute(
+      `SELECT COLUMN_NAME, DATA_TYPE, IS_NULLABLE FROM information_schema.columns WHERE table_schema = DATABASE() AND table_name = ? ORDER BY ordinal_position`,
+      [tableName]
+    );
+    return rows.map((row) => ({
+      name: row.COLUMN_NAME,
+      type: row.DATA_TYPE,
+      notnull: row.IS_NULLABLE === "NO"
+    }));
+  }
+  async #getIndexes(tableName) {
+    const [rows] = await this.#pool.execute(
+      `SELECT
+				INDEX_NAME,
+				GROUP_CONCAT(COLUMN_NAME ORDER BY SEQ_IN_INDEX) as COLUMNS,
+				MAX(NON_UNIQUE = 0) as IS_UNIQUE
+			FROM information_schema.statistics
+			WHERE table_schema = DATABASE() AND table_name = ? AND INDEX_NAME != 'PRIMARY'
+			GROUP BY INDEX_NAME`,
+      [tableName]
+    );
+    return rows.map((row) => ({
+      name: row.INDEX_NAME,
+      columns: row.COLUMNS.split(","),
+      unique: row.IS_UNIQUE === 1
+    }));
+  }
+  async #getConstraints(tableName) {
+    const constraints = [];
+    const indexes = await this.#getIndexes(tableName);
+    for (const idx of indexes) {
+      if (idx.unique) {
+        constraints.push({
+          name: idx.name,
+          type: "unique",
+          columns: idx.columns
+        });
+      }
+    }
+    const [fkRows] = await this.#pool.execute(
+      `SELECT
+				CONSTRAINT_NAME,
+				GROUP_CONCAT(COLUMN_NAME ORDER BY ORDINAL_POSITION) as COLUMNS,
+				REFERENCED_TABLE_NAME,
+				GROUP_CONCAT(REFERENCED_COLUMN_NAME ORDER BY ORDINAL_POSITION) as REF_COLUMNS
+			FROM information_schema.key_column_usage
+			WHERE table_schema = DATABASE()
+				AND table_name = ?
+				AND REFERENCED_TABLE_NAME IS NOT NULL
+			GROUP BY CONSTRAINT_NAME, REFERENCED_TABLE_NAME`,
+      [tableName]
+    );
+    for (const row of fkRows) {
+      constraints.push({
+        name: row.CONSTRAINT_NAME,
+        type: "foreign_key",
+        columns: row.COLUMNS.split(","),
+        referencedTable: row.REFERENCED_TABLE_NAME,
+        referencedColumns: row.REF_COLUMNS.split(",")
+      });
+    }
+    return constraints;
+  }
+  async #ensureMissingColumns(table) {
+    const existingCols = await this.#getColumns(table.name);
+    const existingColNames = new Set(existingCols.map((c) => c.name));
+    const schemaFields = Object.keys(table.schema.shape);
+    let applied = false;
+    for (const fieldName of schemaFields) {
+      if (!existingColNames.has(fieldName)) {
+        await this.#addColumn(table, fieldName);
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #addColumn(table, fieldName) {
+    const zodType = table.schema.shape[fieldName];
+    const fieldMeta = getTableMeta(table).fields[fieldName] || {};
+    const colTemplate = generateColumnDDL(
+      fieldName,
+      zodType,
+      fieldMeta,
+      DIALECT
+    );
+    const colSQL = renderDDL(colTemplate[0], colTemplate.slice(1), DIALECT);
+    await this.#pool.execute(
+      `ALTER TABLE ${quoteIdent2(table.name)} ADD COLUMN ${colSQL}`,
+      []
+    );
+  }
+  async #ensureMissingIndexes(table) {
+    const existingIndexes = await this.#getIndexes(table.name);
+    const existingIndexNames = new Set(existingIndexes.map((idx) => idx.name));
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const fieldName of meta.indexed) {
+      const indexName = `idx_${table.name}_${fieldName}`;
+      if (!existingIndexNames.has(indexName)) {
+        await this.#createIndex(table.name, [fieldName], false);
+        applied = true;
+      }
+    }
+    for (const indexCols of table.indexes) {
+      const indexName = `idx_${table.name}_${indexCols.join("_")}`;
+      if (!existingIndexNames.has(indexName)) {
+        await this.#createIndex(table.name, indexCols, false);
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #createIndex(tableName, columns, unique) {
+    const prefix = unique ? "uniq" : "idx";
+    const indexName = `${prefix}_${tableName}_${columns.join("_")}`;
+    const uniqueClause = unique ? "UNIQUE " : "";
+    const columnList = columns.map(quoteIdent2).join(", ");
+    const sql = `CREATE ${uniqueClause}INDEX ${quoteIdent2(indexName)} ON ${quoteIdent2(tableName)} (${columnList})`;
+    await this.#pool.execute(sql, []);
+    return indexName;
+  }
+  async #checkMissingConstraints(table) {
+    const existingConstraints = await this.#getConstraints(table.name);
+    const meta = getTableMeta(table);
+    for (const fieldName of Object.keys(meta.fields)) {
+      const fieldMeta = meta.fields[fieldName];
+      if (fieldMeta.unique) {
+        const hasConstraint = existingConstraints.some(
+          (c) => c.type === "unique" && c.columns.length === 1 && c.columns[0] === fieldName
+        );
+        if (!hasConstraint) {
+          throw new SchemaDriftError(
+            `Table "${table.name}" is missing UNIQUE constraint on column "${fieldName}"`,
+            {
+              table: table.name,
+              drift: `missing unique:${fieldName}`,
+              suggestion: `Run ensureConstraints() to apply constraints`
+            }
+          );
+        }
+      }
+    }
+    for (const ref of meta.references) {
+      const hasFK = existingConstraints.some(
+        (c) => c.type === "foreign_key" && c.columns.length === 1 && c.columns[0] === ref.fieldName && c.referencedTable === ref.table.name && c.referencedColumns?.[0] === ref.referencedField
+      );
+      if (!hasFK) {
+        throw new SchemaDriftError(
+          `Table "${table.name}" is missing FOREIGN KEY constraint on column "${ref.fieldName}"`,
+          {
+            table: table.name,
+            drift: `missing foreign_key:${ref.fieldName}->${ref.table.name}.${ref.referencedField}`,
+            suggestion: `Run ensureConstraints() to apply constraints`
+          }
+        );
+      }
+    }
+  }
+  async #ensureUniqueConstraints(table, existingConstraints) {
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const fieldName of Object.keys(meta.fields)) {
+      const fieldMeta = meta.fields[fieldName];
+      if (fieldMeta.unique) {
+        const hasConstraint = existingConstraints.some(
+          (c) => c.type === "unique" && c.columns.length === 1 && c.columns[0] === fieldName
+        );
+        if (!hasConstraint) {
+          await this.#preflightUnique(table.name, [fieldName]);
+          await this.#createIndex(table.name, [fieldName], true);
+          applied = true;
+        }
+      }
+    }
+    return applied;
+  }
+  async #ensureForeignKeys(table, existingConstraints) {
+    const meta = getTableMeta(table);
+    let applied = false;
+    for (const ref of meta.references) {
+      const hasFK = existingConstraints.some(
+        (c) => c.type === "foreign_key" && c.columns.length === 1 && c.columns[0] === ref.fieldName && c.referencedTable === ref.table.name && c.referencedColumns?.[0] === ref.referencedField
+      );
+      if (!hasFK) {
+        await this.#preflightForeignKey(
+          table.name,
+          ref.fieldName,
+          ref.table.name,
+          ref.referencedField
+        );
+        const constraintName = `fk_${table.name}_${ref.fieldName}`;
+        const onDelete = ref.onDelete ? ` ON DELETE ${ref.onDelete.toUpperCase()}` : "";
+        await this.#pool.execute(
+          `ALTER TABLE ${quoteIdent2(table.name)} ADD CONSTRAINT ${quoteIdent2(constraintName)} FOREIGN KEY (${quoteIdent2(ref.fieldName)}) REFERENCES ${quoteIdent2(ref.table.name)} (${quoteIdent2(ref.referencedField)})${onDelete}`,
+          []
+        );
+        applied = true;
+      }
+    }
+    return applied;
+  }
+  async #preflightUnique(tableName, columns) {
+    const columnList = columns.map(quoteIdent2).join(", ");
+    const [rows] = await this.#pool.execute(
+      `SELECT COUNT(*) as count FROM ${quoteIdent2(tableName)} GROUP BY ${columnList} HAVING COUNT(*) > 1`,
+      []
+    );
+    const violationCount = rows.length;
+    if (violationCount > 0) {
+      const diagQuery = `SELECT ${columnList}, COUNT(*) FROM ${quoteIdent2(tableName)} GROUP BY ${columnList} HAVING COUNT(*) > 1`;
+      throw new ConstraintPreflightError(
+        `Cannot add UNIQUE constraint on "${tableName}"(${columns.join(", ")}): duplicate values exist`,
+        {
+          table: tableName,
+          constraint: `unique:${columns.join(",")}`,
+          violationCount,
+          query: diagQuery
+        }
+      );
+    }
+  }
+  async #preflightForeignKey(tableName, column, refTable, refColumn) {
+    const [rows] = await this.#pool.execute(
+      `SELECT COUNT(*) as count FROM ${quoteIdent2(tableName)} t WHERE t.${quoteIdent2(column)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${quoteIdent2(refTable)} r WHERE r.${quoteIdent2(refColumn)} = t.${quoteIdent2(column)})`,
+      []
+    );
+    const violationCount = parseInt(String(rows[0]?.count ?? "0"), 10);
+    if (violationCount > 0) {
+      const diagQuery = `SELECT t.${quoteIdent2(column)} FROM ${quoteIdent2(tableName)} t WHERE t.${quoteIdent2(column)} IS NOT NULL AND NOT EXISTS (SELECT 1 FROM ${quoteIdent2(refTable)} r WHERE r.${quoteIdent2(refColumn)} = t.${quoteIdent2(column)})`;
+      throw new ConstraintPreflightError(
+        `Cannot add FOREIGN KEY constraint on "${tableName}"(${column}): ${violationCount} orphaned rows exist`,
+        {
+          table: tableName,
+          constraint: `foreign_key:${column}->${refTable}.${refColumn}`,
+          violationCount,
+          query: diagQuery
+        }
+      );
+    }
+  }
+};
+export {
+  MySQLDriver as default
+};

package/src/postgres.d.ts

@@ -0,0 +1,62 @@
+/**
+ * postgres.js adapter for @b9g/zen
+ *
+ * Provides a Driver implementation for postgres.js.
+ * Uses connection pooling - call close() when done to end all connections.
+ *
+ * Requires: postgres
+ */
+import type { Driver, Table, EnsureResult } from "./zen.js";
+/**
+ * Options for the postgres adapter.
+ */
+export interface PostgresOptions {
+    /** Maximum number of connections in the pool (default: 10) */
+    max?: number;
+    /** Idle timeout in seconds before closing connections (default: 30) */
+    idleTimeout?: number;
+    /** Connection timeout in seconds (default: 30) */
+    connectTimeout?: number;
+}
+/**
+ * PostgreSQL driver using postgres.js.
+ *
+ * @example
+ * import PostgresDriver from "@b9g/zen/postgres";
+ * import {Database} from "@b9g/zen";
+ *
+ * const driver = new PostgresDriver("postgresql://localhost/mydb");
+ * const db = new Database(driver);
+ *
+ * db.addEventListener("upgradeneeded", (e) => {
+ *   e.waitUntil(runMigrations(e));
+ * });
+ *
+ * await db.open(1);
+ *
+ * // When done:
+ * await driver.close();
+ */
+export default class PostgresDriver implements Driver {
+    #private;
+    readonly supportsReturning = true;
+    constructor(url: string, options?: PostgresOptions);
+    all<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T[]>;
+    get<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    run(strings: TemplateStringsArray, values: unknown[]): Promise<number>;
+    val<T>(strings: TemplateStringsArray, values: unknown[]): Promise<T | null>;
+    close(): Promise<void>;
+    transaction<T>(fn: (txDriver: Driver) => Promise<T>): Promise<T>;
+    withMigrationLock<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Ensure table exists with the specified structure.
+     * Creates table if missing, adds missing columns/indexes.
+     * Throws SchemaDriftError if constraints are missing.
+     */
+    ensureTable<T extends Table<any>>(table: T): Promise<EnsureResult>;
+    /**
+     * Ensure constraints exist on the table.
+     * Applies unique and foreign key constraints with preflight checks.
+     */
+    ensureConstraints<T extends Table<any>>(table: T): Promise<EnsureResult>;
+}