@stacksjs/database 0.70.200 → 0.70.202

package/dist/ensure-database.d.ts

@@ -0,0 +1,101 @@
+export declare function isValidDatabaseIdentifier(name: string): boolean;
+/** Quote an identifier for the dialect. Only ever called after validation. */
+export declare function quoteIdentifier(dialect: 'postgres' | 'mysql', name: string): string;
+/**
+ * Classify a driver error. The shapes below were captured from Bun's real
+ * Postgres client, not inferred: a missing database surfaces
+ * `errno: "3D000"` (a STRING) with `code: "ERR_POSTGRES_SERVER_ERROR"`, a
+ * missing role `errno: "28000"`, and a refused socket carries no errno at all
+ * but `code: "ERR_POSTGRES_CONNECTION_REFUSED"`. MySQL reports numeric errnos,
+ * so both types are accepted.
+ */
+export declare function classifyConnectionError(error: unknown): ConnectionFailureKind;
+/**
+ * Resolve the connection the migration runner will actually use.
+ *
+ * Precedence mirrors bun-query-builder's `createConnectionString()` exactly
+ * (env first, config second), because bqb is what opens the real connection.
+ * A config-first resolver here would let us create `foo` while bqb migrates
+ * `bar`.
+ *
+ * Returns `null` when there is nothing to bootstrap: SQLite creates its file
+ * on open, DynamoDB has no SQL catalog, and an unknown driver is not ours to
+ * guess at.
+ */
+export declare function resolveConnectionTarget(envProxy?: Record<string, any>): ConnectionTarget | null;
+/** Build a connection URL for an arbitrary database on the same server. */
+export declare function buildConnectionUrl(target: ConnectionTarget, database: string): string;
+/**
+ * Probe the TARGET database directly.
+ *
+ * Order matters: we do not open a maintenance connection first. On a
+ * locked-down managed instance the app user often cannot touch `postgres` or
+ * `mysql` at all, so leading with maintenance would fail even when the target
+ * exists and everything would otherwise have worked.
+ */
+export declare function probeTargetDatabase(target: ConnectionTarget, deps?: EnsureDatabaseDeps): Promise<ProbeResult>;
+/**
+ * Issue `CREATE DATABASE` from a maintenance connection.
+ *
+ * Ownership note: we authenticate as the same user the app will use, so the
+ * new database is owned by that user and no explicit OWNER clause is needed.
+ * That matters on PG15+, where a database owned by someone else leaves the app
+ * role unable to create tables in `public`.
+ */
+export declare function createDatabase(target: ConnectionTarget, deps?: EnsureDatabaseDeps): Promise<CreateDatabaseResult>;
+/**
+ * Best-effort check for whether the connected role may create databases.
+ * Used to avoid asking a question whose "yes" is guaranteed to fail.
+ * Returns `null` when the answer cannot be determined, which callers must
+ * treat as "go ahead and try".
+ */
+export declare function canCreateDatabases(target: ConnectionTarget, deps?: EnsureDatabaseDeps): Promise<boolean | null>;
+/** Human-readable, copy-pasteable remediation for a failed or declined create. */
+export declare function manualCreateHint(target: ConnectionTarget): string;
+/** One-line description of what we are pointed at, for prompts and errors. */
+export declare function describeTarget(target: ConnectionTarget): string;
+/**
+ * A connection we can issue maintenance DDL on. Structurally satisfied by
+ * Bun's `SQL` instance; declared here so tests can substitute a fake.
+ */
+export declare interface MaintenanceClient {
+  unsafe: (sql: string) => any
+  close: () => any
+}
+export declare interface ConnectionTarget {
+  dialect: 'postgres' | 'mysql'
+  driver: string
+  database: string
+  host: string
+  port: number
+  username: string
+  password: string
+  maintenanceCandidates: string[]
+}
+export declare interface ProbeResult {
+  ok: boolean
+  kind?: ConnectionFailureKind
+  error?: unknown
+}
+export declare interface EnsureDatabaseDeps {
+  connect?: ConnectFn
+  timeoutMs?: number
+}
+export declare interface CreateDatabaseResult {
+  created: boolean
+  kind?: ConnectionFailureKind
+  error?: unknown
+  via?: string
+}
+export type ConnectFn = (url: string) => MaintenanceClient;
+/**
+ * Why a connection attempt failed. Callers branch on this rather than on
+ * error message text, which differs per server version and locale.
+ */
+export type ConnectionFailureKind = | 'missing-database'
+  | 'missing-role'
+  | 'auth-failed'
+  | 'server-unreachable'
+  | 'permission-denied'
+  | 'timeout'
+  | 'unknown';

package/dist/ensure-database.js

@@ -0,0 +1,145 @@
+import process from "node:process";
+import { SQL } from "bun";
+import { env as envVars } from "@stacksjs/env";
+import { DB_HOST_DEFAULT, DB_NAMES, DB_PORTS, DB_USERS, getConnectionDefaults } from "./defaults";
+const DEFAULT_TIMEOUT_MS = 1e4, UNSAFE_IDENTIFIER_CHARS = /["'`\\;\u0000\n\r]/, MAX_IDENTIFIER_LENGTH = 63;
+export function isValidDatabaseIdentifier(name) {
+  if (!name || name.length > MAX_IDENTIFIER_LENGTH)
+    return !1;
+  return !UNSAFE_IDENTIFIER_CHARS.test(name);
+}
+export function quoteIdentifier(dialect, name) {
+  return dialect === "mysql" ? `\`${name}\`` : `"${name}"`;
+}
+function stripWrappingQuotes(value) {
+  return value.replace(/^['"]|['"]$/g, "");
+}
+export function classifyConnectionError(error) {
+  const e = error, errno = e?.errno, code = typeof e?.code === "string" ? e.code : "", message = typeof e?.message === "string" ? e.message : String(error ?? ""), sqlState = typeof errno === "string" ? errno.toUpperCase() : "", mysqlErrno = typeof errno === "number" ? errno : Number.NaN;
+  if (sqlState === "3D000")
+    return "missing-database";
+  if (sqlState === "28000" || sqlState === "28P01")
+    return sqlState === "28P01" ? "auth-failed" : "missing-role";
+  if (sqlState === "42501")
+    return "permission-denied";
+  if (mysqlErrno === 1049)
+    return "missing-database";
+  if (mysqlErrno === 1045)
+    return "auth-failed";
+  if (mysqlErrno === 1044)
+    return "permission-denied";
+  if (mysqlErrno === 2002 || mysqlErrno === 2003)
+    return "server-unreachable";
+  if (code.includes("CONNECTION_REFUSED") || code.includes("CONNECTION_CLOSED") || code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EHOSTUNREACH")
+    return "server-unreachable";
+  if (code === "ETIMEDOUT" || code.includes("TIMEOUT"))
+    return "timeout";
+  if (/database .* does not exist|unknown database/i.test(message))
+    return "missing-database";
+  if (/role .* does not exist|user .* does not exist/i.test(message))
+    return "missing-role";
+  if (/password authentication failed|access denied for user/i.test(message))
+    return "auth-failed";
+  if (/permission denied|insufficient privilege/i.test(message))
+    return "permission-denied";
+  if (/econnrefused|connection refused|can'?t connect/i.test(message))
+    return "server-unreachable";
+  return "unknown";
+}
+export function resolveConnectionTarget(envProxy = envVars) {
+  const driver = String(envProxy.DB_CONNECTION || "sqlite");
+  if (driver !== "postgres" && driver !== "mysql" && driver !== "singlestore")
+    return null;
+  const dialect = driver === "postgres" ? "postgres" : "mysql", defaults = getConnectionDefaults(dialect, envProxy), database = stripWrappingQuotes(String(envProxy.DB_DATABASE || defaults.database || DB_NAMES.default)), host = String(envProxy.DB_HOST || defaults.host || DB_HOST_DEFAULT), port = Number(envProxy.DB_PORT || defaults.port || DB_PORTS[dialect]), username = String(envProxy.DB_USERNAME || defaults.username || DB_USERS[dialect]), password = String(envProxy.DB_PASSWORD ?? defaults.password ?? "");
+  return {
+    dialect,
+    driver,
+    database,
+    host,
+    port,
+    username,
+    password,
+    maintenanceCandidates: dialect === "postgres" ? ["postgres", "template1"] : ["information_schema", "mysql"]
+  };
+}
+export function buildConnectionUrl(target, database) {
+  const scheme = target.dialect === "postgres" ? "postgres" : "mysql", auth = target.password ? `${encodeURIComponent(target.username)}:${encodeURIComponent(target.password)}` : encodeURIComponent(target.username), sslEnv = process.env.DB_SSL, ssl = sslEnv === "true" || sslEnv === "1" ? "?ssl=true" : "";
+  return `${scheme}://${auth}@${target.host}:${target.port}/${encodeURIComponent(database)}${ssl}`;
+}
+function defaultConnect(url) {
+  return new SQL(url);
+}
+async function withConnection(target, database, deps, work) {
+  const connect = deps.connect ?? defaultConnect, timeoutMs = deps.timeoutMs ?? Number(process.env.DB_PREFLIGHT_TIMEOUT_MS || DEFAULT_TIMEOUT_MS), client = connect(buildConnectionUrl(target, database));
+  let timer;
+  try {
+    const timeout = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        const e = Error(`Timed out after ${timeoutMs}ms connecting to ${target.dialect} at ${target.host}:${target.port}`);
+        e.code = "ETIMEDOUT";
+        reject(e);
+      }, timeoutMs);
+    });
+    return await Promise.race([work(client), timeout]);
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    try {
+      await client.close();
+    } catch {}
+  }
+}
+export async function probeTargetDatabase(target, deps = {}) {
+  try {
+    await withConnection(target, target.database, deps, async (client) => client.unsafe("select 1"));
+    return { ok: !0 };
+  } catch (error) {
+    return { ok: !1, kind: classifyConnectionError(error), error };
+  }
+}
+export async function createDatabase(target, deps = {}) {
+  if (!isValidDatabaseIdentifier(target.database))
+    return {
+      created: !1,
+      kind: "unknown",
+      error: Error(`Refusing to create a database named ${JSON.stringify(target.database)}. Database names must be 1 to 63 characters and may not contain quotes, backslashes, semicolons, or newlines.`)
+    };
+  const identifier = quoteIdentifier(target.dialect, target.database), sql = target.dialect === "mysql" ? `CREATE DATABASE IF NOT EXISTS ${identifier}` : `CREATE DATABASE ${identifier}`;
+  let lastError, lastKind = "unknown";
+  for (const candidate of target.maintenanceCandidates)
+    try {
+      await withConnection(target, candidate, deps, async (client) => client.unsafe(sql));
+      return { created: !0, via: candidate };
+    } catch (error) {
+      const kind = classifyConnectionError(error), message = error?.message ?? "", errno = error?.errno;
+      if (errno === "42P04" || errno === 1007 || /already exists|database exists/i.test(String(message)))
+        return { created: !1, via: candidate };
+      lastError = error;
+      lastKind = kind;
+      if (kind === "permission-denied" || kind === "auth-failed" || kind === "missing-role")
+        break;
+    }
+  return { created: !1, kind: lastKind, error: lastError };
+}
+export async function canCreateDatabases(target, deps = {}) {
+  if (target.dialect !== "postgres")
+    return null;
+  for (const candidate of target.maintenanceCandidates)
+    try {
+      return await withConnection(target, candidate, deps, async (client) => {
+        const rows = await client.unsafe("select rolcreatedb, rolsuper from pg_roles where rolname = current_user"), row = Array.isArray(rows) ? rows[0] : void 0;
+        if (!row)
+          return null;
+        return Boolean(row.rolcreatedb || row.rolsuper);
+      });
+    } catch {}
+  return null;
+}
+export function manualCreateHint(target) {
+  if (target.dialect === "postgres")
+    return `createdb -h ${target.host} -p ${target.port} -U ${target.username} ${target.database}`;
+  return `mysql -h ${target.host} -P ${target.port} -u ${target.username} -e "CREATE DATABASE \\\`${target.database}\\\`"`;
+}
+export function describeTarget(target) {
+  return `the ${target.driver} connection (${target.host}:${target.port}, user "${target.username}")`;
+}

package/dist/index.d.ts

@@ -102,6 +102,13 @@ export { migrateRbacTables } from './rbac-tables';
 // SQL dialect helpers & connection defaults
 export * from './sql-helpers';
 export * from './defaults';
+// Dialect classification for the committed migration corpus, so a corpus
+// emitted for one database fails loudly before a single statement runs.
+export * from './migration-dialect';
+// Database bootstrap: probe the target, and create it over a maintenance
+// connection we open ourselves rather than through bun-query-builder, whose
+// connection string is rebuilt from process.env and cannot be redirected.
+export * from './ensure-database';
 // Foreign-key audit (stacksjs/stacks#1916) — compare declared
 // `belongsTo` relationships against live FKs.
 export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from './fk-audit';

package/dist/index.js

@@ -28,6 +28,8 @@ export { migrateNotificationTables } from "./notification-tables";
 export { migrateRbacTables } from "./rbac-tables";
 export * from "./sql-helpers";
 export * from "./defaults";
+export * from "./migration-dialect";
+export * from "./ensure-database";
 export { auditForeignKeys, findFkOrphans, getDeclaredFKs, getLiveFKs } from "./fk-audit";
 export { auditUniqueIndexes, getDeclaredUniques, getLiveUniqueIndexes } from "./unique-audit";
 export {

package/dist/migration-dialect.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Blank out comments and quoted text, preserving offsets so reported line
+ * numbers still point at the real source line.
+ *
+ * This is the whole reason `migrate:switch` was reporting 40 foreign-key
+ * migrations that do not exist: it regex-matched raw file content, so the
+ * words inside `-- Skipped: SQLite does not support ALTER TABLE ADD
+ * CONSTRAINT` counted as an ALTER TABLE ADD CONSTRAINT.
+ */
+export declare function stripSqlNoise(sql: string): string;
+/** Find dialect-exclusive markers in one file's SQL. */
+export declare function classifyMigrationSql(sql: string, file: string): DialectMarker[];
+/**
+ * Audit a whole migration directory against the dialect it is about to run on.
+ *
+ * `inferred` is only set when every marker found agrees, so a genuinely mixed
+ * or portable corpus reports `null` rather than a misleading guess.
+ */
+export declare function auditMigrationCorpus(options: {
+  dir: string
+  target: MigrationDialect
+}): MigrationCorpusAudit;
+/**
+ * The user-facing explanation. Long on purpose: this replaces a raw
+ * `syntax error at or near "AUTOINCREMENT"` that told the user nothing about
+ * why their brand new project could not migrate.
+ */
+export declare function formatMigrationDialectError(audit: MigrationCorpusAudit, target: MigrationDialect, dir: string): string;
+/** Environment escape hatch, for an operator whose corpus is genuinely fine. */
+export declare const DIALECT_OVERRIDE_ENV: 'STACKS_ALLOW_DIALECT_MISMATCH';
+export declare interface DialectMarker {
+  dialect: MigrationDialect
+  marker: string
+  file: string
+  line: number
+  snippet: string
+}
+export declare interface MigrationCorpusAudit {
+  total: number
+  inferred: MigrationDialect | null
+  incompatible: DialectMarker[]
+  empty: boolean
+}
+export type MigrationDialect = 'sqlite' | 'postgres' | 'mysql';

package/dist/migration-dialect.js

@@ -0,0 +1,106 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const MARKERS = [
+  { dialect: "sqlite", pattern: /\bAUTOINCREMENT\b/i, label: "AUTOINCREMENT" },
+  { dialect: "sqlite", pattern: /\bWITHOUT\s+ROWID\b/i, label: "WITHOUT ROWID" },
+  { dialect: "sqlite", pattern: /\bPRAGMA\b/i, label: "PRAGMA" },
+  { dialect: "mysql", pattern: /\bAUTO_INCREMENT\b/i, label: "AUTO_INCREMENT" },
+  { dialect: "mysql", pattern: /\bENGINE\s*=/i, label: "ENGINE=" },
+  { dialect: "postgres", pattern: /\bBIGSERIAL\b/i, label: "BIGSERIAL" },
+  { dialect: "postgres", pattern: /\bSERIAL\b/i, label: "SERIAL" },
+  { dialect: "postgres", pattern: /\bCREATE\s+TYPE\b/i, label: "CREATE TYPE" },
+  { dialect: "postgres", pattern: /\bGENERATED\s+(?:ALWAYS|BY\s+DEFAULT)\s+AS\s+IDENTITY\b/i, label: "GENERATED AS IDENTITY" }
+];
+export function stripSqlNoise(sql) {
+  let out = "", i = 0;
+  const blank = (text) => text.replace(/[^\n]/g, " ");
+  while (i < sql.length) {
+    const rest = sql.slice(i), line = rest.match(/^--[^\n]*/);
+    if (line) {
+      out += blank(line[0]);
+      i += line[0].length;
+      continue;
+    }
+    if (rest.startsWith("/*")) {
+      const end = rest.indexOf("*/"), chunk = end === -1 ? rest : rest.slice(0, end + 2);
+      out += blank(chunk);
+      i += chunk.length;
+      continue;
+    }
+    const quote = rest[0];
+    if (quote === '"' || quote === "'" || quote === "`") {
+      let j = 1;
+      while (j < rest.length && rest[j] !== quote)
+        j++;
+      const chunk = rest.slice(0, Math.min(j + 1, rest.length));
+      out += blank(chunk);
+      i += chunk.length;
+      continue;
+    }
+    out += sql[i];
+    i += 1;
+  }
+  return out;
+}
+export function classifyMigrationSql(sql, file) {
+  const lines = stripSqlNoise(sql).split(`
+`), rawLines = sql.split(`
+`), found = [];
+  for (let index = 0;index < lines.length; index++)
+    for (const { dialect, pattern, label } of MARKERS)
+      if (pattern.test(lines[index] ?? ""))
+        found.push({
+          dialect,
+          marker: label,
+          file,
+          line: index + 1,
+          snippet: (rawLines[index] ?? "").trim().slice(0, 120)
+        });
+  return found;
+}
+export function auditMigrationCorpus(options) {
+  const { dir, target } = options;
+  if (!existsSync(dir))
+    return { total: 0, inferred: null, incompatible: [], empty: !0 };
+  let files;
+  try {
+    files = readdirSync(dir).filter((f) => f.endsWith(".sql")).sort();
+  } catch {
+    return { total: 0, inferred: null, incompatible: [], empty: !0 };
+  }
+  const all = [];
+  for (const file of files) {
+    let sql;
+    try {
+      sql = readFileSync(join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    all.push(...classifyMigrationSql(sql, file));
+  }
+  const dialects = new Set(all.map((m) => m.dialect));
+  return {
+    total: files.length,
+    inferred: dialects.size === 1 ? [...dialects][0] ?? null : null,
+    incompatible: all.filter((m) => m.dialect !== target),
+    empty: files.length === 0
+  };
+}
+export const DIALECT_OVERRIDE_ENV = "STACKS_ALLOW_DIALECT_MISMATCH";
+export function formatMigrationDialectError(audit, target, dir) {
+  const affected = new Set(audit.incompatible.map((m) => m.file)), sample = audit.incompatible.slice(0, 3), inferred = audit.inferred ? `${audit.inferred}-flavoured` : "written for a different database";
+  return [
+    `The migration files in ${dir} are ${inferred} and cannot run on ${target}.`,
+    `${affected.size} of ${audit.total} files use SQL that ${target} does not accept. For example:`,
+    ...sample.map((m) => `  ${m.file}:${m.line}  ${m.marker}`),
+    "",
+    "Nothing was migrated, so the database is unchanged.",
+    "",
+    "Stacks ships one set of migration files, and they are emitted for a single database.",
+    `To use ${target}, regenerate them from your models against ${target}, or point`,
+    "DB_CONNECTION back at the database they were written for.",
+    "",
+    `If you know this corpus is correct, re-run with ${DIALECT_OVERRIDE_ENV}=1 to proceed anyway.`
+  ].join(`
+`);
+}

package/dist/migrations.d.ts

@@ -30,6 +30,21 @@ export type { MigrationResult as MigrationResultType };
  *     directory clean and prevents future runs from re-discovering it.
  */
 export declare function preprocessSqliteMigrations(): void;
+/**
+ * Public bootstrap entry point.
+ *
+ * Call this before ANY other database work in a command. `migrate` reaches the
+ * server from several independent places (auth tables, notification tables,
+ * RBAC tables, the numbered migrations), and each one used to discover a
+ * missing database on its own and report it separately, which is how a single
+ * root cause turned into twenty lines of near-identical errors.
+ *
+ * Throws with one actionable message. Only a success is memoised, so a
+ * transient failure can be retried in the same process.
+ */
+export declare function ensureDatabaseReady(): Promise<void>;
+/** Test seam: forget that the bootstrap already ran. */
+export declare function resetDatabaseBootstrapCache(): void;
 export declare function runDatabaseMigration(): Promise<Result<string, Error>>;
 /**
  * Reset the database (drop all tables)

package/dist/migrations.js

@@ -16,10 +16,19 @@ import {
   generateMigration as qbGenerateMigration,
   resetConnection,
   resetDatabase as qbResetDatabase,
+  config as qbConfig,
   saveMigrationSnapshot,
   setConfig
 } from "@stacksjs/query-builder";
 import { db } from "./utils";
+import {
+  classifyConnectionError,
+  createDatabase,
+  describeTarget,
+  manualCreateHint,
+  probeTargetDatabase,
+  resolveConnectionTarget
+} from "./ensure-database";
 import { frameworkManagedColumns, withoutManagedColumnDrops, withoutManagedColumnDropSql } from "./managed-columns";
 import { acquireMigrationLock } from "./migration-lock";
 import { env as envVars } from "@stacksjs/env";
@@ -53,6 +62,7 @@ function configureQueryBuilder() {
   setConfig({
     dialect,
     verbose: !1,
+    snapshotDir: "storage/framework/database",
     database: {
       database: connectionConfig?.name || connectionConfig?.database || "stacks",
       host: connectionConfig?.host || "localhost",
@@ -201,50 +211,59 @@ export function preprocessSqliteMigrations() {
       log.debug(`[migration] Could not record dropped migrations as executed: ${e}`);
     }
 }
+function mayCreateMissingDatabase() {
+  const signal = process.env.STACKS_CREATE_DATABASE;
+  if (signal === "1")
+    return !0;
+  if (signal === "0")
+    return !1;
+  const policy = String(process.env.DB_CREATE_DATABASE || "").toLowerCase();
+  return !(policy === "never" || policy === "false" || policy === "0");
+}
+function describeProbeFailure(target, kind, error) {
+  const where = describeTarget(target), detail = error instanceof Error ? error.message : String(error ?? "");
+  switch (kind) {
+    case "missing-role":
+      return `The user "${target.username}" does not exist on ${where}. Set DB_USERNAME to a role that exists, or create it with:  createuser -s ${target.username}`;
+    case "auth-failed":
+      return `Authentication failed for user "${target.username}" on ${where}. Check DB_USERNAME and DB_PASSWORD.`;
+    case "server-unreachable":
+      return `Could not reach the database server at ${target.host}:${target.port}. Check that it is running and that DB_HOST and DB_PORT are correct.`;
+    case "timeout":
+      return `Timed out connecting to the database server at ${target.host}:${target.port}. ${detail}`;
+    case "permission-denied":
+      return `The user "${target.username}" is not allowed to connect to "${target.database}" on ${where}.`;
+    default:
+      return `Could not connect to the database "${target.database}" on ${where}. ${detail}`;
+  }
+}
 async function ensureDatabaseExists() {
-  const dialect = getDialect();
-  if (dialect === "sqlite")
+  const target = resolveConnectionTarget();
+  if (!target)
     return;
-  const connectionConfig = dbConfig.connections[dialect], dbName = (connectionConfig?.name || "stacks").replace(/['"]/g, ""), host = connectionConfig?.host || "localhost", port = connectionConfig?.port || (dialect === "postgres" ? 5432 : 3306), username = connectionConfig?.username || (dialect === "postgres" ? process.env.USER || "postgres" : "root"), password = connectionConfig?.password || "", adminDatabase = dialect === "postgres" ? "postgres" : "mysql";
-  try {
-    setConfig({
-      dialect,
-      database: {
-        database: adminDatabase,
-        host,
-        port,
-        username,
-        password
-      }
-    });
-    resetConnection();
-    const adminDb = createQueryBuilder();
-    if (dialect === "postgres")
-      try {
-        await adminDb.unsafe(`CREATE DATABASE "${dbName}"`);
-        log.info(`Created database "${dbName}"`);
-      } catch (e) {
-        if (e?.message?.includes("already exists") || e?.errno === "42P04")
-          log.info(`Database "${dbName}" already exists`);
-        else
-          throw e;
-      }
-    else if (dialect === "mysql")
-      try {
-        await adminDb.unsafe(`CREATE DATABASE IF NOT EXISTS \`${dbName}\``);
-        log.info(`Ensured database "${dbName}" exists`);
-      } catch (e) {
-        if (e?.message?.includes("database exists"))
-          log.info(`Database "${dbName}" already exists`);
-        else
-          throw e;
-      }
-    resetConnection();
-  } catch (error) {
-    log.warn(`Could not auto-create database "${dbName}": ${error?.message || error}`);
-    log.info("If the database already exists, this warning can be ignored.");
-    resetConnection();
-  }
+  const probe = await probeTargetDatabase(target);
+  if (probe.ok)
+    return;
+  if (probe.kind !== "missing-database")
+    throw Error(describeProbeFailure(target, probe.kind, probe.error));
+  if (!mayCreateMissingDatabase())
+    throw Error(`The database "${target.database}" does not exist on ${describeTarget(target)}. Create it with:  ${manualCreateHint(target)}`);
+  const result = await createDatabase(target);
+  if (!result.created && result.error)
+    throw Error(`The database "${target.database}" does not exist on ${describeTarget(target)} and it could not be created automatically. ${describeProbeFailure(target, result.kind, result.error)}
+Create it yourself with:  ${manualCreateHint(target)}`);
+  if (result.created)
+    log.success(`Created database "${target.database}" on ${target.host}:${target.port}`);
+}
+let databaseBootstrapped = !1;
+export async function ensureDatabaseReady() {
+  if (databaseBootstrapped)
+    return;
+  await ensureDatabaseExists();
+  databaseBootstrapped = !0;
+}
+export function resetDatabaseBootstrapCache() {
+  databaseBootstrapped = !1;
 }
 async function hideDisabledFeatureMigrations() {
   const hidden = [];
@@ -325,7 +344,7 @@ function idempotentSql(sql) {
 `;
 }
 function makeMigrationsIdempotent() {
-  const migrationsDir = join(process.cwd(), "database", "migrations");
+  const rewritten = [], migrationsDir = join(process.cwd(), "database", "migrations");
   let files;
   try {
     files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql"));
@@ -346,16 +365,18 @@ function makeMigrationsIdempotent() {
     if (next !== sql)
       try {
         writeFileSync(p, next);
-        log.debug(`[migration] made idempotent: ${f}`);
+        rewritten.push(f);
       } catch {}
   }
+  if (rewritten.length > 0)
+    log.warn(`[migration] Rewrote ${rewritten.length} migration file(s) on disk to be idempotent: ${rewritten.slice(0, 3).join(", ")}${rewritten.length > 3 ? `, +${rewritten.length - 3} more` : ""}. These files are tracked in git, so this shows up as a working-tree change.`);
 }
 export async function runDatabaseMigration() {
   const startedAt = Date.now(), hidden = await hideDisabledFeatureMigrations();
   let lockHandle = null;
   try {
     log.debug("Migrating database...");
-    await ensureDatabaseExists();
+    await ensureDatabaseReady();
     configureQueryBuilder();
     const dialect = getDialect(), lockDb = dialect === "sqlite" ? null : createQueryBuilder();
     lockHandle = await acquireMigrationLock(dialect, lockDb);
@@ -395,10 +416,14 @@ const FRAMEWORK_TABLES = [
 ];
 export async function resetDatabase() {
   try {
+    await ensureDatabaseReady();
     configureQueryBuilder();
     const modelsDir = path.userModelsPath(), dialect = getDialect();
     await dropFrameworkTables(dialect);
-    await qbResetDatabase(modelsDir, { dialect });
+    if (existsSync(modelsDir))
+      await qbResetDatabase(modelsDir, { dialect });
+    else
+      log.debug(`No models directory at ${modelsDir}; skipping model table drops.`);
     return ok("All tables dropped successfully!");
   } catch (error) {
     return err(handleError("Database reset failed", error));
@@ -430,6 +455,9 @@ async function dropFrameworkTables(dialect) {
       await db.unsafe(dropSql).execute();
       log.info(`Dropped framework table: ${tableName}`);
     } catch (error) {
+      const kind = classifyConnectionError(error);
+      if (kind === "missing-database" || kind === "missing-role" || kind === "auth-failed" || kind === "server-unreachable" || kind === "timeout")
+        throw error;
       log.warn(`Could not drop table ${tableName}: ${error instanceof Error ? error.message : String(error)}`);
     }
   if (dialect === "mysql")
@@ -464,8 +492,12 @@ export async function previewPendingMigrations(options = {}) {
     return [];
   }
 }
+function resolveSnapshotDir() {
+  const configured = qbConfig?.snapshotDir;
+  return join(process.cwd(), configured || ".qb");
+}
 function detectSnapshotDialectMismatch(dialect) {
-  const qbDir = join(process.cwd(), ".qb");
+  const qbDir = resolveSnapshotDir();
   let files;
   try {
     files = readdirSync(qbDir);

package/package.json

@@ -2,7 +2,7 @@
   "name": "@stacksjs/database",
   "type": "module",
   "sideEffects": false,
-  "version": "0.70.200",
+  "version": "0.70.202",
   "description": "The Stacks database integration.",
   "author": "Chris Breuer",
   "contributors": [
@@ -60,15 +60,15 @@
     "dynamodb-tooling": "^0.3.2"
   },
   "devDependencies": {
-    "@stacksjs/cli": "0.70.200",
-    "@stacksjs/config": "0.70.200",
-    "@stacksjs/logging": "0.70.200",
-    "@stacksjs/router": "0.70.200",
+    "@stacksjs/cli": "0.70.202",
+    "@stacksjs/config": "0.70.202",
+    "@stacksjs/logging": "0.70.202",
+    "@stacksjs/router": "0.70.202",
     "better-dx": "^0.2.17",
-    "@stacksjs/path": "0.70.200",
-    "@stacksjs/query-builder": "0.70.200",
-    "@stacksjs/storage": "0.70.200",
-    "@stacksjs/strings": "0.70.200",
-    "@stacksjs/utils": "0.70.200"
+    "@stacksjs/path": "0.70.202",
+    "@stacksjs/query-builder": "0.70.202",
+    "@stacksjs/storage": "0.70.202",
+    "@stacksjs/strings": "0.70.202",
+    "@stacksjs/utils": "0.70.202"
   }
 }