@spfn/core 0.2.0-beta.9 → 0.3.0-beta.2

package/dist/db/index.js

@@ -1,16 +1,17 @@
 import { drizzle } from 'drizzle-orm/postgres-js';
 import { env } from '@spfn/core/config';
 import { logger } from '@spfn/core/logger';
+import net from 'net';
 import postgres from 'postgres';
 import { QueryError, ConnectionError, DeadlockError, TransactionError, ConstraintViolationError, DuplicateEntryError, DatabaseError } from '@spfn/core/errors';
 import { parseNumber, parseBoolean } from '@spfn/core/env';
-import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
 import { join, dirname, basename } from 'path';
-import { bigserial, timestamp, uuid as uuid$1, text, jsonb, pgSchema } from 'drizzle-orm/pg-core';
+import { sql, count as count$1, lt, gt, and, desc, asc, eq } from 'drizzle-orm';
+import { bigserial, timestamp, bigint, uuid as uuid$1, text, jsonb, pgSchema } from 'drizzle-orm/pg-core';
+import { createHash, randomUUID } from 'crypto';
 import { AsyncLocalStorage } from 'async_hooks';
 import { createMiddleware } from 'hono/factory';
-import { randomUUID } from 'crypto';
-import { count as count$1, sql, eq, and } from 'drizzle-orm';
 
 // src/db/manager/factory.ts
 function parseUniqueViolation(message) {
@@ -129,7 +130,16 @@ function fromPostgresError(error) {
 }
 
 // src/db/manager/connection.ts
+function getSocketFamily() {
+  const family = process.env.DATABASE_SOCKET_FAMILY;
+  if (family === "4") return 4;
+  if (family === "6") return 6;
+  return void 0;
+}
 var dbLogger = logger.child("@spfn/core:database");
+function isTransactionPooler(connectionString) {
+  return /:6543(?:[/?]|$)|[?&]pgbouncer=true\b|pooler\.supabase\.com/i.test(connectionString);
+}
 var DEFAULT_CONNECT_TIMEOUT = 10;
 function delay(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));
@@ -189,10 +199,23 @@ async function createDatabaseConnection(connectionString, poolConfig, retryConfi
   let client;
   for (let attempt = 0; attempt <= retryConfig.maxRetries; attempt++) {
     try {
+      const socketFamily = getSocketFamily();
+      const prepare = poolConfig.prepare ?? !isTransactionPooler(connectionString);
       client = postgres(connectionString, {
         max: poolConfig.max,
         idle_timeout: poolConfig.idleTimeout,
-        connect_timeout: DEFAULT_CONNECT_TIMEOUT
+        connect_timeout: DEFAULT_CONNECT_TIMEOUT,
+        prepare,
+        ...socketFamily && {
+          socket: ({ host, port }) => new Promise((resolve, reject) => {
+            const socket = new net.Socket();
+            socket.on("error", reject);
+            socket.connect(
+              { port: port[0], host: host[0], family: socketFamily },
+              () => resolve(socket)
+            );
+          })
+        }
       });
       await client`SELECT 1 as test`;
       if (attempt > 0) {
@@ -325,10 +348,27 @@ function parseEnvBoolean(key, defaultValue) {
     throw new Error(`${key}: ${message}`);
   }
 }
+function parseEnvBooleanOptional(key) {
+  const value = process.env[key];
+  if (value === void 0) {
+    return void 0;
+  }
+  try {
+    return parseBoolean(value);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`${key}: ${message}`);
+  }
+}
 function getPoolConfig(options) {
+  const max = options?.max ?? parseEnvNumber("DB_POOL_MAX", 20, 10);
   return {
-    max: options?.max ?? parseEnvNumber("DB_POOL_MAX", 20, 10),
-    idleTimeout: options?.idleTimeout ?? parseEnvNumber("DB_POOL_IDLE_TIMEOUT", 30, 20)
+    max,
+    idleTimeout: options?.idleTimeout ?? parseEnvNumber("DB_POOL_IDLE_TIMEOUT", 30, 20),
+    // Defaults to the write `max`; DB_POOL_READ_MAX lets ops size the replica pool separately
+    readMax: options?.readMax ?? parseEnvNumber("DB_POOL_READ_MAX", max, max),
+    // Left undefined for connection-layer auto-detection unless explicitly overridden.
+    prepare: options?.prepare ?? parseEnvBooleanOptional("SPFN_DB_PREPARE")
   };
 }
 function getRetryConfig() {
@@ -397,11 +437,12 @@ async function createWriteReadClients(writeUrl, readUrl, poolConfig, retryConfig
     dbLogger2.error("Failed to connect to write database", errorObj);
     throw new Error(`Write database connection failed: ${errorObj.message}`, { cause: error });
   }
+  const readPoolConfig = { ...poolConfig, max: poolConfig.readMax ?? poolConfig.max };
   try {
-    readClient = await createDatabaseConnection(readUrl, poolConfig, retryConfig);
+    readClient = await createDatabaseConnection(readUrl, readPoolConfig, retryConfig);
     return {
-      write: drizzle(writeClient),
-      read: drizzle(readClient),
+      write: drizzle({ client: writeClient }),
+      read: drizzle({ client: readClient }),
       writeClient,
       readClient
     };
@@ -417,8 +458,8 @@ async function createWriteReadClients(writeUrl, readUrl, poolConfig, retryConfig
       }
     );
     return {
-      write: drizzle(writeClient),
-      read: drizzle(writeClient),
+      write: drizzle({ client: writeClient }),
+      read: drizzle({ client: writeClient }),
       writeClient,
       readClient: writeClient
     };
@@ -426,7 +467,7 @@ async function createWriteReadClients(writeUrl, readUrl, poolConfig, retryConfig
 }
 async function createSingleClient(url, poolConfig, retryConfig) {
   const client = await createDatabaseConnection(url, poolConfig, retryConfig);
-  const db = drizzle(client);
+  const db = drizzle({ client });
   return {
     write: db,
     read: db,
@@ -478,6 +519,11 @@ async function createDatabaseFromEnv(options) {
   throw new Error("No database pattern detected despite passing config check");
 }
 
+// src/db/manager/path-utils.ts
+function toPosixPath(path) {
+  return path.split("\\").join("/");
+}
+
 // src/db/manager/global-state.ts
 var getWriteInstance = () => globalThis.__SPFN_DB_WRITE__;
 var setWriteInstance = (instance) => {
@@ -487,6 +533,10 @@ var getReadInstance = () => globalThis.__SPFN_DB_READ__;
 var setReadInstance = (instance) => {
   globalThis.__SPFN_DB_READ__ = instance;
 };
+var getDatabaseProvider = () => globalThis.__SPFN_DB_PROVIDER__;
+var setDatabaseProviderInstance = (provider) => {
+  globalThis.__SPFN_DB_PROVIDER__ = provider;
+};
 var getWriteClient = () => globalThis.__SPFN_DB_WRITE_CLIENT__;
 var setWriteClient = (client) => {
   globalThis.__SPFN_DB_WRITE_CLIENT__ = client;
@@ -502,7 +552,32 @@ var setHealthCheckInterval = (interval) => {
 var setMonitoringConfig = (config) => {
   globalThis.__SPFN_DB_MONITORING__ = config;
 };
+var getInitOptions = () => globalThis.__SPFN_DB_INIT_OPTIONS__;
+var setInitOptions = (options) => {
+  globalThis.__SPFN_DB_INIT_OPTIONS__ = options;
+};
+var getInitPromise = () => globalThis.__SPFN_DB_INIT_PROMISE__;
+var setInitPromise = (promise) => {
+  globalThis.__SPFN_DB_INIT_PROMISE__ = promise;
+};
+var getInitProvider = () => globalThis.__SPFN_DB_INIT_PROVIDER__;
+var setInitProvider = (provider) => {
+  globalThis.__SPFN_DB_INIT_PROVIDER__ = provider;
+};
+var getClosePromise = () => globalThis.__SPFN_DB_CLOSE_PROMISE__;
+var setClosePromise = (promise) => {
+  globalThis.__SPFN_DB_CLOSE_PROMISE__ = promise;
+};
+var getIsClosing = () => globalThis.__SPFN_DB_CLOSING__ === true;
+var setIsClosing = (closing) => {
+  globalThis.__SPFN_DB_CLOSING__ = closing;
+};
 var dbLogger3 = logger.child("@spfn/core:database");
+var CLIENT_CLOSE_TIMEOUT = 5;
+var isReconnecting = false;
+function isReconnectingNow() {
+  return isReconnecting;
+}
 async function testDatabaseConnection(db) {
   await db.execute("SELECT 1");
 }
@@ -514,8 +589,17 @@ async function performHealthCheck(getDatabase2) {
     await testDatabaseConnection(read);
   }
 }
-async function reconnectAndRestore(options, closeDatabase2) {
-  await closeDatabase2();
+async function closeClient(client) {
+  try {
+    await client.end({ timeout: CLIENT_CLOSE_TIMEOUT });
+  } catch {
+  }
+}
+async function reconnectAndRestore(options) {
+  if (getIsClosing()) {
+    dbLogger3.debug("reconnectAndRestore aborted: database is closing");
+    return false;
+  }
   const result = await createDatabaseFromEnv(options);
   if (!result.write) {
     return false;
@@ -524,15 +608,33 @@ async function reconnectAndRestore(options, closeDatabase2) {
   if (result.read && result.read !== result.write) {
     await testDatabaseConnection(result.read);
   }
+  if (getIsClosing()) {
+    dbLogger3.warn("reconnectAndRestore: close started mid-rebuild, discarding new pool");
+    if (result.writeClient) {
+      await closeClient(result.writeClient);
+    }
+    if (result.readClient && result.readClient !== result.writeClient) {
+      await closeClient(result.readClient);
+    }
+    return false;
+  }
+  const oldWriteClient = getWriteClient();
+  const oldReadClient = getReadClient();
   setWriteInstance(result.write);
   setReadInstance(result.read);
   setWriteClient(result.writeClient);
   setReadClient(result.readClient);
   const monConfig = buildMonitoringConfig(options?.monitoring);
   setMonitoringConfig(monConfig);
+  if (oldWriteClient) {
+    closeClient(oldWriteClient);
+  }
+  if (oldReadClient && oldReadClient !== oldWriteClient) {
+    closeClient(oldReadClient);
+  }
   return true;
 }
-function startHealthCheck(config, options, getDatabase2, closeDatabase2) {
+function startHealthCheck(config, options, getDatabase2) {
   const healthCheck = getHealthCheckInterval();
   if (healthCheck) {
     dbLogger3.debug("Health check already running");
@@ -543,48 +645,85 @@ function startHealthCheck(config, options, getDatabase2, closeDatabase2) {
     reconnect: config.reconnect
   });
   const interval = setInterval(async () => {
+    if (isReconnecting) {
+      dbLogger3.debug("Health check skipped: reconnection in progress");
+      return;
+    }
     try {
       await performHealthCheck(getDatabase2);
     } catch (error) {
       const message = error instanceof Error ? error.message : "Unknown error";
       dbLogger3.error("Database health check failed", { error: message });
       if (config.reconnect) {
-        await attemptReconnection(config, options, closeDatabase2);
+        await attemptReconnection(config, options, "health_check_failed");
       }
     }
   }, config.interval);
   setHealthCheckInterval(interval);
 }
-async function attemptReconnection(config, options, closeDatabase2) {
+async function triggerForceReconnect(reason) {
+  if (getDatabaseProvider()) {
+    dbLogger3.debug("Force reconnect skipped: database is externally provided", { reason });
+    return false;
+  }
+  if (!getWriteInstance()) {
+    dbLogger3.warn("Force reconnect skipped: database not initialized", { reason });
+    return false;
+  }
+  if (getIsClosing()) {
+    dbLogger3.debug("Force reconnect skipped: database is closing", { reason });
+    return false;
+  }
+  const options = getInitOptions();
+  const config = buildHealthCheckConfig(options?.healthCheck);
+  dbLogger3.warn("Force reconnect triggered", { reason });
+  return await attemptReconnection(config, options, reason);
+}
+async function attemptReconnection(config, options, reason) {
+  if (getDatabaseProvider()) {
+    dbLogger3.debug("Reconnection skipped: database is externally provided", { reason });
+    return false;
+  }
+  if (isReconnecting) {
+    dbLogger3.debug("Reconnection coalesced: attempt already in progress", { reason });
+    return false;
+  }
+  isReconnecting = true;
   dbLogger3.warn("Attempting database reconnection", {
+    reason,
     maxRetries: config.maxRetries,
     retryInterval: `${config.retryInterval}ms`
   });
-  for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
-    try {
-      dbLogger3.debug(`Reconnection attempt ${attempt}/${config.maxRetries}`);
-      if (attempt > 1) {
-        await new Promise((resolve) => setTimeout(resolve, config.retryInterval));
+  try {
+    for (let attempt = 1; attempt <= config.maxRetries; attempt++) {
+      try {
+        dbLogger3.debug(`Reconnection attempt ${attempt}/${config.maxRetries}`);
+        if (attempt > 1) {
+          await new Promise((resolve) => setTimeout(resolve, config.retryInterval));
+        }
+        const success = await reconnectAndRestore(options);
+        if (success) {
+          dbLogger3.info("Database reconnection successful", { attempt });
+          return true;
+        } else {
+          dbLogger3.error(`Reconnection attempt ${attempt} failed: No write database instance created`);
+        }
+      } catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        dbLogger3.error(`Reconnection attempt ${attempt} failed`, {
+          error: message,
+          attempt,
+          maxRetries: config.maxRetries
+        });
       }
-      const success = await reconnectAndRestore(options, closeDatabase2);
-      if (success) {
-        dbLogger3.info("Database reconnection successful", { attempt });
-        return;
-      } else {
-        dbLogger3.error(`Reconnection attempt ${attempt} failed: No write database instance created`);
+      if (attempt === config.maxRetries) {
+        dbLogger3.error("Max reconnection attempts reached, will retry on next health check");
       }
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Unknown error";
-      dbLogger3.error(`Reconnection attempt ${attempt} failed`, {
-        error: message,
-        attempt,
-        maxRetries: config.maxRetries
-      });
-    }
-    if (attempt === config.maxRetries) {
-      dbLogger3.error("Max reconnection attempts reached, giving up");
     }
+  } finally {
+    isReconnecting = false;
   }
+  return true;
 }
 function stopHealthCheck() {
   const healthCheck = getHealthCheckInterval();
@@ -593,6 +732,7 @@ function stopHealthCheck() {
     setHealthCheckInterval(void 0);
     dbLogger3.info("Database health check stopped");
   }
+  isReconnecting = false;
 }
 
 // src/db/manager/manager.ts
@@ -603,8 +743,6 @@ var STACK_TRACE_PATTERNS = {
   withParens: /\((.+):(\d+):(\d+)\)/,
   withoutParens: /at (.+):(\d+):(\d+)/
 };
-var initPromise = null;
-var isClosing = false;
 async function cleanupDatabaseConnections(writeClient, readClient) {
   const cleanupPromises = [];
   if (writeClient) {
@@ -642,13 +780,40 @@ async function testDatabaseConnections(write, read) {
     }
   }
 }
+function validateDatabaseProvider(provider) {
+  if (typeof provider.kind !== "string" || !provider.kind.trim()) {
+    throw new Error("Database provider kind must be a non-empty string");
+  }
+}
+function registerDatabaseProvider(provider) {
+  setDatabaseProviderInstance(provider);
+  setWriteInstance(provider.write);
+  setReadInstance(provider.read ?? provider.write);
+  return {
+    write: provider.write,
+    read: provider.read ?? provider.write
+  };
+}
+async function closeDatabaseProvider(provider, context) {
+  if (!provider.close) {
+    return;
+  }
+  try {
+    await provider.close();
+  } catch (error) {
+    const closeError = error instanceof Error ? error : new Error(String(error));
+    dbLogger4.error(`Error closing ${provider.kind || "unknown"} database provider`, closeError, {
+      context
+    });
+  }
+}
 function getCallerInfo() {
   try {
     const stack = new Error().stack;
     if (!stack) return void 0;
     const lines = stack.split("\n");
     for (let i = STACK_TRACE_SKIP_LINES; i < lines.length; i++) {
-      const line = lines[i];
+      const line = toPosixPath(lines[i]);
       if (!line.includes("node_modules") && !line.includes("/db/manager/")) {
         const match = line.match(STACK_TRACE_PATTERNS.withParens) || line.match(STACK_TRACE_PATTERNS.withoutParens);
         if (match) {
@@ -701,24 +866,107 @@ function getDatabase(type) {
   return writeInst;
 }
 function setDatabase(write, read) {
+  if (getIsClosing()) {
+    throw new Error("Cannot set database while closing");
+  }
+  if (getInitPromise()) {
+    throw new Error("Cannot set database while initialization is in progress");
+  }
+  if (getDatabaseProvider()) {
+    throw new Error(
+      "An external database provider is active. Call closeDatabase() before setting a database manually."
+    );
+  }
+  if (getWriteClient() || getReadClient()) {
+    throw new Error(
+      "Managed database connections are active. Call closeDatabase() before setting a database manually."
+    );
+  }
+  setDatabaseProviderInstance(void 0);
   setWriteInstance(write);
   setReadInstance(read ?? write);
 }
+function setDatabaseProvider(provider) {
+  validateDatabaseProvider(provider);
+  const activeProvider = getDatabaseProvider();
+  if (getIsClosing()) {
+    throw new Error("Cannot set database provider while closing");
+  }
+  if (getInitPromise()) {
+    throw new Error("Cannot set database provider while initialization is in progress");
+  }
+  if (activeProvider === provider) {
+    return {
+      write: provider.write,
+      read: provider.read ?? provider.write
+    };
+  }
+  if (getWriteInstance() || getReadInstance() || getWriteClient() || getReadClient() || activeProvider) {
+    throw new Error(
+      "Database already initialized. Call closeDatabase() before registering a different provider."
+    );
+  }
+  return registerDatabaseProvider(provider);
+}
 async function initDatabase(options) {
-  if (isClosing) {
+  if (getIsClosing()) {
     throw new Error("Cannot initialize database while closing");
   }
   const writeInst = getWriteInstance();
   if (writeInst) {
+    const activeProvider = getDatabaseProvider();
+    if (!activeProvider && !getWriteClient()) {
+      throw new Error(
+        "Database was registered manually. Use getDatabase() directly or call closeDatabase() before initDatabase()."
+      );
+    }
+    if (options?.provider !== activeProvider) {
+      const detail = options?.provider ? "a different provider was supplied" : "the active external provider was not supplied";
+      throw new Error(`Database already initialized: ${detail}`);
+    }
     dbLogger4.debug("Database already initialized");
-    return { write: writeInst, read: getReadInstance() };
+    return {
+      write: writeInst,
+      read: getReadInstance()
+    };
   }
-  if (initPromise) {
+  const activeInitPromise = getInitPromise();
+  if (activeInitPromise) {
+    if (options?.provider !== getInitProvider()) {
+      throw new Error("Database initialization already in progress with a different provider");
+    }
     dbLogger4.debug("Database initialization in progress, waiting...");
-    return await initPromise;
+    return await activeInitPromise;
   }
-  initPromise = (async () => {
+  setInitProvider(options?.provider);
+  const currentInit = (async () => {
     try {
+      if (options?.provider) {
+        const provider = options.provider;
+        try {
+          validateDatabaseProvider(provider);
+          await testDatabaseConnections(provider.write, provider.read);
+          if (getIsClosing()) {
+            throw new Error("Database closed during initialization");
+          }
+          const monConfig2 = buildMonitoringConfig(options.monitoring);
+          const result2 = registerDatabaseProvider(provider);
+          setInitOptions(options);
+          setMonitoringConfig(monConfig2);
+          dbLogger4.info("Database provider connected", {
+            kind: provider.kind,
+            hasReplica: !!(provider.read && provider.read !== provider.write)
+          });
+          return result2;
+        } catch (error) {
+          await closeDatabaseProvider(provider, "initialization_failed");
+          if (error instanceof Error && (error.message === "Database provider kind must be a non-empty string" || error.message === "Database closed during initialization")) {
+            throw error;
+          }
+          const message = error instanceof Error ? error.message : "Unknown error";
+          throw new Error(`Database connection test failed: ${message}`);
+        }
+      }
       const result = await createDatabaseFromEnv(options);
       try {
         await testDatabaseConnections(result.write, result.read);
@@ -727,7 +975,7 @@ async function initDatabase(options) {
         const message = error instanceof Error ? error.message : "Unknown error";
         throw new Error(`Database connection test failed: ${message}`);
       }
-      if (isClosing) {
+      if (getIsClosing()) {
         dbLogger4.warn("Database closed during initialization, cleaning up...");
         await cleanupDatabaseConnections(result.writeClient, result.readClient);
         throw new Error("Database closed during initialization");
@@ -736,13 +984,14 @@ async function initDatabase(options) {
       setReadInstance(result.read);
       setWriteClient(result.writeClient);
       setReadClient(result.readClient);
+      setInitOptions(options);
       const hasReplica = result.read && result.read !== result.write;
       dbLogger4.info(
         hasReplica ? "Database connected (Primary + Replica)" : "Database connected"
       );
       const healthCheckConfig = buildHealthCheckConfig(options?.healthCheck);
       if (healthCheckConfig.enabled) {
-        startHealthCheck(healthCheckConfig, options, getDatabase, closeDatabase);
+        startHealthCheck(healthCheckConfig, options, getDatabase);
       }
       const monConfig = buildMonitoringConfig(options?.monitoring);
       setMonitoringConfig(monConfig);
@@ -754,53 +1003,79 @@ async function initDatabase(options) {
       }
       return { write: getWriteInstance(), read: getReadInstance() };
     } finally {
-      initPromise = null;
+      setInitPromise(void 0);
+      setInitProvider(void 0);
     }
   })();
-  return await initPromise;
+  setInitPromise(currentInit);
+  return await currentInit;
 }
 async function closeDatabase() {
-  if (isClosing) {
+  const activeClosePromise = getClosePromise();
+  if (activeClosePromise) {
     dbLogger4.debug("Database close already in progress");
-    return;
+    return await activeClosePromise;
   }
-  isClosing = true;
-  if (initPromise) {
-    dbLogger4.debug("Waiting for database initialization to complete before closing...");
+  const currentClose = (async () => {
+    setIsClosing(true);
+    const activeInitPromise = getInitPromise();
+    if (activeInitPromise) {
+      dbLogger4.debug("Waiting for database initialization to complete before closing...");
+      try {
+        await activeInitPromise;
+      } catch (_error) {
+        dbLogger4.debug("Initialization failed during close, proceeding with cleanup");
+      }
+    }
+    const writeInst = getWriteInstance();
+    const readInst = getReadInstance();
+    const provider = getDatabaseProvider();
+    if (!writeInst && !readInst && !provider) {
+      dbLogger4.debug("No database connections to close");
+      return;
+    }
     try {
-      await initPromise;
-    } catch (_error) {
-      dbLogger4.debug("Initialization failed during close, proceeding with cleanup");
+      stopHealthCheck();
+      const closePromises = [];
+      if (provider) {
+        closePromises.push(closeDatabaseProvider(provider, "shutdown"));
+      }
+      const writeC = getWriteClient();
+      if (writeC) {
+        closePromises.push(closeDatabaseClient(writeC, "write"));
+      }
+      const readC = getReadClient();
+      if (readC && readC !== writeC) {
+        closePromises.push(closeDatabaseClient(readC, "read"));
+      }
+      await Promise.allSettled(closePromises);
+      dbLogger4.info("All database connections closed");
+    } finally {
+      setWriteInstance(void 0);
+      setReadInstance(void 0);
+      setWriteClient(void 0);
+      setReadClient(void 0);
+      setDatabaseProviderInstance(void 0);
+      setMonitoringConfig(void 0);
+      setInitOptions(void 0);
     }
-  }
-  const writeInst = getWriteInstance();
-  const readInst = getReadInstance();
-  if (!writeInst && !readInst) {
-    dbLogger4.debug("No database connections to close");
-    isClosing = false;
-    return;
-  }
+  })();
+  setClosePromise(currentClose);
   try {
-    stopHealthCheck();
-    const closePromises = [];
-    const writeC = getWriteClient();
-    if (writeC) {
-      closePromises.push(closeDatabaseClient(writeC, "write"));
-    }
-    const readC = getReadClient();
-    if (readC && readC !== writeC) {
-      closePromises.push(closeDatabaseClient(readC, "read"));
-    }
-    await Promise.allSettled(closePromises);
-    dbLogger4.info("All database connections closed");
+    await currentClose;
   } finally {
-    setWriteInstance(void 0);
-    setReadInstance(void 0);
-    setWriteClient(void 0);
-    setReadClient(void 0);
-    setMonitoringConfig(void 0);
-    isClosing = false;
+    if (getClosePromise() === currentClose) {
+      setClosePromise(void 0);
+      setIsClosing(false);
+    }
+  }
+}
+async function forceReconnectDatabase(reason = "manual") {
+  if (getDatabaseProvider()) {
+    dbLogger4.debug("Force reconnect skipped: database is externally provided", { reason });
+    return false;
   }
+  return await triggerForceReconnect(reason);
 }
 function getDatabaseInfo() {
   const writeInst = getWriteInstance();
@@ -808,22 +1083,140 @@ function getDatabaseInfo() {
   return {
     hasWrite: !!writeInst,
     hasRead: !!readInst,
-    isReplica: !!(readInst && readInst !== writeInst)
+    isReplica: !!(readInst && readInst !== writeInst),
+    providerKind: getDatabaseProvider()?.kind
   };
 }
-var INDEX_FILE_PATTERNS = [
+var dbLogger5 = logger.child("@spfn/core:database");
+var POSTGRES_JS_CONNECTION_CODES = /* @__PURE__ */ new Set([
+  "CONNECTION_ENDED",
+  "CONNECTION_CLOSED",
+  "CONNECTION_DESTROYED",
+  "CONNECT_TIMEOUT",
+  "CONNECTION_CONNECT_TIMEOUT"
+]);
+var NODE_NET_ERROR_CODES = /* @__PURE__ */ new Set([
+  "ECONNRESET",
+  "ECONNREFUSED",
+  "EPIPE",
+  "ETIMEDOUT",
+  "EHOSTUNREACH",
+  "ENETUNREACH",
+  "ENOTFOUND"
+]);
+function isConnectionSqlState(code) {
+  if (code.startsWith("08")) return true;
+  if (code === "53300") return true;
+  if (code === "57P01" || code === "57P02" || code === "57P03") return true;
+  return false;
+}
+function* unwrap(error) {
+  const seen = /* @__PURE__ */ new Set();
+  const stack = [error];
+  while (stack.length > 0) {
+    const current = stack.pop();
+    if (!current || typeof current !== "object" || seen.has(current)) {
+      continue;
+    }
+    seen.add(current);
+    const obj = current;
+    yield obj;
+    for (const key of ["cause", "original", "error", "err", "inner"]) {
+      const nested = obj[key];
+      if (nested && typeof nested === "object" && !seen.has(nested)) {
+        stack.push(nested);
+      }
+    }
+  }
+}
+function isConnectionLevelError(error) {
+  if (!error) return false;
+  if (error instanceof ConnectionError) return true;
+  for (const candidate of unwrap(error)) {
+    if (candidate instanceof ConnectionError) return true;
+    const code = candidate.code;
+    if (typeof code === "string") {
+      if (POSTGRES_JS_CONNECTION_CODES.has(code)) return true;
+      if (NODE_NET_ERROR_CODES.has(code)) return true;
+      if (isConnectionSqlState(code)) return true;
+    }
+  }
+  return false;
+}
+var DEFAULT_THRESHOLD = 3;
+var DEFAULT_WINDOW_MS = 1e4;
+var MIN_WINDOW_MS = 1e3;
+function readPositiveIntEnv(key, defaultValue, min) {
+  const raw = process.env[key];
+  if (raw === void 0) return defaultValue;
+  try {
+    return parseNumber(raw, { min, integer: true });
+  } catch {
+    return defaultValue;
+  }
+}
+var ERROR_THRESHOLD = readPositiveIntEnv("DB_RECONNECT_ERROR_THRESHOLD", DEFAULT_THRESHOLD, 1);
+var ERROR_WINDOW_MS = readPositiveIntEnv("DB_RECONNECT_ERROR_WINDOW_MS", DEFAULT_WINDOW_MS, MIN_WINDOW_MS);
+var errorTimestamps = [];
+var reportedErrors = /* @__PURE__ */ new WeakSet();
+function resetConnectionErrorCounter() {
+  errorTimestamps.length = 0;
+}
+function checkAndMarkReported(error) {
+  let alreadySeen = false;
+  const toMark = [];
+  for (const candidate of unwrap(error)) {
+    if (reportedErrors.has(candidate)) {
+      alreadySeen = true;
+    }
+    toMark.push(candidate);
+  }
+  if (alreadySeen) return true;
+  for (const obj of toMark) {
+    reportedErrors.add(obj);
+  }
+  return false;
+}
+function reportDatabaseError(error) {
+  try {
+    if (!isConnectionLevelError(error)) return;
+    if (isReconnectingNow()) return;
+    if (checkAndMarkReported(error)) return;
+    const now = Date.now();
+    errorTimestamps.push(now);
+    const cutoff = now - ERROR_WINDOW_MS;
+    while (errorTimestamps.length > 0 && errorTimestamps[0] < cutoff) {
+      errorTimestamps.shift();
+    }
+    if (errorTimestamps.length < ERROR_THRESHOLD) return;
+    errorTimestamps.length = 0;
+    dbLogger5.error("Connection-error threshold crossed, forcing pool rebuild", {
+      threshold: ERROR_THRESHOLD,
+      windowMs: ERROR_WINDOW_MS
+    });
+    triggerForceReconnect("query_error_threshold").catch((err) => {
+      const message = err instanceof Error ? err.message : String(err);
+      dbLogger5.error("Forced reconnect after error threshold failed", { error: message });
+    });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    dbLogger5.debug("reportDatabaseError itself threw, ignoring", { error: message });
+  }
+}
+var BARREL_FILE_PATTERNS = [
   "/index",
   "/index.ts",
   "/index.js",
   "/index.mjs",
-  "\\index",
-  "\\index.ts",
-  "\\index.js",
-  "\\index.mjs"
+  "/config",
+  "/config.ts",
+  "/config.js",
+  "/config.mjs"
 ];
 var SUPPORTED_EXTENSIONS = [".ts", ".js", ".mjs"];
-function isIndexFile(filePath) {
-  return INDEX_FILE_PATTERNS.some((pattern) => filePath.endsWith(pattern));
+function isBarrelFile(filePath) {
+  const posixPath = toPosixPath(filePath);
+  return BARREL_FILE_PATTERNS.some((pattern) => posixPath.endsWith(pattern));
 }
 function isAbsolutePath(path) {
   if (path.startsWith("/")) return true;
@@ -833,8 +1226,8 @@ function hasSupportedExtension(filePath) {
   if (filePath.endsWith(".d.ts")) return false;
   return SUPPORTED_EXTENSIONS.some((ext) => filePath.endsWith(ext));
 }
-function filterIndexFiles(files) {
-  return files.filter((file) => !isIndexFile(file));
+function filterBarrelFiles(files) {
+  return files.filter((file) => !isBarrelFile(file));
 }
 function scanDirectoryRecursive(dir, extension) {
   const files = [];
@@ -943,7 +1336,7 @@ function discoverPackageSchemas(cwd) {
         for (const schema of packageSchemas) {
           const absolutePath = join(pkgPath, schema);
           const expandedFiles = expandGlobPattern(absolutePath);
-          const schemaFiles = filterIndexFiles(expandedFiles);
+          const schemaFiles = filterBarrelFiles(expandedFiles);
           schemas.push(...schemaFiles);
         }
       }
@@ -993,7 +1386,7 @@ function getDrizzleConfig(options = {}) {
   if (options.packageFilter) {
     const packageSchemas2 = options.disablePackageDiscovery ? [] : discoverPackageSchemas(options.cwd ?? process.cwd());
     const filteredSchemas = packageSchemas2.filter(
-      (schemaPath) => schemaPath.includes(`node_modules/${options.packageFilter}/`)
+      (schemaPath) => toPosixPath(schemaPath).includes(`node_modules/${options.packageFilter}/`)
     );
     if (filteredSchemas.length === 0) {
       throw new Error(
@@ -1005,7 +1398,10 @@ function getDrizzleConfig(options = {}) {
       schema: schema2,
       out,
       dialect,
-      dbCredentials: getDbCredentials(dialect, databaseUrl)
+      dbCredentials: getDbCredentials(dialect, databaseUrl),
+      migrations: {
+        prefix: options.migrationPrefix ?? "timestamp"
+      }
     };
   }
   const userSchema = options.schema ?? "./src/server/entities/**/*.ts";
@@ -1018,7 +1414,7 @@ function getDrizzleConfig(options = {}) {
     for (const schema2 of allSchemas) {
       const absoluteSchema = isAbsolutePath(schema2) ? schema2 : join(cwd, schema2);
       const expanded = expandGlobPattern(absoluteSchema);
-      const filtered = filterIndexFiles(expanded);
+      const filtered = filterBarrelFiles(expanded);
       expandedFiles.push(...filtered);
     }
     allSchemas = expandedFiles;
@@ -1037,7 +1433,10 @@ function getDrizzleConfig(options = {}) {
     out,
     dialect,
     dbCredentials: getDbCredentials(dialect, databaseUrl),
-    schemaFilter
+    schemaFilter,
+    migrations: {
+      prefix: options.migrationPrefix ?? "timestamp"
+    }
   };
 }
 function getDbCredentials(dialect, url) {
@@ -1066,13 +1465,15 @@ function generateDrizzleConfigFile(options = {}) {
     ]` : `'${normalizeSchemaPath(config.schema)}'`;
   const schemaFilterLine = config.schemaFilter && config.schemaFilter.length > 0 ? `
     schemaFilter: ${JSON.stringify(config.schemaFilter)},` : "";
+  const migrationsLine = config.migrations ? `
+    migrations: ${JSON.stringify(config.migrations)},` : "";
   return `import { defineConfig } from 'drizzle-kit';
 
 export default defineConfig({
     schema: ${schemaValue},
     out: '${config.out}',
     dialect: '${config.dialect}',
-    dbCredentials: ${JSON.stringify(config.dbCredentials, null, 4)},${schemaFilterLine}
+    dbCredentials: ${JSON.stringify(config.dbCredentials, null, 4)},${schemaFilterLine}${migrationsLine}
 });
 `;
 }
@@ -1082,14 +1483,14 @@ function id() {
 function timestamps() {
   return {
     createdAt: timestamp("created_at", { withTimezone: true, mode: "date" }).defaultNow().notNull(),
-    updatedAt: timestamp("updated_at", { withTimezone: true, mode: "date" }).defaultNow().notNull()
+    updatedAt: timestamp("updated_at", { withTimezone: true, mode: "date" }).defaultNow().notNull().$onUpdate(() => sql`now()`)
   };
 }
 function foreignKey(name, reference, options) {
-  return bigserial(`${name}_id`, { mode: "number" }).notNull().references(reference, { onDelete: options?.onDelete ?? "cascade" });
+  return bigint(`${name}_id`, { mode: "number" }).notNull().references(reference, { onDelete: options?.onDelete ?? "cascade" });
 }
 function optionalForeignKey(name, reference, options) {
-  return bigserial(`${name}_id`, { mode: "number" }).references(reference, { onDelete: options?.onDelete ?? "set null" });
+  return bigint(`${name}_id`, { mode: "number" }).references(reference, { onDelete: options?.onDelete ?? "set null" });
 }
 function uuid() {
   return uuid$1("id").defaultRandom().primaryKey();
@@ -1147,6 +1548,200 @@ function getSchemaInfo(packageName) {
     scope
   };
 }
+var discoveryLogger = logger.child("@spfn/core:migrations");
+function functionMigrationsTable(packageName) {
+  return `__spfn_fn_${packageName.replace("@spfn/", "")}_migrations`;
+}
+function discoverFunctionMigrations(cwd = process.cwd()) {
+  const spfnDir = join(cwd, "node_modules", "@spfn");
+  if (!existsSync(spfnDir)) {
+    return [];
+  }
+  const functions = [];
+  for (const pkg of readdirSync(spfnDir)) {
+    const packagePath = join(spfnDir, pkg);
+    const packageJsonPath = join(packagePath, "package.json");
+    if (!existsSync(packageJsonPath)) {
+      continue;
+    }
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+      const migrationsConfig = packageJson.spfn?.migrations;
+      if (!migrationsConfig) {
+        continue;
+      }
+      const migrationsDir = join(packagePath, migrationsConfig.dir);
+      if (!existsSync(migrationsDir)) {
+        discoveryLogger.warn(
+          `@spfn/${pkg} declares migrations but the directory is missing: ${migrationsDir}`
+        );
+        continue;
+      }
+      functions.push({ packageName: `@spfn/${pkg}`, migrationsDir, packagePath });
+    } catch {
+      discoveryLogger.warn(`Failed to parse package.json for @spfn/${pkg}`);
+    }
+  }
+  return functions;
+}
+function readMigrationEntries(migrationsDir, packageName) {
+  const journalPath = join(migrationsDir, "meta", "_journal.json");
+  return existsSync(journalPath) ? readJournalEntries(migrationsDir, journalPath, packageName) : readFolderEntries(migrationsDir, packageName);
+}
+function readJournalEntries(migrationsDir, journalPath, packageName) {
+  let journal;
+  try {
+    journal = JSON.parse(readFileSync(journalPath, "utf-8"));
+  } catch {
+    journal = {};
+  }
+  if (!Array.isArray(journal.entries)) {
+    throw new Error(`${packageName}: invalid migration journal at ${journalPath}`);
+  }
+  const entries = [...journal.entries];
+  entries.sort((a, b) => a.idx - b.idx);
+  return entries.map((entry) => {
+    if (typeof entry?.tag !== "string" || typeof entry?.when !== "number") {
+      throw new Error(`${packageName}: invalid journal entry in ${journalPath}`);
+    }
+    const sqlPath = join(migrationsDir, `${entry.tag}.sql`);
+    if (!existsSync(sqlPath)) {
+      throw new Error(`${packageName}: migration file not found: ${entry.tag}.sql`);
+    }
+    return toEntry(entry.tag, readFileSync(sqlPath, "utf-8"), entry.when);
+  });
+}
+function readFolderEntries(migrationsDir, packageName) {
+  const folders = readdirSync(migrationsDir, { withFileTypes: true }).filter((dirent) => dirent.isDirectory()).map((dirent) => dirent.name).filter((name) => existsSync(join(migrationsDir, name, "migration.sql"))).sort((a, b) => a.localeCompare(b));
+  return folders.map((name) => toEntry(
+    name,
+    readFileSync(join(migrationsDir, name, "migration.sql"), "utf-8"),
+    folderTimestampMillis(name, packageName)
+  ));
+}
+function folderTimestampMillis(name, packageName) {
+  const match = /^(\d{4})(\d{2})(\d{2})(\d{2})(\d{2})(\d{2})/.exec(name);
+  if (!match) {
+    throw new Error(`${packageName}: migration folder name must start with a YYYYMMDDHHMMSS timestamp: ${name}`);
+  }
+  const [, year, month, day, hour, minute, second] = match;
+  return Date.UTC(
+    Number(year),
+    Number(month) - 1,
+    Number(day),
+    Number(hour),
+    Number(minute),
+    Number(second)
+  );
+}
+function toEntry(name, content, millis) {
+  return {
+    name,
+    millis,
+    hash: createHash("sha256").update(content).digest("hex"),
+    statements: content.split("--> statement-breakpoint").map((statement) => statement.trim()).filter((statement) => statement.length > 0)
+  };
+}
+var PROJECT_MIGRATIONS_TABLE = "__drizzle_migrations";
+var PROJECT_TARGET_NAME = "project (src/server/drizzle)";
+function filterPendingEntries(entries, lastAppliedMillis, appliedNames) {
+  return entries.filter((entry) => entry.millis > lastAppliedMillis && !appliedNames.has(entry.name));
+}
+function migrationTargets(status) {
+  return [...status.packages, ...status.project ? [status.project] : []];
+}
+function pendingMigrationTargets(status) {
+  return migrationTargets(status).filter((target) => target.pending > 0);
+}
+function countPendingMigrations(status) {
+  return migrationTargets(status).reduce((sum, target) => sum + target.pending, 0);
+}
+function toRows(result) {
+  if (Array.isArray(result)) {
+    return result;
+  }
+  const rows = result?.rows;
+  return Array.isArray(rows) ? rows : [];
+}
+async function tableExists(db, tableName) {
+  const rows = toRows(await db.execute(sql`
+        SELECT EXISTS (
+            SELECT 1 FROM information_schema.tables
+            WHERE table_schema = 'drizzle' AND table_name = ${tableName}
+        ) AS "exists"`));
+  return rows[0]?.exists === true;
+}
+async function readAppliedNames(db, tableName) {
+  const columnRows = toRows(await db.execute(sql`
+        SELECT EXISTS (
+            SELECT 1 FROM information_schema.columns
+            WHERE table_schema = 'drizzle' AND table_name = ${tableName} AND column_name = 'name'
+        ) AS "exists"`));
+  if (columnRows[0]?.exists !== true) {
+    return /* @__PURE__ */ new Set();
+  }
+  const rows = toRows(await db.execute(sql`
+        SELECT name FROM drizzle.${sql.identifier(tableName)} WHERE name IS NOT NULL`));
+  return new Set(rows.map((row) => String(row.name)));
+}
+async function collectTargetStatus(db, name, migrationsDir, tableName) {
+  const entries = readMigrationEntries(migrationsDir, name);
+  let lastApplied = 0;
+  let appliedNames = /* @__PURE__ */ new Set();
+  if (await tableExists(db, tableName)) {
+    const rows = toRows(await db.execute(sql`
+            SELECT created_at FROM drizzle.${sql.identifier(tableName)}
+            ORDER BY created_at DESC LIMIT 1`));
+    lastApplied = rows[0]?.created_at ? Number(rows[0].created_at) : 0;
+    appliedNames = await readAppliedNames(db, tableName);
+  }
+  const pendingEntries = filterPendingEntries(entries, lastApplied, appliedNames);
+  return {
+    name,
+    total: entries.length,
+    applied: entries.length - pendingEntries.length,
+    pending: pendingEntries.length,
+    pendingTags: pendingEntries.map((entry) => entry.name)
+  };
+}
+function hasMigrationTargets(cwd = process.cwd()) {
+  return discoverFunctionMigrations(cwd).length > 0 || existsSync(projectMigrationsDir(cwd));
+}
+function projectMigrationsDir(cwd = process.cwd()) {
+  return join(cwd, "src", "server", "drizzle");
+}
+async function collectMigrationStatus(db, cwd = process.cwd()) {
+  const packages = [];
+  for (const func of discoverFunctionMigrations(cwd)) {
+    packages.push(await collectTargetStatus(
+      db,
+      func.packageName,
+      func.migrationsDir,
+      functionMigrationsTable(func.packageName)
+    ));
+  }
+  const projectDir = projectMigrationsDir(cwd);
+  const project = existsSync(projectDir) ? await collectTargetStatus(db, PROJECT_TARGET_NAME, projectDir, PROJECT_MIGRATIONS_TABLE) : null;
+  return { packages, project: project && project.total > 0 ? project : null };
+}
+
+// src/db/migrations/format.ts
+var RUN_MIGRATIONS_HINT = "Run: pnpm spfn db migrate";
+function formatPendingMigrations(targets) {
+  const lines = [];
+  for (const target of targets) {
+    lines.push(`${target.name}: ${target.pending} pending migration(s) (${target.applied}/${target.total} applied)`);
+    for (const tag of target.pendingTags) {
+      lines.push(`    - ${tag}`);
+    }
+  }
+  return lines;
+}
+function pendingMigrationsSummary(targets) {
+  const pending = targets.reduce((sum, target) => sum + target.pending, 0);
+  const names = targets.map((target) => target.name).join(", ");
+  return `${pending} pending migration(s) in ${names}`;
+}
 var txLogger = logger.child("@spfn/core:transaction");
 var asyncContext = new AsyncLocalStorage();
 function getTransactionContext() {
@@ -1168,7 +1763,23 @@ function runWithTransaction(tx, txId, callback) {
   } else {
     txLogger.debug("Root transaction context set", { txId, level: newLevel });
   }
-  return asyncContext.run({ tx, txId, level: newLevel }, callback);
+  const afterCommitCallbacks = existingContext ? existingContext.afterCommitCallbacks : [];
+  return asyncContext.run(
+    { tx, txId, level: newLevel, afterCommitCallbacks },
+    callback
+  );
+}
+function onAfterCommit(callback) {
+  const context = getTransactionContext();
+  if (!context) {
+    Promise.resolve().then(callback).catch((err) => {
+      txLogger.error("afterCommit callback failed (no transaction)", {
+        error: err instanceof Error ? err.message : String(err)
+      });
+    });
+    return;
+  }
+  context.afterCommitCallbacks.push(callback);
 }
 var MAX_TIMEOUT_MS = 2147483647;
 var txLogger2 = logger.child("@spfn/core:transaction");
@@ -1180,6 +1791,7 @@ async function runInTransaction(callback, options = {}) {
     context = "transaction"
   } = options;
   const timeout = options.timeout ?? defaultTimeout;
+  const idleTimeout = options.idleTimeout ?? env.TRANSACTION_IDLE_TIMEOUT;
   const txId = `tx_${randomUUID()}`;
   const validateAndThrow = (condition, message, logMessage, metadata) => {
     if (condition) {
@@ -1220,6 +1832,24 @@ async function runInTransaction(callback, options = {}) {
     "Timeout exceeds maximum",
     { txId, context, timeout, maxTimeout: MAX_TIMEOUT_MS }
   );
+  validateAndThrow(
+    !Number.isInteger(idleTimeout),
+    `Invalid idleTimeout value: ${idleTimeout}. Must be an integer.`,
+    "Invalid idleTimeout type",
+    { txId, context, idleTimeout }
+  );
+  validateAndThrow(
+    idleTimeout < 0,
+    `Invalid idleTimeout value: ${idleTimeout}. Must be non-negative (0 to disable).`,
+    "Invalid idleTimeout range",
+    { txId, context, idleTimeout }
+  );
+  validateAndThrow(
+    idleTimeout > MAX_TIMEOUT_MS,
+    `Invalid idleTimeout value: ${idleTimeout}. Maximum is ${MAX_TIMEOUT_MS}ms.`,
+    "idleTimeout exceeds maximum",
+    { txId, context, idleTimeout, maxTimeout: MAX_TIMEOUT_MS }
+  );
   const writeDb = getDatabase("write");
   if (!writeDb) {
     const error = new TransactionError({
@@ -1251,13 +1881,25 @@ async function runInTransaction(callback, options = {}) {
     txLogger2.debug("Transaction started", { txId, context });
   }
   const startTime = Date.now();
+  let afterCommitCallbacks = [];
   try {
     const result = await writeDb.transaction(async (tx) => {
+      const transaction = tx;
       if (timeout > 0 && !isNested) {
-        await tx.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
+        await transaction.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
+      }
+      if (idleTimeout > 0 && !isNested) {
+        await transaction.execute(sql.raw(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeout}`));
       }
-      return await runWithTransaction(tx, txId, async () => {
-        return await callback(tx);
+      return await runWithTransaction(transaction, txId, async () => {
+        const innerResult = await callback(transaction);
+        if (!isNested) {
+          const ctx = getTransactionContext();
+          if (ctx) {
+            afterCommitCallbacks = [...ctx.afterCommitCallbacks];
+          }
+        }
+        return innerResult;
       });
     });
     const duration = Date.now() - startTime;
@@ -1267,7 +1909,8 @@ async function runInTransaction(callback, options = {}) {
           txId,
           context,
           duration: `${duration}ms`,
-          threshold: `${slowThreshold}ms`
+          threshold: `${slowThreshold}ms`,
+          hint: "A transaction holds a pooled connection (and row locks) for its whole duration. If this is slow because of non-DB work (external API, etc.) inside the transaction, move that work out \u2014 it starves the connection pool."
         });
       } else {
         txLogger2.debug("Transaction committed", {
@@ -1277,6 +1920,24 @@ async function runInTransaction(callback, options = {}) {
         });
       }
     }
+    if (!isNested && afterCommitCallbacks.length > 0) {
+      if (enableLogging) {
+        txLogger2.debug("Executing afterCommit callbacks", {
+          txId,
+          context,
+          count: afterCommitCallbacks.length
+        });
+      }
+      for (const cb of afterCommitCallbacks) {
+        Promise.resolve().then(cb).catch((err) => {
+          txLogger2.error("afterCommit callback failed", {
+            txId,
+            context,
+            error: err instanceof Error ? err.message : String(err)
+          });
+        });
+      }
+    }
     return result;
   } catch (error) {
     const duration = Date.now() - startTime;
@@ -1288,7 +1949,8 @@ async function runInTransaction(callback, options = {}) {
           duration: `${duration}ms`,
           threshold: `${slowThreshold}ms`,
           error: error instanceof Error ? error.message : String(error),
-          errorType: error instanceof Error ? error.name : "Unknown"
+          errorType: error instanceof Error ? error.name : "Unknown",
+          hint: "If the error is an idle-in-transaction timeout, the transaction held a pooled connection while awaiting non-DB work (external API, etc.). Move that work out of the transaction."
         });
       } else {
         txLogger2.error("Transaction rolled back", {
@@ -1323,6 +1985,7 @@ function Transactional(options = {}) {
         }
       );
     } catch (error) {
+      reportDatabaseError(error);
       if (error instanceof DatabaseError) {
         throw error;
       }
@@ -1392,7 +2055,8 @@ async function create(table, data) {
   if (!db) {
     throw new Error("Database not initialized. Call initDatabase() first.");
   }
-  const [result] = await db.insert(table).values(data).returning();
+  const results = await db.insert(table).values(data).returning();
+  const result = results[0];
   return result;
 }
 async function createMany(table, data) {
@@ -1408,10 +2072,11 @@ async function upsert(table, data, options) {
   if (!db) {
     throw new Error("Database not initialized. Call initDatabase() first.");
   }
-  const [result] = await db.insert(table).values(data).onConflictDoUpdate({
+  const results = await db.insert(table).values(data).onConflictDoUpdate({
     target: options.target,
     set: options.set || data
   }).returning();
+  const result = results[0];
   return result;
 }
 async function updateOne(table, where, data) {
@@ -1423,7 +2088,8 @@ async function updateOne(table, where, data) {
   if (!whereClause) {
     throw new Error("updateOne requires at least one where condition");
   }
-  const [result] = await db.update(table).set(data).where(whereClause).returning();
+  const results = await db.update(table).set(data).where(whereClause).returning();
+  const result = results[0];
   return result ?? null;
 }
 async function updateMany(table, where, data) {
@@ -1447,7 +2113,8 @@ async function deleteOne(table, where) {
   if (!whereClause) {
     throw new Error("deleteOne requires at least one where condition");
   }
-  const [result] = await db.delete(table).where(whereClause).returning();
+  const results = await db.delete(table).where(whereClause).returning();
+  const result = results[0];
   return result ?? null;
 }
 async function deleteMany(table, where) {
@@ -1570,6 +2237,7 @@ var BaseRepository = class {
     try {
       return await queryFn();
     } catch (error) {
+      reportDatabaseError(error);
       const err = error instanceof Error ? error : new Error(String(error));
       const repositoryName = this.constructor.name;
       throw new RepositoryError(
@@ -1636,14 +2304,51 @@ var BaseRepository = class {
       const orderByArray = Array.isArray(options.orderBy) ? options.orderBy : [options.orderBy];
       query = query.orderBy(...orderByArray);
     }
-    if (options?.limit) {
-      query = query.limit(options.limit);
+    const maxRows = env.DB_MAX_ROWS;
+    const requestedLimit = options?.limit && options.limit > 0 ? options.limit : void 0;
+    const effectiveLimit = maxRows > 0 ? Math.min(requestedLimit ?? maxRows, maxRows) : requestedLimit;
+    if (effectiveLimit) {
+      query = query.limit(effectiveLimit);
     }
     if (options?.offset) {
       query = query.offset(options.offset);
     }
     return query;
   }
+  /**
+   * Keyset (cursor) pagination — O(limit) instead of OFFSET's O(offset).
+   *
+   * Pages by a strictly-ordered, unique column instead of a numeric offset, so a
+   * deep page doesn't scan and discard everything before it. Pass the cursor
+   * column's value from the last row of the previous page as `after`; omit it for
+   * the first page. The column must be unique and the sole sort key (e.g. an
+   * auto-increment id or a ULID).
+   *
+   * @example
+   * ```typescript
+   * const page1 = await this._findManyKeyset(users, { cursorColumn: users.id, limit: 20 });
+   * const page2 = await this._findManyKeyset(users, {
+   *     cursorColumn: users.id,
+   *     after: page1.at(-1)?.id,
+   *     limit: 20,
+   * });
+   * ```
+   */
+  async _findManyKeyset(table, options) {
+    const { cursorColumn, after, order = "asc", where } = options;
+    const maxRows = env.DB_MAX_ROWS;
+    const limit = maxRows > 0 ? Math.min(options.limit, maxRows) : options.limit;
+    const baseWhere = where ? isSQLWrapper(where) ? where : buildWhereFromObject(table, where) : void 0;
+    const cursorPredicate = after !== void 0 ? order === "desc" ? lt(cursorColumn, after) : gt(cursorColumn, after) : void 0;
+    const whereClause = baseWhere && cursorPredicate ? and(baseWhere, cursorPredicate) : cursorPredicate ?? baseWhere;
+    let query = this.readDb.select().from(table);
+    if (whereClause) {
+      query = query.where(whereClause);
+    }
+    query = query.orderBy(order === "desc" ? desc(cursorColumn) : asc(cursorColumn));
+    query = query.limit(limit);
+    return query;
+  }
   /**
    * Create a new record
    *
@@ -1660,7 +2365,8 @@ var BaseRepository = class {
    * ```
    */
   async _create(table, data) {
-    const [result] = await this.db.insert(table).values(data).returning();
+    const results = await this.db.insert(table).values(data).returning();
+    const result = results[0];
     return result;
   }
   /**
@@ -1697,15 +2403,16 @@ var BaseRepository = class {
    *     value: {...}
    * }, {
    *     target: [cache.key],
-   *     set: { value: data.value, updatedAt: new Date() }
+   *     set: { value: data.value } // updatedAt is stamped by the database
    * });
    * ```
    */
   async _upsert(table, data, options) {
-    const [result] = await this.db.insert(table).values(data).onConflictDoUpdate({
+    const results = await this.db.insert(table).values(data).onConflictDoUpdate({
       target: options.target,
       set: options.set || data
     }).returning();
+    const result = results[0];
     return result;
   }
   /**
@@ -1729,7 +2436,8 @@ var BaseRepository = class {
     if (!whereClause) {
       throw new Error("updateOne requires at least one where condition");
     }
-    const [result] = await this.db.update(table).set(data).where(whereClause).returning();
+    const results = await this.db.update(table).set(data).where(whereClause).returning();
+    const result = results[0];
     return result ?? null;
   }
   /**
@@ -1773,7 +2481,8 @@ var BaseRepository = class {
     if (!whereClause) {
       throw new Error("deleteOne requires at least one where condition");
     }
-    const [result] = await this.db.delete(table).where(whereClause).returning();
+    const results = await this.db.delete(table).where(whereClause).returning();
+    const result = results[0];
     return result ?? null;
   }
   /**
@@ -1822,6 +2531,6 @@ var BaseRepository = class {
   }
 };
 
-export { BaseRepository, RepositoryError, Transactional, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, optionalForeignKey, packageNameToSchema, publishingFields, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { BaseRepository, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, RUN_MIGRATIONS_HINT, RepositoryError, Transactional, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map