@stacksjs/database 0.70.88 → 0.70.90

package/dist/fk-audit.js

@@ -0,0 +1,181 @@
+import { existsSync } from "node:fs";
+import { dirname } from "node:path";
+import { plural, singular, snakeCase } from "@stacksjs/strings";
+import { path } from "@stacksjs/path";
+import { globSync } from "@stacksjs/storage";
+export function safeGlob(pattern) {
+  const metaIdx = pattern.search(/[*?[]/), root = metaIdx === -1 ? dirname(pattern) : dirname(pattern.slice(0, metaIdx));
+  if (!existsSync(root))
+    return [];
+  try {
+    return globSync(pattern, { absolute: !0 });
+  } catch {
+    return [];
+  }
+}
+export async function getDeclaredFKs() {
+  const modelFiles = [
+    ...safeGlob(path.userModelsPath("*.ts")),
+    ...safeGlob(path.storagePath("framework/defaults/app/Models/**/*.ts"))
+  ], declared = [];
+  for (const modelFile of modelFiles) {
+    let model;
+    try {
+      model = (await import(modelFile)).default;
+    } catch {
+      continue;
+    }
+    if (!model || typeof model !== "object")
+      continue;
+    const fromTable = model.table || plural(snakeCase(model.name || "")), belongsTo = model.belongsTo;
+    if (Array.isArray(belongsTo))
+      for (const entry of belongsTo) {
+        const related = typeof entry === "string" ? entry : entry?.model ?? "";
+        if (!related)
+          continue;
+        const fromColumn = `${snakeCase(singular(related))}_id`, toTable = plural(snakeCase(related));
+        declared.push({
+          fromTable,
+          fromColumn,
+          toTable,
+          toColumn: "id",
+          model: model.name || ""
+        });
+      }
+    else if (belongsTo && typeof belongsTo === "object")
+      for (const related of Object.keys(belongsTo)) {
+        const fromColumn = `${snakeCase(singular(related))}_id`, toTable = plural(snakeCase(related));
+        declared.push({
+          fromTable,
+          fromColumn,
+          toTable,
+          toColumn: "id",
+          model: model.name || ""
+        });
+      }
+  }
+  return declared;
+}
+export async function getLiveFKs() {
+  const { db } = await import("./utils"), dialect = await currentDialect();
+  if (dialect === "sqlite")
+    return getSqliteLiveFKs(db);
+  if (dialect === "mysql")
+    return getMysqlLiveFKs(db);
+  if (dialect === "postgres")
+    return getPostgresLiveFKs(db);
+  return [];
+}
+export async function auditForeignKeys() {
+  const declared = await getDeclaredFKs(), live = await getLiveFKs(), liveKeys = new Set(live.map((fk) => `${fk.fromTable.toLowerCase()}.${fk.fromColumn.toLowerCase()}\u2192${fk.toTable.toLowerCase()}.${fk.toColumn.toLowerCase()}`)), missing = declared.filter((d) => {
+    const key = `${d.fromTable.toLowerCase()}.${d.fromColumn.toLowerCase()}\u2192${d.toTable.toLowerCase()}.${d.toColumn.toLowerCase()}`;
+    return !liveKeys.has(key);
+  });
+  return { declared, live, missing };
+}
+export async function findFkOrphans(dialect) {
+  if ((dialect ?? await currentDialect()) !== "sqlite")
+    return { supported: !1, total: 0, orphans: [] };
+  const { db } = await import("./utils"), rows = await db.unsafe("PRAGMA foreign_key_check").execute(), checkRows = Array.isArray(rows) ? rows : [], fkListCache = new Map;
+  async function fkListFor(table) {
+    if (fkListCache.has(table))
+      return fkListCache.get(table);
+    if (!/^[a-z_]\w*$/i.test(table)) {
+      fkListCache.set(table, []);
+      return [];
+    }
+    const list = await db.unsafe(`PRAGMA foreign_key_list("${table}")`).execute(), arr = Array.isArray(list) ? list : [];
+    fkListCache.set(table, arr);
+    return arr;
+  }
+  const grouped = new Map;
+  for (const raw of checkRows) {
+    const r = raw, table = String(r.table ?? ""), parent = String(r.parent ?? "");
+    if (!table || !parent)
+      continue;
+    const fkid = Number(r.fkid ?? 0);
+    let column = "";
+    const fkList = await fkListFor(table);
+    for (const fk of fkList) {
+      const f = fk;
+      if (Number(f.id) === fkid && f.from) {
+        column = String(f.from);
+        break;
+      }
+    }
+    const key = `${table}\x00${parent}\x00${fkid}`;
+    let entry = grouped.get(key);
+    if (!entry) {
+      entry = { table, column, parent, count: 0, sampleRowids: [] };
+      grouped.set(key, entry);
+    }
+    entry.count++;
+    if (entry.sampleRowids.length < 5 && typeof r.rowid === "number")
+      entry.sampleRowids.push(r.rowid);
+  }
+  const orphans = [...grouped.values()];
+  return { supported: !0, total: orphans.reduce((sum, o) => sum + o.count, 0), orphans };
+}
+async function currentDialect() {
+  const driver = ((await import("@stacksjs/env")).env?.DB_CONNECTION ?? "sqlite").toLowerCase();
+  if (driver === "sqlite" || driver === "mysql" || driver === "postgres")
+    return driver;
+  return "other";
+}
+async function getSqliteLiveFKs(db) {
+  const tables = await db.unsafe("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'"), rows = Array.isArray(tables) ? tables : [], fks = [];
+  for (const row of rows) {
+    const fromTable = row.name;
+    if (!fromTable)
+      continue;
+    if (!/^[a-z_][\w]*$/i.test(fromTable))
+      continue;
+    const fkRows = await db.unsafe(`PRAGMA foreign_key_list("${fromTable}")`);
+    for (const fk of Array.isArray(fkRows) ? fkRows : []) {
+      const r = fk;
+      if ((r.seq ?? 0) !== 0)
+        continue;
+      if (!r.from || !r.to || !r.table)
+        continue;
+      fks.push({ fromTable, fromColumn: r.from, toTable: r.table, toColumn: r.to });
+    }
+  }
+  return fks;
+}
+async function getMysqlLiveFKs(db) {
+  const rows = await db.unsafe(`
+    SELECT TABLE_NAME, COLUMN_NAME, REFERENCED_TABLE_NAME, REFERENCED_COLUMN_NAME
+    FROM information_schema.KEY_COLUMN_USAGE
+    WHERE TABLE_SCHEMA = DATABASE()
+      AND REFERENCED_TABLE_NAME IS NOT NULL
+  `);
+  return (Array.isArray(rows) ? rows : []).map((row) => ({
+    fromTable: String(row.TABLE_NAME ?? row.table_name ?? ""),
+    fromColumn: String(row.COLUMN_NAME ?? row.column_name ?? ""),
+    toTable: String(row.REFERENCED_TABLE_NAME ?? row.referenced_table_name ?? ""),
+    toColumn: String(row.REFERENCED_COLUMN_NAME ?? row.referenced_column_name ?? "")
+  })).filter((fk) => fk.fromTable && fk.fromColumn && fk.toTable && fk.toColumn);
+}
+async function getPostgresLiveFKs(db) {
+  const rows = await db.unsafe(`
+    SELECT
+      kcu.table_name AS from_table,
+      kcu.column_name AS from_column,
+      ccu.table_name AS to_table,
+      ccu.column_name AS to_column
+    FROM information_schema.referential_constraints rc
+    JOIN information_schema.key_column_usage kcu
+      ON kcu.constraint_name = rc.constraint_name
+    AND kcu.constraint_schema = rc.constraint_schema
+    JOIN information_schema.constraint_column_usage ccu
+      ON ccu.constraint_name = rc.constraint_name
+    AND ccu.constraint_schema = rc.constraint_schema
+    WHERE rc.constraint_schema = 'public'
+  `);
+  return (Array.isArray(rows) ? rows : []).map((row) => ({
+    fromTable: String(row.from_table ?? ""),
+    fromColumn: String(row.from_column ?? ""),
+    toTable: String(row.to_table ?? ""),
+    toColumn: String(row.to_column ?? "")
+  })).filter((fk) => fk.fromTable && fk.fromColumn && fk.toTable && fk.toColumn);
+}

package/dist/index.d.ts

@@ -0,0 +1,149 @@
+export type {
+  DatabaseConnectionConfig,
+  DatabaseOptions,
+} from './database';
+export type {
+  DatabaseConnections,
+  DynamoDbConfig,
+  FullDatabaseConfig,
+  MysqlConfig,
+  PostgresConfig,
+  SqliteConfig,
+} from './driver-config';
+export type { GenerateOptions } from './factory';
+export type { ScaffoldOptions, ScaffoldResult } from './seed-scaffold';
+export type { DeclaredFK, FkAuditResult, FkOrphan, FkOrphanReport, LiveFK } from './fk-audit';
+export type { DeclaredUnique, LiveUniqueIndex, UniqueAuditResult } from './unique-audit';
+export type {
+  QueryBuilder,
+  QueryBuilderConfig,
+  Seeder as QueryBuilderSeeder,
+  SupportedDialect,
+} from '@stacksjs/query-builder';
+export type {
+  DynamoConnectionConfig,
+  SingleTableEntityMapping,
+  SortKeyBuilder,
+  BatchWriteOperation,
+  TransactWriteOperation,
+  QueryResult,
+} from './drivers/dynamodb';
+/**
+ * @stacksjs/database
+ *
+ * Database module powered by bun-query-builder.
+ * Provides database initialization, driver configuration, migrations,
+ * seeding, and a fluent query builder interface.
+ *
+ * @example
+ * ```ts
+ * import { Database, db, createSqliteDatabase } from '@stacksjs/database'
+ *
+ * // Use the default db instance (configured from environment)
+ * const users = await db.selectFrom('users').where('active', '=', true).get()
+ *
+ * // Or create a custom database instance
+ * const customDb = new Database({
+ *   driver: 'postgres',
+ *   connection: {
+ *     database: 'myapp',
+ *     host: 'localhost',
+ *     port: 5432,
+ *     username: 'postgres',
+ *     password: 'secret'
+ *   }
+ * })
+ *
+ * // Helper functions for quick setup
+ * const sqliteDb = createSqliteDatabase('database/app.sqlite')
+ * ```
+ */
+// Database initialization and management
+export {
+  Database,
+  createDatabase,
+  createMysqlDatabase,
+  createPostgresDatabase,
+  createSqliteDatabase,
+} from './database';
+// Driver configuration
+export {
+  detectDriver,
+  driverDefaults,
+  getConfigFromEnv,
+  getConnectionString,
+  mergeWithDefaults,
+  validateDriverConfig,
+} from './driver-config';
+// Core database utilities and default instance
+export * from './utils';
+// Types (compatibility layer for Kysely types)
+export * from './types';
+// Migrations
+export * from './migrations';
+// Query logger DI hook (router calls setQueryTracker on init)
+export { setQueryTracker, logQuery } from './query-logger';
+// Class-based seeders (supplements the model-attribute auto-seeder)
+export { Seeder, runClassSeeders } from './class-seeder';
+// Zero-downtime migration helpers
+export { addColumnSafely, backfillInBatches, renameColumnSafely } from './safe-migrations';
+// Seeding
+export * from './seeder';
+// stacksjs/stacks#1919 — public factory API. The canonical replacement
+// for the legacy `useSeeder` trait + auto-walker. Class seeders call
+// `factory.generate(Model, opts)` explicitly so there's one
+// orchestration layer per table, no double-fire on tables that have
+// both a `useSeeder` trait and a class seeder file.
+export { factory, generate as factoryGenerate } from './factory';
+// `buddy seed:scaffold` codemod — generates class-seeder files for
+// every model with a `useSeeder` trait, easing the migration off the
+// auto-walker.
+export { scaffoldClassSeedersFromModels, renderSeederFile } from './seed-scaffold';
+// Driver utilities
+export * from './drivers/index';
+// Custom migrations (jobs, errors, etc.)
+export * from './custom/index';
+// Auth tables migration
+export * from './auth-tables';
+// uuid column guarantee for `useUuid` models (stacksjs/status#1 Phase 9)
+export * from './uuid-columns';
+// Notification tables migration (stacksjs/stacks#1937)
+export { migrateNotificationTables } from './notification-tables';
+// RBAC tables migration (stacksjs/stacks#1941 Phase A)
+export { migrateRbacTables } from './rbac-tables';
+// SQL dialect helpers & connection defaults
+export * from './sql-helpers';
+export * from './defaults';
+// Foreign-key audit (stacksjs/stacks#1916) — compare declared
+// `belongsTo` relationships against live FKs.
+export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from './fk-audit';
+// Unique-index drift audit (stacksjs/stacks#1952) — compare declared
+// `unique: true` attributes / indexes against live UNIQUE indexes.
+export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from './unique-audit';
+// Transaction context: AsyncLocalStorage-based scope so side-effect
+// emitters (queue dispatch, mailer send) can buffer themselves
+// until the surrounding `db.transaction(...)` commits
+// (stacksjs/stacks#1882).
+export {
+  __flushAfterCommitNow,
+  __pendingAfterCommitCount,
+  enqueueAfterCommit,
+  isInTransaction,
+  runInTransactionScope,
+} from './transaction-context';
+// Re-export bun-query-builder functions and types
+export {
+  createQueryBuilder,
+  setConfig,
+} from '@stacksjs/query-builder';
+// DynamoDB entity-centric API
+export {
+  createDynamo,
+  dynamo,
+  EntityQueryBuilder,
+  generateKeyPattern,
+  parseKeyPattern,
+  buildKey,
+  marshall,
+  unmarshall,
+} from './drivers/dynamodb';

package/dist/index.js

@@ -0,0 +1,55 @@
+export {
+  Database,
+  createDatabase,
+  createMysqlDatabase,
+  createPostgresDatabase,
+  createSqliteDatabase
+} from "./database";
+export {
+  detectDriver,
+  driverDefaults,
+  getConfigFromEnv,
+  getConnectionString,
+  mergeWithDefaults,
+  validateDriverConfig
+} from "./driver-config";
+export * from "./utils";
+export * from "./types";
+export * from "./migrations";
+export { setQueryTracker, logQuery } from "./query-logger";
+export { Seeder, runClassSeeders } from "./class-seeder";
+export { addColumnSafely, backfillInBatches, renameColumnSafely } from "./safe-migrations";
+export * from "./seeder";
+export { factory, generate as factoryGenerate } from "./factory";
+export { scaffoldClassSeedersFromModels, renderSeederFile } from "./seed-scaffold";
+export * from "./drivers";
+export * from "./custom";
+export * from "./auth-tables";
+export * from "./uuid-columns";
+export { migrateNotificationTables } from "./notification-tables";
+export { migrateRbacTables } from "./rbac-tables";
+export * from "./sql-helpers";
+export * from "./defaults";
+export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from "./fk-audit";
+export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from "./unique-audit";
+export {
+  __flushAfterCommitNow,
+  __pendingAfterCommitCount,
+  enqueueAfterCommit,
+  isInTransaction,
+  runInTransactionScope
+} from "./transaction-context";
+export {
+  createQueryBuilder,
+  setConfig
+} from "@stacksjs/query-builder";
+export {
+  createDynamo,
+  dynamo,
+  EntityQueryBuilder,
+  generateKeyPattern,
+  parseKeyPattern,
+  buildKey,
+  marshall,
+  unmarshall
+} from "./drivers/dynamodb";

package/dist/migration-lock.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Acquire the distributed migration lock for the given dialect.
+ * Returns a handle whose `release()` method MUST be called in a
+ * `finally` to free the lock — even on error paths.
+ *
+ * @param dialect - which database driver is being migrated against
+ * @param adminDb - the bun-query-builder connection to issue lock SQL
+ *                  through (PG / MySQL). Ignored for SQLite.
+ * @param opts.timeoutMs - max time to wait for an existing holder
+ * @param opts.sqliteLockPath - override the file path SQLite uses
+ *
+ * Throws an error if the lock can't be acquired within `timeoutMs`.
+ */
+export declare function acquireMigrationLock(dialect: Dialect, adminDb: { unsafe: (sql: string) => Promise<unknown> } | null, opts?: { timeoutMs?: number, sqliteLockPath?: string }): Promise<MigrationLockHandle>;
+/**
+ * Returned by `acquireMigrationLock()`. Callers MUST invoke `release`
+ * in a finally block; the lock is process-external (file, advisory,
+ * or named) so leaking it strands future migration runs.
+ */
+export declare interface MigrationLockHandle {
+  release: () => Promise<void>
+}
+export type Dialect = 'sqlite' | 'mysql' | 'postgres';

package/dist/migration-lock.js

@@ -0,0 +1,143 @@
+import { Buffer } from "node:buffer";
+import { createHash } from "node:crypto";
+import { closeSync, openSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import process from "node:process";
+import { userDatabasePath } from "@stacksjs/path";
+const DEFAULT_TIMEOUT_MS = 30000, INITIAL_BACKOFF_MS = 100, MAX_BACKOFF_MS = 2000, STALE_LOCK_MS = 60000, LOCK_NAME = "stacks_migrations";
+export async function acquireMigrationLock(dialect, adminDb, opts = {}) {
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  if (dialect !== "sqlite" && dialect !== "postgres" && dialect !== "mysql")
+    throw Error(`[migration-lock] unknown dialect: ${String(dialect)}`);
+  if (dialect === "sqlite")
+    return acquireSqliteLock(opts.sqliteLockPath, timeoutMs);
+  if (!adminDb)
+    throw Error(`[migration-lock] ${dialect} requires a database connection to acquire the lock`);
+  if (dialect === "postgres")
+    return acquirePostgresLock(adminDb, timeoutMs);
+  return acquireMySqlLock(adminDb, timeoutMs);
+}
+function lockKeysForPostgres() {
+  const hash = createHash("sha256").update(LOCK_NAME).digest(), key1 = hash.readInt32BE(0), key2 = hash.readInt32BE(4);
+  return { key1, key2 };
+}
+async function acquirePostgresLock(adminDb, timeoutMs) {
+  const { key1, key2 } = lockKeysForPostgres(), start = Date.now();
+  let backoff = INITIAL_BACKOFF_MS;
+  while (!0) {
+    const result = await adminDb.unsafe(`SELECT pg_try_advisory_lock(${key1}, ${key2}) AS acquired`);
+    if (extractFirstBool(result, "acquired"))
+      return {
+        release: async () => {
+          try {
+            await adminDb.unsafe(`SELECT pg_advisory_unlock(${key1}, ${key2})`);
+          } catch {}
+        }
+      };
+    if (Date.now() - start >= timeoutMs)
+      throw Error("[migration-lock] another migration is in progress \u2014 could not acquire postgres advisory lock within timeout");
+    await sleepWithJitter(backoff);
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  }
+}
+async function acquireMySqlLock(adminDb, timeoutMs) {
+  const start = Date.now();
+  let backoff = INITIAL_BACKOFF_MS;
+  while (!0) {
+    const result = await adminDb.unsafe(`SELECT GET_LOCK('${LOCK_NAME}', 0) AS acquired`);
+    if (extractFirstInt(result, "acquired") === 1)
+      return {
+        release: async () => {
+          try {
+            await adminDb.unsafe(`SELECT RELEASE_LOCK('${LOCK_NAME}')`);
+          } catch {}
+        }
+      };
+    if (Date.now() - start >= timeoutMs)
+      throw Error("[migration-lock] another migration is in progress \u2014 could not acquire MySQL named lock within timeout");
+    await sleepWithJitter(backoff);
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  }
+}
+function defaultSqliteLockPath() {
+  return userDatabasePath(".migration.lock");
+}
+async function acquireSqliteLock(lockPath, timeoutMs) {
+  const path = lockPath ?? defaultSqliteLockPath(), start = Date.now();
+  let backoff = INITIAL_BACKOFF_MS;
+  while (!0) {
+    if (tryCreateLockFile(path)) {
+      let released = !1;
+      return {
+        release: async () => {
+          if (released)
+            return;
+          released = !0;
+          try {
+            unlinkSync(path);
+          } catch {}
+        }
+      };
+    }
+    reclaimIfStale(path);
+    if (Date.now() - start >= timeoutMs)
+      throw Error(`[migration-lock] another migration is in progress \u2014 lock file ${path} held within timeout`);
+    await sleepWithJitter(backoff);
+    backoff = Math.min(backoff * 2, MAX_BACKOFF_MS);
+  }
+}
+function tryCreateLockFile(path) {
+  try {
+    const fd = openSync(path, "wx");
+    try {
+      const payload = JSON.stringify({ pid: process.pid, startedAt: new Date().toISOString() });
+      writeFileSync(fd, Buffer.from(payload, "utf8"));
+    } finally {
+      closeSync(fd);
+    }
+    return !0;
+  } catch (e) {
+    if (e.code === "EEXIST")
+      return !1;
+    throw e;
+  }
+}
+function reclaimIfStale(path) {
+  try {
+    const st = statSync(path);
+    if (Date.now() - st.mtimeMs > STALE_LOCK_MS)
+      try {
+        unlinkSync(path);
+      } catch {}
+  } catch {}
+}
+function sleepWithJitter(ms) {
+  const jittered = ms * (1 + Math.random() * 0.25);
+  return new Promise((resolve) => setTimeout(resolve, jittered));
+}
+function extractFirstBool(result, column) {
+  const row = pluckFirstRow(result);
+  if (!row)
+    return !1;
+  const value = row[column];
+  return value === !0 || value === 1 || value === "1" || value === "t";
+}
+function extractFirstInt(result, column) {
+  const row = pluckFirstRow(result);
+  if (!row)
+    return null;
+  const value = row[column];
+  if (typeof value === "number")
+    return value;
+  if (typeof value === "string" && /^-?\d+$/.test(value))
+    return Number.parseInt(value, 10);
+  return null;
+}
+function pluckFirstRow(result) {
+  if (!result)
+    return null;
+  if (Array.isArray(result))
+    return result[0];
+  if (typeof result === "object" && "rows" in result && Array.isArray(result.rows))
+    return result.rows[0];
+  return null;
+}

package/dist/migrations.d.ts

@@ -0,0 +1,76 @@
+import type { MigrationOperation } from '@stacksjs/query-builder';
+import type { Result } from '@stacksjs/error-handling';
+export type { MigrationResult as MigrationResultType };
+/**
+ * SQLite compatibility preprocessing for migrations.
+ *
+ * SQLite does not support:
+ * - ALTER TABLE ADD CONSTRAINT (foreign keys must be defined at table creation)
+ * - CREATE TYPE ... AS ENUM (SQLite has no user-defined types; enum columns
+ *   are plain TEXT, with the allowed values enforced at the validation layer)
+ *
+ * Note: CREATE UNIQUE INDEX files are deliberately NOT skipped — the SQLite
+ * dialect driver never renders inline UNIQUE in CREATE TABLE, so the
+ * standalone index file is the only uniqueness enforcement on SQLite
+ * (stacksjs/stacks#1952).
+ *
+ * Two flavours of "no-op on SQLite" need different handling:
+ *
+ *   - **Skip-and-keep** (`skipMigration`): the file is portable — it would
+ *     run cleanly on MySQL/Postgres — but doesn't apply to SQLite. Record
+ *     it as executed in the migrations tracking table so it doesn't replay,
+ *     but **leave the file on disk** so a future `DB_CONNECTION` flip can
+ *     pick it up. This is the right path for FK constraint files.
+ *     (stacksjs/stacks#1916)
+ *
+ *   - **Drop-and-delete** (`deleteMigration`): the file is genuinely dead
+ *     — a duplicate CREATE TABLE created by `buddy generate:migrations`
+ *     regenerating against an already-modeled table, or a DROP COLUMN
+ *     migration whose target column never existed. Removing it keeps the
+ *     directory clean and prevents future runs from re-discovering it.
+ */
+export declare function preprocessSqliteMigrations(): void;
+/**
+ * Run database migrations
+ */
+export declare function runDatabaseMigration(): Promise<Result<string, Error>>;
+/**
+ * Reset the database (drop all tables)
+ */
+export declare function resetDatabase(): Promise<Result<string, Error>>;
+/**
+ * Preview the pending migration as a list of structured operations WITHOUT
+ * writing any files or advancing the snapshot. The `buddy migrate` command
+ * uses this (in the interactive parent process) to gate destructive changes
+ * behind confirmation before spawning the non-interactive migrate action.
+ */
+export declare function previewPendingMigrations(options?: GenerateMigrationsOptions): Promise<MigrationOperation[]>;
+export declare function generateMigrations(options?: GenerateMigrationsOptions): Promise<Result<string, Error>>;
+/**
+ * Generate fresh migrations (full regeneration, ignoring previous state)
+ */
+export declare function generateMigrations2(): Promise<Result<string, Error>>;
+/*` definitions to the stored snapshot
+ * (`.qb/model-snapshot.<dialect>.json`) via bun-query-builder, then — if
+ * there are changes — writes the resulting ALTER/CREATE/DROP statements
+ * out to a fresh file in `database/migrations/`. Each statement is
+ * grouped by table + DDL verb and lands in its own file using the
+ * runner's existing naming convention so it picks them up the same way
+ * as a hand-written migration.
+ *
+ * Without this write step the qb generator stages the diff in memory but
+ * the runner never sees it, so model edits silently no-op'd — defeating
+ * the "models are the source of truth" promise.
+ */
+export declare interface GenerateMigrationsOptions {
+  applyRenames?: boolean
+  fromDb?: boolean
+}
+/**
+ * Migration result type for compatibility
+ */
+export declare interface MigrationResult {
+  migrationName: string
+  direction: 'Up' | 'Down'
+  status: 'Success' | 'Error' | 'NotExecuted'
+}