@spfn/core 0.2.0-beta.6 → 0.2.0-beta.64

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 { join, dirname, basename } from 'path';
-import { bigserial, timestamp, uuid as uuid$1, text, jsonb, pgSchema } from 'drizzle-orm/pg-core';
+import { bigserial, timestamp, bigint, uuid as uuid$1, text, jsonb, pgSchema } from 'drizzle-orm/pg-core';
 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';
+import { sql, count as count$1, lt, gt, and, desc, asc, eq } 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,8 +437,9 @@ 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),
@@ -502,7 +543,20 @@ 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 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 +568,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 +587,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 +624,77 @@ 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 (!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 (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 +703,7 @@ function stopHealthCheck() {
     setHealthCheckInterval(void 0);
     dbLogger3.info("Database health check stopped");
   }
+  isReconnecting = false;
 }
 
 // src/db/manager/manager.ts
@@ -604,7 +715,6 @@ var STACK_TRACE_PATTERNS = {
   withoutParens: /at (.+):(\d+):(\d+)/
 };
 var initPromise = null;
-var isClosing = false;
 async function cleanupDatabaseConnections(writeClient, readClient) {
   const cleanupPromises = [];
   if (writeClient) {
@@ -705,7 +815,7 @@ function setDatabase(write, read) {
   setReadInstance(read ?? write);
 }
 async function initDatabase(options) {
-  if (isClosing) {
+  if (getIsClosing()) {
     throw new Error("Cannot initialize database while closing");
   }
   const writeInst = getWriteInstance();
@@ -727,7 +837,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 +846,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);
@@ -760,11 +871,11 @@ async function initDatabase(options) {
   return await initPromise;
 }
 async function closeDatabase() {
-  if (isClosing) {
+  if (getIsClosing()) {
     dbLogger4.debug("Database close already in progress");
     return;
   }
-  isClosing = true;
+  setIsClosing(true);
   if (initPromise) {
     dbLogger4.debug("Waiting for database initialization to complete before closing...");
     try {
@@ -777,7 +888,7 @@ async function closeDatabase() {
   const readInst = getReadInstance();
   if (!writeInst && !readInst) {
     dbLogger4.debug("No database connections to close");
-    isClosing = false;
+    setIsClosing(false);
     return;
   }
   try {
@@ -799,9 +910,13 @@ async function closeDatabase() {
     setWriteClient(void 0);
     setReadClient(void 0);
     setMonitoringConfig(void 0);
-    isClosing = false;
+    setInitOptions(void 0);
+    setIsClosing(false);
   }
 }
+async function forceReconnectDatabase(reason = "manual") {
+  return await triggerForceReconnect(reason);
+}
 function getDatabaseInfo() {
   const writeInst = getWriteInstance();
   const readInst = getReadInstance();
@@ -811,7 +926,123 @@ function getDatabaseInfo() {
     isReplica: !!(readInst && readInst !== writeInst)
   };
 }
-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",
@@ -819,11 +1050,14 @@ var INDEX_FILE_PATTERNS = [
   "\\index",
   "\\index.ts",
   "\\index.js",
-  "\\index.mjs"
+  "\\index.mjs",
+  "\\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) {
+  return BARREL_FILE_PATTERNS.some((pattern) => filePath.endsWith(pattern));
 }
 function isAbsolutePath(path) {
   if (path.startsWith("/")) return true;
@@ -833,8 +1067,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 +1177,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);
         }
       }
@@ -1005,7 +1239,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 +1255,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 +1274,10 @@ function getDrizzleConfig(options = {}) {
     out,
     dialect,
     dbCredentials: getDbCredentials(dialect, databaseUrl),
-    schemaFilter
+    schemaFilter,
+    migrations: {
+      prefix: options.migrationPrefix ?? "timestamp"
+    }
   };
 }
 function getDbCredentials(dialect, url) {
@@ -1066,13 +1306,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}
 });
 `;
 }
@@ -1086,10 +1328,10 @@ function timestamps() {
   };
 }
 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();
@@ -1168,7 +1410,20 @@ 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 +1435,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 +1476,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 +1525,24 @@ 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) => {
       if (timeout > 0 && !isNested) {
         await tx.execute(sql.raw(`SET LOCAL statement_timeout = ${timeout}`));
       }
+      if (idleTimeout > 0 && !isNested) {
+        await tx.execute(sql.raw(`SET LOCAL idle_in_transaction_session_timeout = ${idleTimeout}`));
+      }
       return await runWithTransaction(tx, txId, async () => {
-        return await callback(tx);
+        const innerResult = await callback(tx);
+        if (!isNested) {
+          const ctx = getTransactionContext();
+          if (ctx) {
+            afterCommitCallbacks = [...ctx.afterCommitCallbacks];
+          }
+        }
+        return innerResult;
       });
     });
     const duration = Date.now() - startTime;
@@ -1267,7 +1552,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 +1563,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 +1592,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 +1628,7 @@ function Transactional(options = {}) {
         }
       );
     } catch (error) {
+      reportDatabaseError(error);
       if (error instanceof DatabaseError) {
         throw error;
       }
@@ -1570,6 +1876,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 +1943,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
    *
@@ -1822,6 +2166,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, RepositoryError, Transactional, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, forceReconnectDatabase, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, id, initDatabase, isConnectionLevelError, onAfterCommit, optionalForeignKey, packageNameToSchema, publishingFields, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map