@stacksjs/database 0.70.229 → 0.70.230

package/dist/migrations.js

@@ -1,5 +1,5 @@
 var {require}=import.meta;import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { dirname, isAbsolute, join } from "node:path";
 import { log as _log } from "@stacksjs/logging";
 const log = {
   info: (...args) => typeof _log?.info === "function" ? _log.info(...args) : console.log(...args),
@@ -10,6 +10,7 @@ const log = {
 };
 import { err, handleError, ok } from "@stacksjs/error-handling";
 import { path } from "@stacksjs/path";
+import { defaultModelsPath } from "./seeder";
 import {
   createQueryBuilder,
   executeMigration as qbExecuteMigration,
@@ -32,9 +33,18 @@ import {
 import { resolveModelSources } from "./model-sources";
 import { frameworkManagedColumns, withoutManagedColumnDrops, withoutManagedColumnDropSql } from "./managed-columns";
 import { acquireMigrationLock } from "./migration-lock";
+import { migrateNotificationTables } from "./notification-tables";
 import { env as envVars } from "@stacksjs/env";
 import { getConnectionDefaults } from "./defaults";
-const dbDriver = envVars.DB_CONNECTION || "sqlite", sqliteDefaults = getConnectionDefaults("sqlite", envVars), mysqlDefaults = getConnectionDefaults("mysql", envVars), postgresDefaults = getConnectionDefaults("postgres", envVars), dbConfig = {
+const databaseEnv = {
+  DB_CONNECTION: process.env.DB_CONNECTION || envVars.DB_CONNECTION,
+  DB_DATABASE_PATH: process.env.DB_DATABASE_PATH || envVars.DB_DATABASE_PATH,
+  DB_DATABASE: process.env.DB_DATABASE || envVars.DB_DATABASE,
+  DB_HOST: process.env.DB_HOST || envVars.DB_HOST,
+  DB_PORT: process.env.DB_PORT ? Number(process.env.DB_PORT) : envVars.DB_PORT,
+  DB_USERNAME: process.env.DB_USERNAME || envVars.DB_USERNAME,
+  DB_PASSWORD: process.env.DB_PASSWORD || envVars.DB_PASSWORD
+}, dbDriver = databaseEnv.DB_CONNECTION || "sqlite", sqliteDefaults = getConnectionDefaults("sqlite", databaseEnv), mysqlDefaults = getConnectionDefaults("mysql", databaseEnv), postgresDefaults = getConnectionDefaults("postgres", databaseEnv), dbConfig = {
   default: dbDriver,
   connections: {
     sqlite: { database: sqliteDefaults.database, prefix: "" },
@@ -42,6 +52,10 @@ const dbDriver = envVars.DB_CONNECTION || "sqlite", sqliteDefaults = getConnecti
     postgres: { name: postgresDefaults.database, host: postgresDefaults.host, username: postgresDefaults.username, password: postgresDefaults.password, port: postgresDefaults.port, prefix: "" }
   }
 };
+function sqliteDatabasePath() {
+  const configured = dbConfig.connections.sqlite.database || "stacks.db";
+  return isAbsolute(configured) ? configured : join(process.cwd(), configured);
+}
 function getDriver() {
   return dbConfig.default || "sqlite";
 }
@@ -74,9 +88,17 @@ function configureQueryBuilder() {
   });
   resetConnection();
 }
-function prepareMigrationModelsDir() {
-  const userModelsDir = path.userModelsPath();
-  return { modelsDir: userModelsDir, skip: !existsSync(userModelsDir) };
+export function prepareMigrationModelsDir() {
+  const sources = resolveModelSources();
+  return {
+    modelsDir: sources?.dir ?? path.userModelsPath(),
+    skip: !sources
+  };
+}
+export function sqlStatementsOf(content) {
+  return content.split(`
+`).map((line) => line.replace(/--.*$/, "")).join(`
+`).split(";").map((s) => s.trim()).filter((s) => s.length > 0);
 }
 export function preprocessSqliteMigrations() {
   const migrationsDir = join(process.cwd(), "database", "migrations");
@@ -95,7 +117,7 @@ export function preprocessSqliteMigrations() {
       unlinkSync(filePath);
     } catch {}
     droppedMigrations.push(file);
-  }, replayMigrations = [], addConstraintPattern = /^\s*ALTER\s+TABLE\s+.+\s+ADD\s+CONSTRAINT\s+/i, createTypePattern = /^\s*CREATE\s+TYPE\s+/i, createUniqueIndexPattern = /^\s*CREATE\s+UNIQUE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?(\w+)["'`]?/i, dropColumnPattern = /^\s*ALTER\s+TABLE\s+["']?(\w+)["']?\s+DROP\s+COLUMN\s+["']?(\w+)["']?\s*$/i, createTablePattern = /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i, createTableEarliest = new Map;
+  }, replayMigrations = [], addConstraintPattern = /^\s*ALTER\s+TABLE\s+.+\s+ADD\s+CONSTRAINT\s+/i, createTypePattern = /^\s*CREATE\s+TYPE\s+/i, createUniqueIndexPattern = /^\s*CREATE\s+UNIQUE\s+INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["'`]?(\w+)["'`]?/i, dropColumnPattern = /^\s*ALTER\s+TABLE\s+["']?(\w+)["']?\s+DROP\s+COLUMN\s+["']?(\w+)["']?\s*$/i, addColumnPattern = /^\s*ALTER\s+TABLE\s+["']?(\w+)["']?\s+ADD\s+COLUMN\s+["'`]?(\w+)["'`]?/i, createTablePattern = /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["']?(\w+)["']?/i, createTableEarliest = new Map;
   for (const file of files) {
     const m = file.match(/^\d+-create-(\w+)-table\.sql$/);
     if (!m || !m[1])
@@ -104,18 +126,51 @@ export function preprocessSqliteMigrations() {
     if (!existing || file < existing)
       createTableEarliest.set(tableName, file);
   }
-  const sqliteDbPath = join(process.cwd(), dbConfig.connections.sqlite.database || "stacks.db");
+  const earlierCreateDefinesColumn = (migrationFile, table, column) => {
+    const createFile = createTableEarliest.get(table);
+    if (!createFile || createFile >= migrationFile)
+      return !1;
+    try {
+      const createContent = readFileSync(join(migrationsDir, createFile), "utf8"), createStatement = sqlStatementsOf(createContent).find((statement) => statement.match(createTablePattern)?.[1] === table);
+      if (!createStatement)
+        return !1;
+      const escapedColumn = column.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      return new RegExp(`(?:^|[,(])\\s*["'\`]?${escapedColumn}["'\`]?\\s+`, "i").test(createStatement);
+    } catch {
+      return !1;
+    }
+  }, sqliteDbPath = sqliteDatabasePath();
   let sqliteDb = null;
   if (existsSync(sqliteDbPath))
     try {
       const { Database } = require("bun:sqlite");
       sqliteDb = new Database(sqliteDbPath, { readonly: !0 });
     } catch {}
+  const migrationWasRecorded = (file) => {
+    if (!sqliteDb)
+      return !1;
+    try {
+      return Boolean(sqliteDb.prepare("SELECT 1 FROM migrations WHERE migration = ? LIMIT 1").get(file));
+    } catch {
+      return !1;
+    }
+  };
   for (const file of files) {
     log.debug(`[migration] Running: ${file}`);
-    const filePath = join(migrationsDir, file), statements = readFileSync(filePath, "utf-8").split(";").map((s) => s.trim()).filter((s) => s.length > 0 && !s.startsWith("--"));
+    const filePath = join(migrationsDir, file), content = readFileSync(filePath, "utf-8"), statements = sqlStatementsOf(content);
     if (statements.length === 0)
       continue;
+    const uniqueIndexNames = statements.map((s) => s.match(createUniqueIndexPattern)?.[1]).filter((name) => Boolean(name));
+    if (sqliteDb && uniqueIndexNames.length === statements.length) {
+      const indexExists = sqliteDb.prepare("SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?");
+      if (uniqueIndexNames.filter((name) => !indexExists.get(name)).length > 0) {
+        log.info(`Re-queueing unique-index migration (index missing from database): ${file}`);
+        replayMigrations.push(file);
+      }
+      continue;
+    }
+    if (migrationWasRecorded(file))
+      continue;
     const firstStatement = statements[0], createTableMatch = firstStatement ? firstStatement.match(createTablePattern) : null;
     if (createTableMatch && createTableMatch[1]) {
       const tableName = createTableMatch[1], earliest = createTableEarliest.get(tableName);
@@ -132,14 +187,28 @@ export function preprocessSqliteMigrations() {
       skipMigration(file, "SQLite does not support CREATE TYPE (enum types)");
       continue;
     }
-    const uniqueIndexNames = statements.map((s) => s.match(createUniqueIndexPattern)?.[1]).filter((name) => Boolean(name));
-    if (sqliteDb && uniqueIndexNames.length === statements.length) {
-      const indexExists = sqliteDb.prepare("SELECT name FROM sqlite_master WHERE type = 'index' AND name = ?");
-      if (uniqueIndexNames.filter((name) => !indexExists.get(name)).length > 0) {
-        log.info(`Re-queueing unique-index migration (index missing from database): ${file}`);
-        replayMigrations.push(file);
+    const addColumnTargets = statements.map((s) => s.match(addColumnPattern)).filter((m) => Boolean(m?.[1] && m[2])).map((m) => ({ table: m[1], column: m[2] }));
+    if (addColumnTargets.length > 0 && addColumnTargets.length === statements.length) {
+      const satisfied = addColumnTargets.filter(({ table, column }) => {
+        try {
+          if (sqliteDb) {
+            const safeTableName = table.replace(/[^a-zA-Z0-9_]/g, ""), columns = sqliteDb.prepare(`PRAGMA table_info("${safeTableName}")`).all();
+            if (columns.some((col) => col.name === column))
+              return !0;
+            if (columns.length > 0)
+              return !1;
+          }
+          return earlierCreateDefinesColumn(file, table, column);
+        } catch {
+          return !1;
+        }
+      });
+      if (satisfied.length === addColumnTargets.length) {
+        skipMigration(file, "every column it adds already exists or is defined by an earlier create-table migration");
+        continue;
       }
-      continue;
+      if (satisfied.length > 0)
+        log.warn(`[migration] ${file} is partially applied: ${satisfied.map((p) => `${p.table}.${p.column}`).join(", ")} already exist${satisfied.length === 1 ? "s" : ""} or will be created earlier, the rest do not. SQLite cannot skip a single ADD COLUMN, so this file will fail. Add the remaining columns by hand, or split the file so the applied statements sit in their own migration.`);
     }
     if (statements.some((s) => dropColumnPattern.test(s))) {
       let modified = !1;
@@ -149,6 +218,10 @@ export function preprocessSqliteMigrations() {
         if (dropColMatch && dropColMatch[1] && dropColMatch[2]) {
           const tableName = dropColMatch[1], columnName = dropColMatch[2];
           if (!sqliteDb) {
+            if (earlierCreateDefinesColumn(file, tableName, columnName)) {
+              filteredStatements.push(stmt);
+              continue;
+            }
             log.info(`Skipping DROP COLUMN "${columnName}" \u2014 no database exists yet: ${file}`);
             modified = !0;
             continue;
@@ -156,6 +229,10 @@ export function preprocessSqliteMigrations() {
           try {
             const safeTableName = tableName.replace(/[^a-zA-Z0-9_]/g, ""), columns = sqliteDb.prepare(`PRAGMA table_info("${safeTableName}")`).all();
             if (columns.length === 0) {
+              if (earlierCreateDefinesColumn(file, tableName, columnName)) {
+                filteredStatements.push(stmt);
+                continue;
+              }
               log.info(`Skipping DROP COLUMN "${columnName}" \u2014 table "${tableName}" does not exist yet: ${file}`);
               modified = !0;
               continue;
@@ -166,6 +243,10 @@ export function preprocessSqliteMigrations() {
               continue;
             }
           } catch {
+            if (earlierCreateDefinesColumn(file, tableName, columnName)) {
+              filteredStatements.push(stmt);
+              continue;
+            }
             log.info(`Skipping DROP COLUMN "${columnName}" \u2014 table "${tableName}" not found: ${file}`);
             modified = !0;
             continue;
@@ -190,7 +271,7 @@ export function preprocessSqliteMigrations() {
     } catch {}
   if (droppedMigrations.length > 0 || replayMigrations.length > 0)
     try {
-      const dbPath = join(process.cwd(), dbConfig.connections.sqlite.database || "stacks.db");
+      const dbPath = sqliteDatabasePath();
       mkdirSync(dirname(dbPath), { recursive: !0 });
       const { Database } = require("bun:sqlite"), writeDb = new Database(dbPath);
       try {
@@ -275,7 +356,7 @@ async function hideDisabledFeatureMigrations() {
     const disabledFeatures = new Set(FEATURE_NAMES.filter((f) => !isFeatureEnabled(f)));
     if (disabledFeatures.size === 0)
       return hidden;
-    const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
+    const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql")), gatedTables = new Set;
     for (const file of files) {
       const owner = migrationFeature(file);
       if (!owner || !disabledFeatures.has(owner))
@@ -283,10 +364,24 @@ async function hideDisabledFeatureMigrations() {
       const table = migrationTable(file);
       if (table && appModelClaimsTable(table))
         continue;
+      if (table)
+        gatedTables.add(table.toLowerCase());
       const original = join(migrationsDir, file), hiddenPath = `${original}.disabled`;
       await fs.rename(original, hiddenPath);
       hidden.push({ original, hidden: hiddenPath, feature: owner });
     }
+    for (const file of files) {
+      const filePath = join(migrationsDir, file);
+      if (!existsSync(filePath))
+        continue;
+      const sql = readFileSync(filePath, "utf8"), filtered = withoutGatedStatements(sql, gatedTables);
+      if (filtered === sql)
+        continue;
+      const backup = `${filePath}.ungated`;
+      await fs.rename(filePath, backup);
+      writeFileSync(filePath, filtered);
+      hidden.push({ original: filePath, hidden: backup, feature: "mixed" });
+    }
     if (hidden.length > 0) {
       const summary = Object.entries(hidden.reduce((acc, h) => {
         acc[h.feature] = (acc[h.feature] ?? 0) + 1;
@@ -297,10 +392,39 @@ async function hideDisabledFeatureMigrations() {
   } catch {}
   return hidden;
 }
+export function statementTable(statement) {
+  const patterns = [
+    /^\s*ALTER\s+TABLE\s+["`]?([a-z0-9_]+)["`]?/i,
+    /^\s*CREATE\s+TABLE\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?([a-z0-9_]+)["`]?/i,
+    /^\s*DROP\s+TABLE\s+(?:IF\s+EXISTS\s+)?["`]?([a-z0-9_]+)["`]?/i,
+    /^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?[a-z0-9_]+["`]?\s+ON\s+["`]?([a-z0-9_]+)["`]?/i
+  ];
+  for (const pattern of patterns) {
+    const match = pattern.exec(statement);
+    if (match)
+      return match[1].toLowerCase();
+  }
+  return null;
+}
+export function withoutGatedStatements(sql, gated) {
+  if (gated.size === 0)
+    return sql;
+  const statements = sql.split(";").map((s) => s.trim()).filter(Boolean), kept = statements.filter((statement) => {
+    const table = statementTable(statement);
+    return !table || !gated.has(table);
+  });
+  if (kept.length === statements.length)
+    return sql;
+  return kept.length === 0 ? "" : `${kept.join(`;
+`)};
+`;
+}
 async function restoreHiddenMigrations(hidden) {
   const fs = await import("node:fs/promises");
   for (const { original, hidden: h } of hidden)
     try {
+      if (h.endsWith(".ungated"))
+        await fs.rm(original, { force: !0 });
       await fs.rename(h, original);
     } catch {}
 }
@@ -379,6 +503,9 @@ export async function runDatabaseMigration() {
     log.debug("Migrating database...");
     await ensureDatabaseReady();
     configureQueryBuilder();
+    const notificationTables = await migrateNotificationTables();
+    if (!notificationTables.success)
+      throw Error(notificationTables.error || "Failed to prepare notification tables");
     const dialect = getDialect(), lockDb = dialect === "sqlite" ? null : createQueryBuilder();
     lockHandle = await acquireMigrationLock(dialect, lockDb);
     if (dialect === "sqlite")
@@ -425,11 +552,43 @@ export async function resetDatabase() {
       await qbResetDatabase(modelsDir, { dialect });
     else
       log.debug(`No models directory at ${modelsDir}; skipping model table drops.`);
+    const defaultsDir = defaultModelsPath();
+    if (existsSync(defaultsDir))
+      await qbResetDatabase(defaultsDir, { dialect });
+    else
+      log.debug(`No framework default models directory at ${defaultsDir}; skipping.`);
+    if (dialect === "postgres")
+      await dropOrphanedEnumTypes();
     return ok("All tables dropped successfully!");
   } catch (error) {
     return err(handleError("Database reset failed", error));
   }
 }
+async function dropOrphanedEnumTypes() {
+  try {
+    const rows = await db.unsafe(`
+      SELECT t.typname AS name
+      FROM pg_type t
+      JOIN pg_namespace n ON n.oid = t.typnamespace
+      WHERE t.typtype = 'e'
+        AND n.nspname = current_schema()
+        AND NOT EXISTS (
+          SELECT 1 FROM pg_attribute a
+          JOIN pg_class c ON c.oid = a.attrelid
+          WHERE a.atttypid = t.oid AND c.relkind = 'r' AND NOT a.attisdropped
+        )
+    `).execute(), names = (Array.isArray(rows) ? rows : rows?.rows ?? []).map((row) => String(row.name ?? row.typname ?? "")).filter(Boolean);
+    for (const name of names)
+      try {
+        await db.unsafe(`DROP TYPE IF EXISTS "${name}" CASCADE`).execute();
+        log.debug(`Dropped orphaned enum type: ${name}`);
+      } catch (error) {
+        log.warn(`Could not drop enum type ${name}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+  } catch (error) {
+    log.warn(`Could not list enum types to drop: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
 async function dropFrameworkTables(dialect) {
   if (dialect === "mysql")
     try {
@@ -499,6 +658,52 @@ function snapshotDirLabel() {
 function resolveSnapshotDir() {
   return join(process.cwd(), snapshotDirLabel());
 }
+function snapshotPathFor(dialect) {
+  return join(resolveSnapshotDir(), `model-snapshot.${dialect}.json`);
+}
+function readStoredMigrationPlan(dialect) {
+  const snapshotPath = snapshotPathFor(dialect);
+  if (!existsSync(snapshotPath))
+    return;
+  let parsed;
+  try {
+    parsed = JSON.parse(readFileSync(snapshotPath, "utf8"));
+  } catch (error) {
+    throw Error(`The migration snapshot is not valid JSON: ${snapshotPath}. Repair or regenerate it before creating migrations.`, { cause: error });
+  }
+  const candidate = parsed && typeof parsed === "object" && "plan" in parsed ? parsed.plan : parsed;
+  if (!candidate || typeof candidate !== "object" || !Array.isArray(candidate.tables))
+    throw TypeError(`The migration snapshot has an invalid structure: ${snapshotPath}. Repair or regenerate it before creating migrations.`);
+  return candidate;
+}
+export function preserveMigrationPlanTableOrder(next, previous) {
+  const orderedByPrevious = (values, previousValues, keyFor) => {
+    if (!previousValues)
+      return [...values];
+    const previousOrder = new Map(previousValues.map((value, index) => [keyFor(value), index])), nextOrder = new Map(values.map((value, index) => [keyFor(value), index])), previousCount = previousValues.length;
+    return [...values].sort((left, right) => {
+      const leftKey = keyFor(left), rightKey = keyFor(right), leftOrder = previousOrder.get(leftKey) ?? previousCount + nextOrder.get(leftKey), rightOrder = previousOrder.get(rightKey) ?? previousCount + nextOrder.get(rightKey);
+      return leftOrder - rightOrder;
+    });
+  }, previousTables = new Map(previous?.tables.map((table) => [table.table, table]) ?? []), tables = next.tables.map((table) => {
+    const previousTable = previousTables.get(table.table), previousColumns = new Map(previousTable?.columns.map((column) => [column.name, column]) ?? []);
+    return {
+      ...table,
+      columns: orderedByPrevious(table.columns.map((column) => {
+        if (next.dialect !== "sqlite" || !column.enumTypeName || previousColumns.get(column.name)?.enumTypeName)
+          return column;
+        const portableColumn = { ...column };
+        delete portableColumn.enumTypeName;
+        return portableColumn;
+      }), previousTable?.columns, (column) => column.name),
+      indexes: orderedByPrevious(table.indexes, previousTable?.indexes, (index) => index.name)
+    };
+  });
+  return {
+    ...next,
+    tables: orderedByPrevious(tables, previous?.tables, (table) => table.table)
+  };
+}
 function detectSnapshotDialectMismatch(dialect) {
   const qbDir = resolveSnapshotDir();
   let files;
@@ -526,7 +731,7 @@ export async function generateMigrations(options = {}) {
       const snapshotDir = snapshotDirLabel();
       return err(Error(`Refusing to generate migrations: resolved dialect "${dialect}" has no snapshot in ${snapshotDir}/, but "${mismatch}" does. DB_CONNECTION is likely unset or wrong ` + "(missing .env?) \u2014 generating now would write a full duplicate migration set in the " + `wrong dialect. Set DB_CONNECTION=${mismatch} (or your intended dialect) and retry. To intentionally start a new dialect from scratch, remove ${snapshotDir}/model-snapshot.${mismatch}.json first.`));
     }
-    const { modelsDir, skip } = prepareMigrationModelsDir();
+    const storedPlan = readStoredMigrationPlan(getQbDialect()), { modelsDir, skip } = prepareMigrationModelsDir();
     if (skip) {
       log.debug("No app/Models directory found; using committed framework migrations");
       return ok("Migrations generated");
@@ -535,12 +740,22 @@ export async function generateMigrations(options = {}) {
     log.debug(`[migration] Generating migrations for dialect: ${dialect}, models: ${modelsDir}`);
     const result = await qbGenerateMigration(modelsDir, { dialect: getQbDialect(), dryRun: !0, applyRenames, fromDb });
     let sqlStatements = result.sqlStatements ?? [];
+    if (dialect === "sqlite")
+      sqlStatements = inlineSqliteAddedColumnReferences(sqlStatements, result.plan);
     if (result.hasChanges && sqlStatements.length > 0) {
       const filtered = withoutManagedColumnDropSql(sqlStatements, await frameworkManagedColumns(), result.operations ?? []);
       if (filtered.removed.length > 0)
         log.debug(`[migration] Skipped ${filtered.removed.length} generated drop(s) of framework-managed column(s) (stacksjs/stacks#2075)`);
       sqlStatements = filtered.statements;
     }
+    if (result.hasChanges && sqlStatements.length > 0) {
+      const dangling = findDanglingTypeReferences(sqlStatements);
+      if (dangling.length > 0) {
+        const before = sqlStatements.length;
+        sqlStatements = sqlStatements.filter((statement) => !referencesUndefinedType(statement, dangling));
+        log.warn(`[migration] Skipped ${before - sqlStatements.length} generated statement(s) referencing enum type(s) nothing creates (${dangling.slice(0, 3).join(", ")}${dangling.length > 3 ? ", \u2026" : ""}). This is a bug in the migration generator, not in your models.`);
+      }
+    }
     if (result.hasChanges) {
       const written = persistGeneratedMigrations(sqlStatements);
       if (written > 0)
@@ -549,12 +764,19 @@ export async function generateMigrations(options = {}) {
         log.debug("Migration generation produced no new files (already up to date)");
     } else
       log.debug("No changes detected");
-    saveMigrationSnapshot(result.plan, { dialect: getQbDialect() });
+    const stablePlan = preserveMigrationPlanTableOrder(result.plan, storedPlan);
+    if (!storedPlan || JSON.stringify(stablePlan) !== JSON.stringify(storedPlan))
+      saveMigrationSnapshot(stablePlan, { dialect: getQbDialect() });
+    else
+      log.debug("Model snapshot unchanged");
     return ok("Migrations generated");
   } catch (error) {
     return err(handleError("Migration generation failed", error));
   }
 }
+export function referencesUndefinedType(statement, dangling) {
+  return dangling.some((name) => statement.includes(`"${name}"`));
+}
 export function findDanglingTypeReferences(statements) {
   const defined = new Set, referenced = new Set;
   for (const statement of statements) {
@@ -565,6 +787,32 @@ export function findDanglingTypeReferences(statements) {
   }
   return [...referenced].filter((name) => !defined.has(name)).sort();
 }
+export function inlineSqliteAddedColumnReferences(statements, plan) {
+  const references = new Map;
+  for (const table of plan?.tables ?? []) {
+    if (!table.table)
+      continue;
+    for (const column of table.columns ?? []) {
+      const reference = column.references;
+      if (!column.name || !reference?.table || !reference.column)
+        continue;
+      references.set(`${table.table}.${column.name}`, {
+        table: reference.table,
+        column: reference.column
+      });
+    }
+  }
+  if (references.size === 0)
+    return statements;
+  return statements.map((statement) => {
+    if (/\bREFERENCES\b/i.test(statement))
+      return statement;
+    const match = statement.match(/^(\s*ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+ADD\s+COLUMN\s+["`]?(\w+)["`]?\s+)([\s\S]*?)(;?\s*)$/i), reference = match?.[2] && match[3] ? references.get(`${match[2]}.${match[3]}`) : void 0;
+    if (!match || !reference)
+      return statement;
+    return `${match[1]}${match[4].trimEnd()} REFERENCES "${reference.table}"("${reference.column}")${match[5]}`;
+  });
+}
 export async function regenerateMigrationCorpus(options = {}) {
   try {
     configureQueryBuilder();
@@ -735,7 +983,7 @@ export function groupGeneratedStatements(sqlStatements) {
     const alter = stmt.match(/^\s*ALTER\s+TABLE\s+["`]?(\w+)["`]?\s+(?:ADD\s+COLUMN\s+["`]?(\w+)["`]?|DROP\s+COLUMN\s+["`]?(\w+)["`]?|ADD\s+CONSTRAINT)/i), alterTable = alter?.[1];
     if (alter && alterTable) {
       const isCreateTimeConstraint = createdTables.has(alterTable) && !alter[2] && !alter[3];
-      push(isCreateTimeConstraint ? "create-foreign-key-constraints" : `alter-${alterTable}-${alter[2] || alter[3] || "constraint"}`, stmt);
+      push(isCreateTimeConstraint ? "create-foreign-key-constraints" : `alter-${alterTable}-columns`, stmt);
       continue;
     }
     const idx = stmt.match(/^\s*CREATE\s+(?:UNIQUE\s+)?INDEX\s+(?:IF\s+NOT\s+EXISTS\s+)?["`]?(\w+)["`]?\s+ON\s+["`]?(\w+)["`]?/i), idxName = idx?.[1], idxTable = idx?.[2];

package/dist/notification-tables.d.ts

@@ -12,6 +12,12 @@ export declare function notificationsTableSql(sql: SqlHelpers): string;
  * preference upsert safe — matches `NotificationPreferenceRow`.
  */
 export declare function notificationPreferencesTableSql(sql: SqlHelpers): string;
+/**
+ * `CREATE TABLE IF NOT EXISTS notification_deliveries`. This table records
+ * every transport attempt made by `notify()` without mixing outbound delivery
+ * state into the database inbox table.
+ */
+export declare function notificationDeliveriesTableSql(sql: SqlHelpers): string;
 /**
  * Create the notification + notification_preferences tables. Idempotent
  * (`IF NOT EXISTS`), so it's safe to run on every `buddy migrate`.

package/dist/notification-tables.js

@@ -3,7 +3,7 @@ import { env as envVars } from "@stacksjs/env";
 import { db } from "./utils";
 import { sqlHelpers } from "./sql-helpers";
 function getDbDriver() {
-  return envVars.DB_CONNECTION || "sqlite";
+  return process.env.DB_CONNECTION || envVars.DB_CONNECTION || "sqlite";
 }
 export function notificationsTableSql(sql) {
   const { pkColumn, nullableTimestamp } = sql;
@@ -13,6 +13,7 @@ export function notificationsTableSql(sql) {
     type VARCHAR(255) NOT NULL,
     data TEXT NOT NULL,
     read_at ${nullableTimestamp},
+    uuid VARCHAR(36),
     created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
     updated_at ${nullableTimestamp}
   )`;
@@ -30,6 +31,23 @@ export function notificationPreferencesTableSql(sql) {
     UNIQUE (user_id, channel, category)
   )`;
 }
+export function notificationDeliveriesTableSql(sql) {
+  const { pkColumn, nullableTimestamp } = sql;
+  return `CREATE TABLE IF NOT EXISTS notification_deliveries (
+    ${pkColumn},
+    user_id INTEGER,
+    channel VARCHAR(50) NOT NULL,
+    recipient VARCHAR(1000) NOT NULL,
+    subject VARCHAR(255),
+    body TEXT NOT NULL,
+    status VARCHAR(50) NOT NULL DEFAULT 'pending',
+    error TEXT,
+    metadata TEXT,
+    sent_at ${nullableTimestamp},
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    updated_at ${nullableTimestamp}
+  )`;
+}
 export async function migrateNotificationTables(options = {}) {
   const dbDriver = getDbDriver(), sql = sqlHelpers(dbDriver);
   if (options.verbose)
@@ -43,6 +61,11 @@ export async function migrateNotificationTables(options = {}) {
       log.info("Creating notification_preferences table...");
     await db.unsafe(notificationPreferencesTableSql(sql)).execute();
     await db.unsafe("CREATE INDEX IF NOT EXISTS idx_notification_preferences_user ON notification_preferences (user_id)").execute();
+    if (options.verbose)
+      log.info("Creating notification deliveries table...");
+    await db.unsafe(notificationDeliveriesTableSql(sql)).execute();
+    await db.unsafe("CREATE INDEX IF NOT EXISTS idx_notification_deliveries_channel ON notification_deliveries (channel)").execute();
+    await db.unsafe("CREATE INDEX IF NOT EXISTS idx_notification_deliveries_status ON notification_deliveries (status)").execute();
     if (options.verbose)
       log.success("Notification tables created");
     return { success: !0 };

package/dist/query-logger.d.ts

@@ -3,6 +3,7 @@ export declare function setQueryTracker(fn: QueryTracker): void;
  * Process an executed query and store it in the database
  */
 export declare function logQuery(event: LogEvent): Promise<void>;
+export declare function isExcludedQuery(query: string, excludedQueries: readonly string[]): boolean;
 /**
  * Query log event type - compatible with bun-query-builder hooks
  */

package/dist/query-logger.js

@@ -13,11 +13,15 @@ export async function logQuery(event) {
     return;
   try {
     const { query, durationMs, error, bindings } = extractQueryInfo(event);
-    try {
-      trackQuery(query, durationMs, config.database?.default || "unknown");
-    } catch {}
+    if (query)
+      try {
+        trackQuery(query, durationMs, config.database?.default || "unknown");
+      } catch {}
     if (!config.database?.queryLogging?.enabled)
       return;
+    const excludedQueries = config.database?.queryLogging?.excludedQueries;
+    if (!query.trim() || isExcludedQuery(query, Array.isArray(excludedQueries) ? excludedQueries : []))
+      return;
     const status = determineQueryStatus(durationMs, error), logRecord = await createQueryLogRecord(query, durationMs, status, error, bindings);
     if (config.database?.queryLogging?.analysis?.enabled && (status === "slow" || config.database.queryLogging.analysis.analyzeAll))
       await enhanceWithQueryAnalysis(logRecord);
@@ -38,8 +42,27 @@ export async function logQuery(event) {
     log.error("Failed to log query:", err);
   }
 }
+export function isExcludedQuery(query, excludedQueries) {
+  const normalizedQuery = query.toLowerCase();
+  return excludedQueries.some((pattern) => {
+    const normalizedPattern = pattern.trim().toLowerCase();
+    return normalizedPattern.length > 0 && normalizedQuery.includes(normalizedPattern);
+  });
+}
+function queryText(sql) {
+  if (typeof sql === "string")
+    return usableQueryText(sql);
+  if (sql && typeof sql === "object" && typeof sql.then === "function")
+    return "";
+  if (sql && typeof sql.toString === "function")
+    return usableQueryText(String(sql));
+  return "";
+}
+function usableQueryText(text) {
+  return text.startsWith("[object ") ? "" : text;
+}
 function extractQueryInfo(event) {
-  const query = event.query?.sql || "", durationMs = event.queryDurationMillis || 0, error = event.error;
+  const query = queryText(event.query?.sql), durationMs = event.queryDurationMillis || 0, error = event.error;
   let bindings;
   if (event.query?.parameters)
     try {
@@ -208,6 +231,10 @@ async function storeQueryLog(logRecord) {
   try {
     await db.insertInto("query_logs").values(logRecord).execute();
   } catch (error) {
-    log.error("Failed to store query log:", error);
+    const message = error instanceof Error ? error.message : String(error);
+    if (/no such table|does not exist|doesn't exist/i.test(message) && /query_logs/i.test(message))
+      log.debug("Query logging will start after the query_logs table is migrated.");
+    else
+      log.error("Failed to store query log:", error);
   }
 }

package/dist/relation-columns.d.ts

@@ -0,0 +1,19 @@
+import type { Model } from '@stacksjs/types';
+/**
+ * The foreign key a single `belongsTo` entry puts on the declaring model's
+ * table. Accepts both forms the type allows: a bare model name, and the
+ * object form with an explicit `foreignKey`.
+ */
+export declare function belongsToColumn(entry: unknown): string | null;
+/** Every foreign key column a model's `belongsTo` declarations imply. */
+export declare function belongsToColumnsOf(model: Model): string[];
+/**
+ * Resolve `table -> relation foreign key columns` across userland and
+ * framework-default models.
+ *
+ * A column that IS declared in `attributes` needs no protection — the differ
+ * already expects it — but including it changes nothing, since the guards only
+ * ever suppress drops of columns in this set and the differ never proposes
+ * dropping a column it expects.
+ */
+export declare function findRelationForeignKeys(): Promise<Map<string, Set<string>>>;