@vertz/db 0.2.12 → 0.2.14

package/dist/shared/chunk-1x9z0p5e.js

@@ -0,0 +1,977 @@
+import {
+  camelToSnake,
+  defaultPostgresDialect,
+  defaultSqliteDialect,
+  snakeToCamel
+} from "./chunk-8v70x3hq.js";
+import {
+  sha256Hex
+} from "./chunk-ssga2xea.js";
+import {
+  __require
+} from "./chunk-j4kwq1gh.js";
+
+// src/migration/runner.ts
+import {
+  createMigrationQueryError,
+  err,
+  ok
+} from "@vertz/errors";
+var HISTORY_TABLE = "_vertz_migrations";
+function buildCreateHistorySql(dialect) {
+  if (dialect.name === "sqlite") {
+    return `
+CREATE TABLE IF NOT EXISTS "${HISTORY_TABLE}" (
+  "id" INTEGER PRIMARY KEY AUTOINCREMENT,
+  "name" TEXT NOT NULL UNIQUE,
+  "checksum" TEXT NOT NULL,
+  "applied_at" TEXT NOT NULL DEFAULT (datetime('now'))
+);
+`;
+  }
+  return `
+CREATE TABLE IF NOT EXISTS "${HISTORY_TABLE}" (
+  "id" serial PRIMARY KEY,
+  "name" text NOT NULL UNIQUE,
+  "checksum" text NOT NULL,
+  "applied_at" timestamp with time zone NOT NULL DEFAULT now()
+);
+`;
+}
+async function computeChecksum(sql) {
+  return sha256Hex(sql);
+}
+function parseMigrationName(filename) {
+  const match = filename.match(/^(\d+)_(.+)\.sql$/);
+  if (!match?.[1] || !match[2])
+    return null;
+  return {
+    timestamp: Number.parseInt(match[1], 10),
+    name: filename
+  };
+}
+function createMigrationRunner(options) {
+  const dialect = options?.dialect ?? defaultPostgresDialect;
+  const createHistorySql = buildCreateHistorySql(dialect);
+  return {
+    async createHistoryTable(queryFn) {
+      try {
+        await queryFn(createHistorySql, []);
+        return ok(undefined);
+      } catch (cause) {
+        return err(createMigrationQueryError("Failed to create migration history table", {
+          sql: createHistorySql,
+          cause
+        }));
+      }
+    },
+    async apply(queryFn, sql, name, options2) {
+      const checksum = await computeChecksum(sql);
+      const recordSql = `INSERT INTO "${HISTORY_TABLE}" ("name", "checksum") VALUES (${dialect.param(1)}, ${dialect.param(2)})`;
+      const statements = [sql, recordSql];
+      if (options2?.dryRun) {
+        return ok({
+          name,
+          sql,
+          checksum,
+          dryRun: true,
+          statements
+        });
+      }
+      try {
+        await queryFn(sql, []);
+        await queryFn(recordSql, [name, checksum]);
+        return ok({
+          name,
+          sql,
+          checksum,
+          dryRun: false,
+          statements
+        });
+      } catch (cause) {
+        return err(createMigrationQueryError(`Failed to apply migration: ${name}`, {
+          sql,
+          cause
+        }));
+      }
+    },
+    async getApplied(queryFn) {
+      try {
+        const result = await queryFn(`SELECT "name", "checksum", "applied_at" FROM "${HISTORY_TABLE}" ORDER BY "id" ASC`, []);
+        return ok(result.rows.map((row) => ({
+          name: row.name,
+          checksum: row.checksum,
+          appliedAt: new Date(row.applied_at)
+        })));
+      } catch (cause) {
+        return err(createMigrationQueryError("Failed to retrieve applied migrations", {
+          cause
+        }));
+      }
+    },
+    getPending(files, applied) {
+      const appliedNames = new Set(applied.map((a) => a.name));
+      return files.filter((f) => !appliedNames.has(f.name)).sort((a, b) => a.timestamp - b.timestamp);
+    },
+    async detectDrift(files, applied) {
+      const drifted = [];
+      const appliedMap = new Map(applied.map((a) => [a.name, a.checksum]));
+      for (const file of files) {
+        const appliedChecksum = appliedMap.get(file.name);
+        if (appliedChecksum && appliedChecksum !== await computeChecksum(file.sql)) {
+          drifted.push(file.name);
+        }
+      }
+      return drifted;
+    },
+    detectOutOfOrder(files, applied) {
+      if (applied.length === 0)
+        return [];
+      const appliedNames = new Set(applied.map((a) => a.name));
+      const lastApplied = applied[applied.length - 1];
+      if (!lastApplied)
+        return [];
+      const lastAppliedFile = files.find((f) => f.name === lastApplied.name);
+      if (!lastAppliedFile)
+        return [];
+      return files.filter((f) => !appliedNames.has(f.name) && f.timestamp < lastAppliedFile.timestamp).map((f) => f.name);
+    }
+  };
+}
+
+// src/migration/validate-indexes.ts
+var POSTGRES_ONLY_INDEX_TYPES = new Set(["hash", "gin", "gist", "brin"]);
+function validateIndexes(tables, dialect) {
+  const warnings = [];
+  for (const [tableName, table] of Object.entries(tables)) {
+    for (const idx of table.indexes) {
+      if (idx.type && dialect === "sqlite" && POSTGRES_ONLY_INDEX_TYPES.has(idx.type)) {
+        warnings.push(`Index on "${tableName}" (${idx.columns.join(", ")}) uses type "${idx.type}" which is not supported on ${dialect}. The index type will be ignored.`);
+      }
+    }
+  }
+  return warnings;
+}
+
+// src/migration/auto-migrate.ts
+import { isErr } from "@vertz/errors";
+
+// src/migration/differ.ts
+function columnSimilarity(a, b) {
+  let score = 0;
+  let total = 0;
+  total += 3;
+  if (a.type === b.type)
+    score += 3;
+  total += 1;
+  if (a.nullable === b.nullable)
+    score += 1;
+  total += 1;
+  if (a.primary === b.primary)
+    score += 1;
+  total += 1;
+  if (a.unique === b.unique)
+    score += 1;
+  return score / total;
+}
+function indexKey(idx) {
+  return JSON.stringify([idx.columns, idx.type ?? null, idx.where ?? null, idx.unique ?? false]);
+}
+function computeDiff(before, after) {
+  const changes = [];
+  for (const tableName of Object.keys(after.tables)) {
+    if (!(tableName in before.tables)) {
+      changes.push({ type: "table_added", table: tableName });
+    }
+  }
+  for (const tableName of Object.keys(before.tables)) {
+    if (!(tableName in after.tables)) {
+      changes.push({ type: "table_removed", table: tableName });
+    }
+  }
+  for (const tableName of Object.keys(after.tables)) {
+    if (!(tableName in before.tables))
+      continue;
+    const beforeTable = before.tables[tableName];
+    const afterTable = after.tables[tableName];
+    if (!beforeTable || !afterTable)
+      continue;
+    const removedCols = Object.keys(beforeTable.columns).filter((c) => !(c in afterTable.columns));
+    const addedCols = Object.keys(afterTable.columns).filter((c) => !(c in beforeTable.columns));
+    const renames = [];
+    const matchedRemoved = new Set;
+    const matchedAdded = new Set;
+    for (const removed of removedCols) {
+      const removedSnap = beforeTable.columns[removed];
+      if (!removedSnap)
+        continue;
+      let bestMatch = null;
+      let bestScore = 0;
+      for (const added of addedCols) {
+        if (matchedAdded.has(added))
+          continue;
+        const addedSnap = afterTable.columns[added];
+        if (!addedSnap)
+          continue;
+        const score = columnSimilarity(removedSnap, addedSnap);
+        if (score > bestScore) {
+          bestScore = score;
+          bestMatch = added;
+        }
+      }
+      if (bestMatch && bestScore >= 0.7) {
+        renames.push({ oldCol: removed, newCol: bestMatch, confidence: bestScore });
+        matchedRemoved.add(removed);
+        matchedAdded.add(bestMatch);
+      }
+    }
+    for (const rename of renames) {
+      changes.push({
+        type: "column_renamed",
+        table: tableName,
+        oldColumn: rename.oldCol,
+        newColumn: rename.newCol,
+        confidence: rename.confidence
+      });
+    }
+    for (const colName of addedCols) {
+      if (!matchedAdded.has(colName)) {
+        changes.push({ type: "column_added", table: tableName, column: colName });
+      }
+    }
+    for (const colName of removedCols) {
+      if (!matchedRemoved.has(colName)) {
+        changes.push({ type: "column_removed", table: tableName, column: colName });
+      }
+    }
+    for (const colName of Object.keys(afterTable.columns)) {
+      if (!(colName in beforeTable.columns))
+        continue;
+      const beforeCol = beforeTable.columns[colName];
+      const afterCol = afterTable.columns[colName];
+      if (!beforeCol || !afterCol)
+        continue;
+      if (beforeCol.type !== afterCol.type || beforeCol.nullable !== afterCol.nullable || beforeCol.default !== afterCol.default) {
+        const change = {
+          type: "column_altered",
+          table: tableName,
+          column: colName
+        };
+        if (beforeCol.type !== afterCol.type) {
+          change.oldType = beforeCol.type;
+          change.newType = afterCol.type;
+        }
+        if (beforeCol.nullable !== afterCol.nullable) {
+          change.oldNullable = beforeCol.nullable;
+          change.newNullable = afterCol.nullable;
+        }
+        if (beforeCol.default !== afterCol.default) {
+          change.oldDefault = beforeCol.default;
+          change.newDefault = afterCol.default;
+        }
+        changes.push(change);
+      }
+    }
+    const beforeIndexKeys = new Set(beforeTable.indexes.map((i) => indexKey(i)));
+    const afterIndexKeys = new Set(afterTable.indexes.map((i) => indexKey(i)));
+    for (const idx of afterTable.indexes) {
+      const key = indexKey(idx);
+      if (!beforeIndexKeys.has(key)) {
+        const change = {
+          type: "index_added",
+          table: tableName,
+          columns: [...idx.columns]
+        };
+        if (idx.name)
+          change.indexName = idx.name;
+        if (idx.type)
+          change.indexType = idx.type;
+        if (idx.where)
+          change.indexWhere = idx.where;
+        if (idx.unique)
+          change.indexUnique = idx.unique;
+        changes.push(change);
+      }
+    }
+    for (const idx of beforeTable.indexes) {
+      const key = indexKey(idx);
+      if (!afterIndexKeys.has(key)) {
+        const change = {
+          type: "index_removed",
+          table: tableName,
+          columns: [...idx.columns]
+        };
+        if (idx.name)
+          change.indexName = idx.name;
+        if (idx.type)
+          change.indexType = idx.type;
+        if (idx.where)
+          change.indexWhere = idx.where;
+        if (idx.unique)
+          change.indexUnique = idx.unique;
+        changes.push(change);
+      }
+    }
+  }
+  for (const enumName of Object.keys(after.enums)) {
+    if (!(enumName in before.enums)) {
+      changes.push({ type: "enum_added", enumName });
+    }
+  }
+  for (const enumName of Object.keys(before.enums)) {
+    if (!(enumName in after.enums)) {
+      changes.push({ type: "enum_removed", enumName });
+    }
+  }
+  for (const enumName of Object.keys(after.enums)) {
+    if (!(enumName in before.enums))
+      continue;
+    const beforeVals = before.enums[enumName];
+    const afterVals = after.enums[enumName];
+    if (!beforeVals || !afterVals)
+      continue;
+    const beforeSet = new Set(beforeVals);
+    const afterSet = new Set(afterVals);
+    const addedValues = afterVals.filter((v) => !beforeSet.has(v));
+    const removedValues = beforeVals.filter((v) => !afterSet.has(v));
+    if (addedValues.length > 0 || removedValues.length > 0) {
+      changes.push({ type: "enum_altered", enumName, addedValues, removedValues });
+    }
+  }
+  return { changes };
+}
+
+// src/migration/sql-generator.ts
+function escapeSqlString(value) {
+  return value.replace(/'/g, "''");
+}
+function isEnumType(col, enums) {
+  const typeLower = col.type.toLowerCase();
+  if (enums) {
+    for (const enumName of Object.keys(enums)) {
+      if (typeLower === enumName.toLowerCase() || typeLower === enumName) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function getEnumValues(col, enums) {
+  if (!enums)
+    return;
+  for (const [enumName, values] of Object.entries(enums)) {
+    if (col.type.toLowerCase() === enumName.toLowerCase() || col.type === enumName) {
+      return values;
+    }
+  }
+  return;
+}
+function columnDef(name, col, dialect, enums) {
+  const snakeName = camelToSnake(name);
+  const isEnum = isEnumType(col, enums);
+  let sqlType;
+  let checkConstraint;
+  if (isEnum && dialect.name === "sqlite") {
+    sqlType = dialect.mapColumnType("text");
+    const enumValues = getEnumValues(col, enums);
+    if (enumValues && enumValues.length > 0) {
+      const escapedValues = enumValues.map((v) => `'${escapeSqlString(v)}'`).join(", ");
+      checkConstraint = `CHECK("${snakeName}" IN (${escapedValues}))`;
+    }
+  } else {
+    if (dialect.name === "postgres" && col.type === col.type.toLowerCase()) {
+      sqlType = col.type;
+    } else {
+      const normalizedType = normalizeColumnType(col.type);
+      sqlType = dialect.mapColumnType(normalizedType);
+    }
+  }
+  const parts = [`"${snakeName}" ${sqlType}`];
+  if (checkConstraint) {
+    parts.push(checkConstraint);
+  }
+  if (!col.nullable) {
+    parts.push("NOT NULL");
+  }
+  if (col.unique) {
+    parts.push("UNIQUE");
+  }
+  if (col.default !== undefined) {
+    parts.push(`DEFAULT ${col.default}`);
+  }
+  return parts.join(" ");
+}
+function normalizeColumnType(type) {
+  const typeUpper = type.toUpperCase();
+  const typeMap = {
+    UUID: "uuid",
+    TEXT: "text",
+    INTEGER: "integer",
+    SERIAL: "serial",
+    BOOLEAN: "boolean",
+    TIMESTAMPTZ: "timestamp",
+    TIMESTAMP: "timestamp",
+    "DOUBLE PRECISION": "float",
+    JSONB: "json",
+    JSON: "json",
+    NUMERIC: "decimal",
+    REAL: "float",
+    VARCHAR: "varchar"
+  };
+  return typeMap[typeUpper] || type.toLowerCase();
+}
+function generateMigrationSql(changes, ctx, dialect = defaultPostgresDialect) {
+  const statements = [];
+  const tables = ctx?.tables;
+  const enums = ctx?.enums;
+  if (tables) {
+    const warnings = validateIndexes(tables, dialect.name);
+    for (const warning of warnings) {
+      console.warn(warning);
+    }
+  }
+  for (const change of changes) {
+    switch (change.type) {
+      case "enum_added": {
+        if (!change.enumName)
+          break;
+        if (dialect.name === "postgres") {
+          const values = enums?.[change.enumName];
+          if (!values || values.length === 0)
+            break;
+          const enumSnakeName = camelToSnake(change.enumName);
+          const valuesStr = values.map((v) => `'${escapeSqlString(v)}'`).join(", ");
+          statements.push(`CREATE TYPE "${enumSnakeName}" AS ENUM (${valuesStr});`);
+        }
+        break;
+      }
+      case "table_added": {
+        if (!change.table)
+          break;
+        const table = tables?.[change.table];
+        if (!table)
+          break;
+        const tableName = camelToSnake(change.table);
+        const cols = [];
+        const primaryKeys = [];
+        if (dialect.name === "postgres" && enums) {
+          for (const [, col] of Object.entries(table.columns)) {
+            if (isEnumType(col, enums)) {
+              const enumValues = getEnumValues(col, enums);
+              if (enumValues && enumValues.length > 0) {
+                const enumSnakeName = camelToSnake(col.type);
+                const alreadyEmitted = statements.some((s) => s.includes(`CREATE TYPE "${enumSnakeName}"`));
+                if (!alreadyEmitted) {
+                  const valuesStr = enumValues.map((v) => `'${escapeSqlString(v)}'`).join(", ");
+                  statements.push(`CREATE TYPE "${enumSnakeName}" AS ENUM (${valuesStr});`);
+                }
+              }
+            }
+          }
+        }
+        for (const [colName, col] of Object.entries(table.columns)) {
+          cols.push(`  ${columnDef(colName, col, dialect, enums)}`);
+          if (col.primary) {
+            primaryKeys.push(`"${camelToSnake(colName)}"`);
+          }
+        }
+        if (primaryKeys.length > 0) {
+          cols.push(`  PRIMARY KEY (${primaryKeys.join(", ")})`);
+        }
+        for (const fk of table.foreignKeys) {
+          const fkCol = camelToSnake(fk.column);
+          const fkTarget = camelToSnake(fk.targetTable);
+          const fkTargetCol = camelToSnake(fk.targetColumn);
+          cols.push(`  FOREIGN KEY ("${fkCol}") REFERENCES "${fkTarget}" ("${fkTargetCol}")`);
+        }
+        statements.push(`CREATE TABLE "${tableName}" (
+${cols.join(`,
+`)}
+);`);
+        for (const idx of table.indexes) {
+          const idxCols = idx.columns.map((c) => `"${camelToSnake(c)}"`).join(", ");
+          const idxName = idx.name ?? `idx_${tableName}_${idx.columns.map((c) => camelToSnake(c)).join("_")}`;
+          const unique = idx.unique ? "UNIQUE " : "";
+          const using = idx.type && dialect.name === "postgres" ? ` USING ${idx.type}` : "";
+          const where = idx.where ? ` WHERE ${idx.where}` : "";
+          statements.push(`CREATE ${unique}INDEX "${idxName}" ON "${tableName}"${using} (${idxCols})${where};`);
+        }
+        break;
+      }
+      case "table_removed": {
+        if (!change.table)
+          break;
+        statements.push(`DROP TABLE "${camelToSnake(change.table)}";`);
+        break;
+      }
+      case "column_added": {
+        if (!change.table || !change.column)
+          break;
+        const col = tables?.[change.table]?.columns[change.column];
+        if (!col)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" ADD COLUMN ${columnDef(change.column, col, dialect, enums)};`);
+        break;
+      }
+      case "column_removed": {
+        if (!change.table || !change.column)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" DROP COLUMN "${camelToSnake(change.column)}";`);
+        break;
+      }
+      case "column_altered": {
+        if (!change.table || !change.column)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const snakeCol = camelToSnake(change.column);
+        if (change.newType !== undefined) {
+          statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" TYPE ${change.newType};`);
+        }
+        if (change.newNullable !== undefined) {
+          if (change.newNullable) {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" DROP NOT NULL;`);
+          } else {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" SET NOT NULL;`);
+          }
+        }
+        if (change.newDefault !== undefined) {
+          if (change.newDefault) {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" SET DEFAULT ${change.newDefault};`);
+          } else {
+            statements.push(`ALTER TABLE "${snakeTable}" ALTER COLUMN "${snakeCol}" DROP DEFAULT;`);
+          }
+        }
+        break;
+      }
+      case "column_renamed": {
+        if (!change.table || !change.oldColumn || !change.newColumn)
+          break;
+        statements.push(`ALTER TABLE "${camelToSnake(change.table)}" RENAME COLUMN "${camelToSnake(change.oldColumn)}" TO "${camelToSnake(change.newColumn)}";`);
+        break;
+      }
+      case "index_added": {
+        if (!change.table || !change.columns)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const idxCols = change.columns.map((c) => `"${camelToSnake(c)}"`).join(", ");
+        const idxName = change.indexName ?? `idx_${snakeTable}_${change.columns.map((c) => camelToSnake(c)).join("_")}`;
+        const unique = change.indexUnique ? "UNIQUE " : "";
+        const using = change.indexType && dialect.name === "postgres" ? ` USING ${change.indexType}` : "";
+        const where = change.indexWhere ? ` WHERE ${change.indexWhere}` : "";
+        statements.push(`CREATE ${unique}INDEX "${idxName}" ON "${snakeTable}"${using} (${idxCols})${where};`);
+        break;
+      }
+      case "index_removed": {
+        if (!change.table || !change.columns)
+          break;
+        const snakeTable = camelToSnake(change.table);
+        const idxName = change.indexName ?? `idx_${snakeTable}_${change.columns.map((c) => camelToSnake(c)).join("_")}`;
+        statements.push(`DROP INDEX "${idxName}";`);
+        break;
+      }
+      case "enum_removed": {
+        if (!change.enumName)
+          break;
+        if (dialect.name === "postgres") {
+          statements.push(`DROP TYPE "${camelToSnake(change.enumName)}";`);
+        }
+        break;
+      }
+      case "enum_altered": {
+        if (!change.enumName || !change.addedValues)
+          break;
+        if (dialect.name === "postgres") {
+          const enumSnakeName = camelToSnake(change.enumName);
+          for (const val of change.addedValues) {
+            statements.push(`ALTER TYPE "${enumSnakeName}" ADD VALUE '${escapeSqlString(val)}';`);
+          }
+        }
+        break;
+      }
+    }
+  }
+  return statements.join(`
+
+`);
+}
+
+// src/migration/auto-migrate.ts
+var DESTRUCTIVE_CHANGE_TYPES = ["table_removed", "column_removed"];
+function isDestructiveChange(change) {
+  return DESTRUCTIVE_CHANGE_TYPES.includes(change.type);
+}
+async function autoMigrate(options) {
+  const { currentSchema, snapshotPath, db } = options;
+  let storage;
+  if (options.storage) {
+    storage = options.storage;
+  } else {
+    const { NodeSnapshotStorage } = await import("./chunk-dvwe5jsq.js");
+    storage = new NodeSnapshotStorage;
+  }
+  const previousSnapshot = await storage.load(snapshotPath);
+  const dialectObj = defaultSqliteDialect;
+  const runner = createMigrationRunner();
+  await runner.createHistoryTable(db);
+  if (!previousSnapshot) {
+    console.log("[auto-migrate] No previous snapshot found. Applying full schema...");
+    const diff = computeDiff({ version: 1, tables: {}, enums: {} }, currentSchema);
+    if (diff.changes.length > 0) {
+      for (const change of diff.changes) {
+        if (isDestructiveChange(change)) {
+          console.warn(`[auto-migrate] Warning: Destructive change detected on first run: ${change.type}`);
+        }
+      }
+      const sql = generateMigrationSql(diff.changes, {
+        tables: currentSchema.tables,
+        enums: currentSchema.enums
+      }, dialectObj);
+      if (sql.trim()) {
+        const result = await runner.apply(db, sql, "auto-migrate-initial");
+        if (isErr(result)) {
+          const error = result.error;
+          const errorMessage = typeof error === "object" && error !== null && "message" in error ? error.message : String(error);
+          const cause = typeof error === "object" && error !== null && "cause" in error ? error.cause : undefined;
+          const causeStr = cause ? ` (cause: ${String(cause)})` : "";
+          throw new Error(`Failed to apply initial schema: ${errorMessage}${causeStr}`);
+        }
+        console.log("[auto-migrate] Initial schema applied successfully.");
+      }
+    } else {
+      console.log("[auto-migrate] No schema changes to apply.");
+    }
+  } else {
+    console.log("[auto-migrate] Previous snapshot found. Computing diff...");
+    const diff = computeDiff(previousSnapshot, currentSchema);
+    if (diff.changes.length === 0) {
+      console.log("[auto-migrate] No schema changes detected.");
+    } else {
+      const destructiveChanges = diff.changes.filter(isDestructiveChange);
+      for (const change of destructiveChanges) {
+        let details = "";
+        if (change.type === "table_removed" && change.table) {
+          details = ` (table: ${change.table})`;
+        } else if (change.type === "column_removed" && change.table && change.column) {
+          details = ` (table: ${change.table}, column: ${change.column})`;
+        }
+        console.warn(`[auto-migrate] ⚠️  Warning: Destructive change detected${details}: ${change.type}`);
+      }
+      const sql = generateMigrationSql(diff.changes, {
+        tables: currentSchema.tables,
+        enums: currentSchema.enums
+      }, dialectObj);
+      if (sql.trim()) {
+        const result = await runner.apply(db, sql, `auto-migrate-${Date.now()}`);
+        if (isErr(result)) {
+          const error = result.error;
+          const errorMessage = typeof error === "object" && error !== null && "message" in error ? error.message : String(error);
+          const cause = typeof error === "object" && error !== null && "cause" in error ? error.cause : undefined;
+          const causeStr = cause ? ` (cause: ${String(cause)})` : "";
+          throw new Error(`Failed to apply migration: ${errorMessage}${causeStr}`);
+        }
+        console.log(`[auto-migrate] Applied ${diff.changes.length} change(s).`);
+      }
+    }
+  }
+  await storage.save(snapshotPath, currentSchema);
+  console.log("[auto-migrate] Snapshot saved.");
+}
+
+// src/errors/db-error.ts
+class DbError extends Error {
+  pgCode;
+  table;
+  query;
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+  toJSON() {
+    const json = {
+      error: this.name,
+      code: this.code,
+      message: this.message
+    };
+    if (this.table !== undefined) {
+      json.table = this.table;
+    }
+    return json;
+  }
+}
+
+class UniqueConstraintError extends DbError {
+  code = "UNIQUE_VIOLATION";
+  pgCode = "23505";
+  table;
+  query;
+  column;
+  value;
+  constructor(options) {
+    super(`Unique constraint violated on ${options.table}.${options.column}${options.value !== undefined ? ` (value: ${options.value})` : ""}`);
+    this.table = options.table;
+    this.column = options.column;
+    this.value = options.value;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table,
+      column: this.column
+    };
+  }
+}
+
+class ForeignKeyError extends DbError {
+  code = "FOREIGN_KEY_VIOLATION";
+  pgCode = "23503";
+  table;
+  query;
+  constraint;
+  detail;
+  constructor(options) {
+    super(`Foreign key constraint "${options.constraint}" violated on table ${options.table}`);
+    this.table = options.table;
+    this.constraint = options.constraint;
+    this.detail = options.detail;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class NotNullError extends DbError {
+  code = "NOT_NULL_VIOLATION";
+  pgCode = "23502";
+  table;
+  query;
+  column;
+  constructor(options) {
+    super(`Not-null constraint violated on ${options.table}.${options.column}`);
+    this.table = options.table;
+    this.column = options.column;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table,
+      column: this.column
+    };
+  }
+}
+
+class CheckConstraintError extends DbError {
+  code = "CHECK_VIOLATION";
+  pgCode = "23514";
+  table;
+  query;
+  constraint;
+  constructor(options) {
+    super(`Check constraint "${options.constraint}" violated on table ${options.table}`);
+    this.table = options.table;
+    this.constraint = options.constraint;
+    this.query = options.query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class NotFoundError extends DbError {
+  code = "NotFound";
+  table;
+  query;
+  constructor(table, query) {
+    super(`Record not found in table ${table}`);
+    this.table = table;
+    this.query = query;
+  }
+  toJSON() {
+    return {
+      ...super.toJSON(),
+      table: this.table
+    };
+  }
+}
+
+class ConnectionError extends DbError {
+  code = "CONNECTION_ERROR";
+  constructor(message) {
+    super(`Database connection error: ${message}`);
+  }
+}
+
+class ConnectionPoolExhaustedError extends ConnectionError {
+  code = "POOL_EXHAUSTED";
+  constructor(poolSize) {
+    super(`Connection pool exhausted (max: ${poolSize})`);
+    this.name = "ConnectionPoolExhaustedError";
+  }
+}
+
+// src/errors/pg-parser.ts
+function extractKeyDetail(detail) {
+  if (!detail)
+    return null;
+  const match = detail.match(/^Key \(([^)]+)\)=\(([^)]*)\)/);
+  if (!match)
+    return null;
+  return { column: match[1], value: match[2] };
+}
+function extractNotNullColumn(message) {
+  const match = message.match(/null value in column "([^"]+)"/);
+  return match ? match[1] : null;
+}
+function extractCheckConstraint(message) {
+  const match = message.match(/violates check constraint "([^"]+)"/);
+  return match ? match[1] : null;
+}
+function isConnectionErrorCode(code) {
+  return code.startsWith("08");
+}
+
+class UnknownDbError extends DbError {
+  code;
+  table;
+  query;
+  constructor(code, message, table, query) {
+    super(message);
+    this.code = code;
+    this.table = table;
+    this.query = query;
+  }
+}
+function parsePgError(pgError, query) {
+  const { code, message, table, column, constraint, detail } = pgError;
+  switch (code) {
+    case "23505": {
+      const keyDetail = extractKeyDetail(detail);
+      return new UniqueConstraintError({
+        table: table ?? "unknown",
+        column: column ?? keyDetail?.column ?? "unknown",
+        value: keyDetail?.value,
+        query
+      });
+    }
+    case "23503": {
+      return new ForeignKeyError({
+        table: table ?? "unknown",
+        constraint: constraint ?? "unknown",
+        detail,
+        query
+      });
+    }
+    case "23502": {
+      const extractedColumn = extractNotNullColumn(message);
+      return new NotNullError({
+        table: table ?? "unknown",
+        column: column ?? extractedColumn ?? "unknown",
+        query
+      });
+    }
+    case "23514": {
+      const extractedConstraint = extractCheckConstraint(message);
+      return new CheckConstraintError({
+        table: table ?? "unknown",
+        constraint: constraint ?? extractedConstraint ?? "unknown",
+        query
+      });
+    }
+    default: {
+      if (isConnectionErrorCode(code)) {
+        return new ConnectionError(message);
+      }
+      return new UnknownDbError(code, message, table, query);
+    }
+  }
+}
+
+// src/query/executor.ts
+function isPgError(error) {
+  return typeof error === "object" && error !== null && "code" in error && typeof error.code === "string" && "message" in error && typeof error.message === "string";
+}
+async function executeQuery(queryFn, sql, params) {
+  try {
+    return await queryFn(sql, params);
+  } catch (error) {
+    if (isPgError(error)) {
+      throw parsePgError(error, sql);
+    }
+    throw error;
+  }
+}
+
+// src/query/helpers.ts
+function getColumnNames(table) {
+  return Object.keys(table._columns);
+}
+function getDefaultColumns(table) {
+  return getColumnsWithoutAnnotations(table, []);
+}
+function getColumnsWithoutAnnotations(table, annotations) {
+  const allAnnotations = annotations.includes("hidden") ? annotations : [...annotations, "hidden"];
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    if (!col)
+      return true;
+    const colAnnotations = col._meta._annotations;
+    return !allAnnotations.some((f) => colAnnotations[f]);
+  });
+}
+function resolveSelectColumns(table, select) {
+  if (!select) {
+    return getDefaultColumns(table);
+  }
+  if ("not" in select && select.not !== undefined) {
+    const notValue = select.not;
+    const flags = Array.isArray(notValue) ? notValue : [notValue];
+    return getColumnsWithoutAnnotations(table, flags);
+  }
+  return Object.keys(select).filter((k) => select[k] === true);
+}
+function getTimestampColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.sqlType === "timestamp with time zone" : false;
+  });
+}
+function getPrimaryKeyColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.primary : false;
+  });
+}
+function getReadOnlyColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.isReadOnly : false;
+  });
+}
+function getAutoUpdateColumns(table) {
+  return Object.keys(table._columns).filter((key) => {
+    const col = table._columns[key];
+    return col ? col._meta.isAutoUpdate : false;
+  });
+}
+
+// src/query/row-mapper.ts
+function mapRow(row) {
+  const result = {};
+  for (const key of Object.keys(row)) {
+    result[snakeToCamel(key)] = row[key];
+  }
+  return result;
+}
+function mapRows(rows) {
+  return rows.map((row) => mapRow(row));
+}
+
+export { computeDiff, computeChecksum, parseMigrationName, createMigrationRunner, validateIndexes, generateMigrationSql, autoMigrate, DbError, UniqueConstraintError, ForeignKeyError, NotNullError, CheckConstraintError, NotFoundError, ConnectionError, ConnectionPoolExhaustedError, parsePgError, executeQuery, getColumnNames, getDefaultColumns, getColumnsWithoutAnnotations, resolveSelectColumns, getTimestampColumns, getPrimaryKeyColumns, getReadOnlyColumns, getAutoUpdateColumns, mapRow, mapRows };