@podosoft/podokit 1.2.0 → 1.4.0

package/dist/templates/modules/audit-log/files/apps/api/src/audit/audit.migration.spec.ts

@@ -5,16 +5,24 @@ import { revertLatestSqliteMigration, runSqliteMigrations } from "../database/sq
 import { InitAuditLogs1720300000000 } from "../migrations/1720300000000-InitAuditLogs";
 import { IndexAuditLogFilters1792000000000 } from "../migrations/1792000000000-IndexAuditLogFilters";
 
-function runner(type: "postgres" | "better-sqlite3", queries: string[]): QueryRunner {
+function runner(
+  type: "postgres" | "better-sqlite3",
+  queries: string[],
+  invalidIndexes: string[] = [],
+): QueryRunner {
   return {
     connection: { options: { type } },
-    query: (sql: string): Promise<unknown[]> => {
+    query: (sql: string, parameters: unknown[] = []): Promise<unknown[]> => {
       queries.push(sql);
-      return Promise.resolve([]);
+      const invalid = sql.includes("indisvalid") && invalidIndexes.some((name) => parameters[0] === `"${name}"`);
+      return Promise.resolve(invalid ? [{ invalid: 1 }] : []);
     },
   } as unknown as QueryRunner;
 }
 
+const INVALID_CHECK =
+  "SELECT 1 AS \"invalid\" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid";
+
 const FILTER_INDEXES = [
   "IDX_audit_logs_action_createdAt",
   "IDX_audit_logs_actorEmail_createdAt",
@@ -61,20 +69,41 @@ describe("audit log migration", () => {
 });
 
 describe("audit filter index migration", () => {
-  it("replaces the single-column indexes on PostgreSQL and restores them on revert", async () => {
+  it("builds and drops the PostgreSQL indexes concurrently outside a transaction", async () => {
     const migration = new IndexAuditLogFilters1792000000000();
+    // A transaction block would reject CONCURRENTLY; the runner must use "each".
+    expect(migration.transaction).toBe(false);
     const up: string[] = [];
     await migration.up(runner("postgres", up));
     expect(up).toEqual([
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
-      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
-      'DROP INDEX IF EXISTS "IDX_audit_logs_action"',
-      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt"',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      INVALID_CHECK,
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_createdAt"',
     ]);
-    expect(up.join("\n")).not.toContain("CONCURRENTLY");
+  });
+
+  it("rebuilds an invalid index left by an interrupted concurrent build", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(
+      runner("postgres", up, ["IDX_audit_logs_action_createdAt"]),
+    );
+    const drop = up.indexOf('DROP INDEX CONCURRENTLY IF EXISTS "IDX_audit_logs_action_createdAt"');
+    expect(drop).toBeGreaterThan(-1);
+    expect(up[drop + 1]).toBe(
+      'CREATE INDEX CONCURRENTLY IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+    );
+    expect(up.filter((sql) => sql.startsWith("DROP INDEX CONCURRENTLY"))).toHaveLength(3);
+  });
 
+  it("restores the single-column PostgreSQL indexes on revert inside its transaction", async () => {
+    const migration = new IndexAuditLogFilters1792000000000();
     const down: string[] = [];
     await migration.down(runner("postgres", down));
     expect(down).toEqual([
@@ -87,6 +116,19 @@ describe("audit filter index migration", () => {
     ]);
   });
 
+  it("keeps plain index statements on SQLite", async () => {
+    const up: string[] = [];
+    await new IndexAuditLogFilters1792000000000().up(runner("better-sqlite3", up));
+    expect(up).toEqual([
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_createdAt_id" ON "audit_logs" ("createdAt", "id")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_action_createdAt" ON "audit_logs" ("action", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_actorEmail_createdAt" ON "audit_logs" ("actorEmail", "createdAt")',
+      'CREATE INDEX IF NOT EXISTS "IDX_audit_logs_targetLabel_createdAt" ON "audit_logs" ("targetLabel", "createdAt")',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_action"',
+      'DROP INDEX IF EXISTS "IDX_audit_logs_createdAt"',
+    ]);
+  });
+
   it("migrates up and down on SQLite", async () => {
     const database = new Database(":memory:");
     const migrations = [

package/dist/templates/modules/audit-log/files/apps/api/src/migrations/1792000000000-IndexAuditLogFilters.ts

@@ -2,8 +2,8 @@ import type { MigrationInterface, QueryRunner } from "typeorm";
 
 // Indexes for the keyset list: ("createdAt", "id") serves the unfiltered pages and
 // the retention prune, and each filter gets its column followed by "createdAt".
-// IF NOT EXISTS lets an operator build them beforehand with CREATE INDEX
-// CONCURRENTLY on a large PostgreSQL table; migrations run in one transaction.
+// PostgreSQL builds and drops them concurrently so audit writes continue on a
+// large table. IF NOT EXISTS keeps indexes an operator already built.
 const INDEXES: Array<[name: string, columns: string]> = [
   ["IDX_audit_logs_createdAt_id", `"createdAt", "id"`],
   ["IDX_audit_logs_action_createdAt", `"action", "createdAt"`],
@@ -18,14 +18,36 @@ const REPLACED: Array<[name: string, columns: string]> = [
 
 export class IndexAuditLogFilters1792000000000 implements MigrationInterface {
   name = "IndexAuditLogFilters1792000000000";
+  // CONCURRENTLY cannot run inside a transaction block. The runner therefore
+  // uses the "each" transaction mode. SQLite migrations always use one.
+  transaction = false;
 
   async up(queryRunner: QueryRunner): Promise<void> {
+    if (queryRunner.connection.options.type !== "postgres") {
+      for (const [name, columns] of INDEXES) {
+        await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+      }
+      for (const [name] of REPLACED) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
+      return;
+    }
     for (const [name, columns] of INDEXES) {
-      await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);
+      // An interrupted concurrent build leaves an invalid index that
+      // IF NOT EXISTS would keep, so drop it and build again.
+      const invalid = await queryRunner.query(
+        `SELECT 1 AS "invalid" FROM pg_index WHERE indexrelid = to_regclass($1) AND NOT indisvalid`,
+        [`"${name}"`],
+      ) as unknown[];
+      if (invalid.length > 0) await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${name}"`);
+      await queryRunner.query(
+        `CREATE INDEX CONCURRENTLY IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`,
+      );
+    }
+    for (const [name] of REPLACED) {
+      await queryRunner.query(`DROP INDEX CONCURRENTLY IF EXISTS "${name}"`);
     }
-    for (const [name] of REPLACED) await queryRunner.query(`DROP INDEX IF EXISTS "${name}"`);
   }
 
+  // A revert runs inside a transaction, so it uses plain statements.
   async down(queryRunner: QueryRunner): Promise<void> {
     for (const [name, columns] of REPLACED) {
       await queryRunner.query(`CREATE INDEX IF NOT EXISTS "${name}" ON "audit_logs" (${columns})`);

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.spec.ts

@@ -0,0 +1,26 @@
+import type { SQL } from "bun";
+import { describe, expect, it } from "bun:test";
+import { validateEnv } from "../config/env.validation";
+import { refreshForRequest } from "./auth-provider";
+import { configureAuthQueryDatabase } from "./db";
+
+describe("refreshForRequest", () => {
+  it("stops waiting for a configuration refresh the database does not answer", async () => {
+    let queries = 0;
+    // Every query waits forever, like one on a paused server.
+    const silent = (): Promise<never> => {
+      queries += 1;
+      return new Promise(() => undefined);
+    };
+    configureAuthQueryDatabase(silent as unknown as SQL);
+
+    const waitMs = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
+    const started = Date.now();
+    await refreshForRequest();
+    const waited = Date.now() - started;
+
+    expect(queries).toBeGreaterThan(0);
+    expect(waited).toBeGreaterThanOrEqual(waitMs - 10);
+    expect(waited).toBeLessThan(waitMs + 500);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/auth-provider.ts

@@ -1,7 +1,12 @@
 import type { AuthConfig } from "@podosoft/podokit-auth";
+import { validateEnv } from "../config/env.validation";
 import { auth as bootstrapAuth, buildAuth } from "./auth";
 import { authConfigStore } from "./auth-config-store";
 import { publishConfigChanged } from "./config-events";
+import { answersWithin, checkAuthResponse } from "./database-outage";
+import { authDatabaseReachable } from "./db";
+
+const REFRESH_WAIT_MS = validateEnv(process.env).READINESS_CHECK_TIMEOUT_MS;
 
 // Runtime auth instance that rebuilds when the DB config changes, so admin edits
 // (OAuth credentials, SMTP, server-enforced toggles) apply WITHOUT a restart.
@@ -52,10 +57,20 @@ export async function refreshAuthNow(): Promise<void> {
   await publishConfigChanged();
 }
 
+/**
+ * Refreshes before a request is served. While PostgreSQL does not answer, the
+ * refresh lasts as long as a query may wait, and the request would wait for
+ * Better Auth's own queries after it. Past the readiness check timeout the
+ * current instance serves the request, and the refresh finishes in the background.
+ */
+export async function refreshForRequest(): Promise<void> {
+  await answersWithin(refreshIfStale, REFRESH_WAIT_MS);
+}
+
 // Stable handler reference the adapter captures once; redispatches per request.
 const dynamicHandler: typeof bootstrapAuth.handler = async (request) => {
-  await refreshIfStale();
-  return current.handler(request);
+  await refreshForRequest();
+  return checkAuthResponse(await current.handler(request), authDatabaseReachable);
 };
 
 export const authRuntime: typeof bootstrapAuth = new Proxy(bootstrapAuth, {

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.service.ts

@@ -1,8 +1,9 @@
 import { AppException } from "@podosoft/podokit-contracts";
 import type { AccessPolicy, RequestIdentity } from "../core/services";
 import type { SettingsService } from "../settings/settings.service";
-import { getAuth, refreshIfStale } from "./auth-provider";
-import { closeAuthDatabase } from "./db";
+import { getAuth, refreshForRequest } from "./auth-provider";
+import { rethrowAuthError } from "./database-outage";
+import { authDatabaseReachable, closeAuthDatabase } from "./db";
 
 export interface AuthUser extends Record<string, unknown> {
   id: string;
@@ -18,9 +19,12 @@ export interface AuthSession {
 export type SessionResolver = (headers: Headers) => Promise<AuthSession | null>;
 
 function defaultSessionResolver(headers: Headers): Promise<AuthSession | null> {
-  return refreshIfStale()
+  return refreshForRequest()
     .then(() => getAuth().api.getSession({ headers }))
-    .then((session) => session as AuthSession | null);
+    .then(
+      (session) => session as AuthSession | null,
+      (error: unknown) => rethrowAuthError(error, authDatabaseReachable),
+    );
 }
 
 export function rolesOf(user: AuthUser): string[] {

package/dist/templates/modules/auth/files/apps/api/src/auth/auth.ts

@@ -14,7 +14,7 @@ import { oauthProvider } from "@better-auth/oauth-provider";
 import { SIGNUP_APPROVAL_REQUIRED } from "@podosoft/podokit-contracts";
 import { runUserDeletedHandlers } from "./user-delete-handlers";
 import { authBaseUrl, authSecret } from "./auth-environment";
-import { authSchemaValidation } from "./schema-validation";
+import { isMaintenanceCommand } from "./maintenance";
 // podokit:begin:auth-imports
 // podokit:end:auth-imports
 
@@ -233,7 +233,7 @@ export function buildAuth(config: AuthConfig) {
         // resolved client IP as x-forwarded-for; trust it so sessions record an IP.
         ipAddressHeaders: ["x-forwarded-for"],
       },
-      ...(authSchemaValidation() ? {} : { database: { validateSchema: false } }),
+      ...(isMaintenanceCommand() ? { database: { validateSchema: false } } : {}),
     },
     user: {
       additionalFields: {

package/dist/templates/modules/auth/files/apps/api/src/auth/database-outage.spec.ts

@@ -0,0 +1,114 @@
+import { describe, expect, it, mock } from "bun:test";
+import { APIError } from "better-auth/api";
+import { Pool } from "pg";
+import {
+  answersWithin,
+  checkAuthResponse,
+  rethrowAuthError,
+  sharedProbe,
+} from "./database-outage";
+
+const down = mock(async () => false);
+const up = mock(async () => true);
+
+async function rejection(promise: Promise<unknown>): Promise<unknown> {
+  return promise.then(() => undefined, (error: unknown) => error);
+}
+
+describe("checkAuthResponse", () => {
+  it("passes answers below 500 on without asking the database", async () => {
+    const probe = mock(async () => false);
+    for (const status of [200, 401, 403, 429]) {
+      const response = new Response(null, { status });
+      await expect(checkAuthResponse(response, probe)).resolves.toBe(response);
+    }
+    expect(probe).not.toHaveBeenCalled();
+  });
+
+  it("keeps a server error while the database answers", async () => {
+    const response = new Response(null, { status: 500 });
+    await expect(checkAuthResponse(response, up)).resolves.toBe(response);
+  });
+
+  it("reports a server error during a database outage as DATABASE_UNAVAILABLE", async () => {
+    const error = await rejection(checkAuthResponse(new Response(null, { status: 500 }), down));
+    expect(error).toMatchObject({ code: "DATABASE_UNAVAILABLE", statusCode: 503 });
+  });
+});
+
+describe("rethrowAuthError", () => {
+  it("rethrows client errors without asking the database", async () => {
+    const probe = mock(async () => false);
+    const unauthorized = new APIError("UNAUTHORIZED", { message: "Invalid session" });
+    await expect(rejection(rethrowAuthError(unauthorized, probe))).resolves.toBe(unauthorized);
+    expect(probe).not.toHaveBeenCalled();
+  });
+
+  it("reports a server error during a database outage as DATABASE_UNAVAILABLE", async () => {
+    const failed = APIError.from("INTERNAL_SERVER_ERROR", { message: "Failed to get session", code: "FAILED_TO_GET_SESSION" });
+    const error = await rejection(rethrowAuthError(failed, down));
+    expect(error).toMatchObject({ code: "DATABASE_UNAVAILABLE", statusCode: 503 });
+    expect(await rejection(rethrowAuthError(new Error("socket hang up"), down)))
+      .toMatchObject({ code: "DATABASE_UNAVAILABLE" });
+  });
+
+  it("rethrows other server errors unchanged while the database answers", async () => {
+    const failure = new Error("Unexpected");
+    await expect(rejection(rethrowAuthError(failure, up))).resolves.toBe(failure);
+  });
+});
+
+describe("answersWithin", () => {
+  it("reports success and failure of the query", async () => {
+    await expect(answersWithin(async () => [{ ok: 1 }], 100)).resolves.toBe(true);
+    await expect(answersWithin(async () => { throw new Error("refused"); }, 100)).resolves.toBe(false);
+  });
+
+  it("gives up on a query that does not answer", async () => {
+    const started = Date.now();
+    await expect(answersWithin(() => new Promise(() => undefined), 50)).resolves.toBe(false);
+    expect(Date.now() - started).toBeLessThan(1_000);
+  });
+
+  it("reports a PostgreSQL server that refuses or never answers as unreachable", async () => {
+    // Accepts the TCP connection and never answers, like a paused server.
+    const silent = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    const closed = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    closed.stop(true);
+    const pools = [silent.port, closed.port].map((port) =>
+      new Pool({
+        connectionString: `postgres://podokit:podokit@127.0.0.1:${port}/podokit`,
+        connectionTimeoutMillis: 2_000,
+      })
+    );
+    try {
+      for (const pool of pools) {
+        const started = Date.now();
+        await expect(answersWithin(() => pool.query("SELECT 1"), 200)).resolves.toBe(false);
+        expect(Date.now() - started).toBeLessThan(1_000);
+      }
+    } finally {
+      silent.stop(true);
+      await Promise.all(pools.map((pool) => pool.end().catch(() => undefined)));
+    }
+  });
+});
+
+describe("sharedProbe", () => {
+  it("lets concurrent callers share one probe and probes again afterwards", async () => {
+    let release: (value: boolean) => void = () => undefined;
+    const probe = mock(() => new Promise<boolean>((resolve) => { release = resolve; }));
+    const shared = sharedProbe(probe);
+
+    const first = shared();
+    const second = shared();
+    release(false);
+    await expect(Promise.all([first, second])).resolves.toEqual([false, false]);
+    expect(probe).toHaveBeenCalledTimes(1);
+
+    const third = shared();
+    release(true);
+    await expect(third).resolves.toBe(true);
+    expect(probe).toHaveBeenCalledTimes(2);
+  });
+});

package/dist/templates/modules/auth/files/apps/api/src/auth/database-outage.ts

@@ -0,0 +1,50 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { APIError } from "better-auth/api";
+
+/** Resolves whether the database answers now. */
+export type DatabaseProbe = () => Promise<boolean>;
+
+export function databaseUnavailable(): AppException {
+  return new AppException("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503);
+}
+
+/** Whether `query` succeeds within `timeoutMs`; a query still waiting then counts as failed. */
+export async function answersWithin(query: () => Promise<unknown>, timeoutMs: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<boolean>((resolve) => {
+    timer = setTimeout(() => resolve(false), timeoutMs);
+  });
+  try {
+    return await Promise.race([query().then(() => true, () => false), deadline]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Lets concurrent callers share one run of `probe`. */
+export function sharedProbe(probe: DatabaseProbe): DatabaseProbe {
+  let running: Promise<boolean> | undefined;
+  return () => {
+    running ??= probe().finally(() => {
+      running = undefined;
+    });
+    return running;
+  };
+}
+
+// Better Auth answers a failed query with a bare 500, and its session lookup
+// replaces the cause with INTERNAL_SERVER_ERROR. A server error is therefore
+// checked against the database itself before it is reported.
+
+/** Passes `response` on, unless it is a server error while the database does not answer. */
+export async function checkAuthResponse(response: Response, reachable: DatabaseProbe): Promise<Response> {
+  if (response.status < 500 || (await reachable())) return response;
+  throw databaseUnavailable();
+}
+
+/** Rethrows `error`, as DATABASE_UNAVAILABLE when it is a server error while the database does not answer. */
+export async function rethrowAuthError(error: unknown, reachable: DatabaseProbe): Promise<never> {
+  const clientError = error instanceof APIError && error.statusCode < 500;
+  if (!clientError && !(await reachable())) throw databaseUnavailable();
+  throw error;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/db.spec.ts

@@ -3,22 +3,25 @@ import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import { postgresPool } from "./db";
+import { AuthPostgresPool } from "./postgres-pool";
 
 function databaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
 }
 
 describe("auth database pool", () => {
-  it("applies the pool limits from the environment", () => {
+  it("applies the pool limits and the query timeout from the environment", () => {
     if (databaseProvider() !== "postgres") {
       expect(postgresPool).toBeNull();
       return;
     }
     const env = validateEnv(process.env);
+    expect(postgresPool).toBeInstanceOf(AuthPostgresPool);
     expect(postgresPool?.options).toMatchObject({
       max: env.DB_AUTH_POOL_MAX,
       connectionTimeoutMillis: env.DB_CONNECT_TIMEOUT_MS,
       idleTimeoutMillis: env.DB_IDLE_TIMEOUT_MS,
+      query_timeout: env.DB_QUERY_TIMEOUT_MS,
     });
   });
 });

package/dist/templates/modules/auth/files/apps/api/src/auth/db.ts

@@ -1,11 +1,13 @@
 import { Database as SqliteDatabase } from "bun:sqlite";
 import type { SQL } from "bun";
-import { Pool } from "pg";
 import type { AuthConfigRow, ConfigVersions } from "@podosoft/podokit-auth";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
 import { databaseUrl, sqliteDatabasePath } from "../database/database";
+import { answersWithin, sharedProbe, type DatabaseProbe } from "./database-outage";
+import { isMaintenanceCommand } from "./maintenance";
+import { AuthPostgresPool } from "./postgres-pool";
 
 const env = validateEnv(process.env);
 const url = databaseUrl(env);
@@ -15,11 +17,12 @@ function databaseProvider(): DatabaseProviderName {
 const provider = databaseProvider();
 
 export const postgresPool = provider === "postgres"
-  ? new Pool({
+  ? new AuthPostgresPool({
       connectionString: url,
       max: env.DB_AUTH_POOL_MAX,
       connectionTimeoutMillis: env.DB_CONNECT_TIMEOUT_MS,
       idleTimeoutMillis: env.DB_IDLE_TIMEOUT_MS,
+      ...(isMaintenanceCommand() ? {} : { query_timeout: env.DB_QUERY_TIMEOUT_MS }),
     })
   : null;
 
@@ -30,6 +33,12 @@ export const sqliteDatabase = provider === "sqlite"
 export const authDatabase = postgresPool ?? sqliteDatabase;
 if (!authDatabase) throw new Error("No authentication database is configured");
 
+/** Whether the authentication database answers `SELECT 1` within the readiness check timeout. */
+export const authDatabaseReachable: DatabaseProbe = sharedProbe(async () => {
+  if (!postgresPool) return true;
+  return answersWithin(() => postgresPool.query("SELECT 1"), env.READINESS_CHECK_TIMEOUT_MS);
+});
+
 let queryDatabase: SQL | undefined;
 
 export function configureAuthQueryDatabase(sql: SQL): void {

package/dist/templates/modules/auth/files/apps/api/src/auth/maintenance-command.ts

@@ -0,0 +1,5 @@
+// Imported first by maintenance commands, before ./auth creates the Better Auth
+// instance and ./db opens its pool.
+import { startMaintenanceCommand } from "./maintenance";
+
+startMaintenanceCommand();

package/dist/templates/modules/auth/files/apps/api/src/auth/maintenance.ts

@@ -0,0 +1,14 @@
+// Servers validate Better Auth's database schema at startup and bound every auth
+// query with DB_QUERY_TIMEOUT_MS. Maintenance commands, such as the migration
+// runner and the admin bootstrap, build the same instance before the schema they
+// change exists or matches, and may run statements for longer, so they opt out
+// for their process.
+let maintenance = false;
+
+export function startMaintenanceCommand(): void {
+  maintenance = true;
+}
+
+export function isMaintenanceCommand(): boolean {
+  return maintenance;
+}

package/dist/templates/modules/auth/files/apps/api/src/auth/postgres-pool.spec.ts

@@ -0,0 +1,136 @@
+import { describe, expect, it } from "bun:test";
+import type { Socket } from "bun";
+import type { PoolClient } from "pg";
+import { AuthPostgresPool } from "./postgres-pool";
+
+interface FakePostgres {
+  port: number;
+  /** While false, the server keeps every connection open and ignores queries, like a paused one. */
+  answering: boolean;
+  accepted: number;
+  closed: number;
+  stop: () => void;
+}
+
+function message(type: string, body: Buffer): Buffer {
+  const header = Buffer.alloc(5);
+  header.write(type, 0, "latin1");
+  header.writeInt32BE(body.length + 4, 1);
+  return Buffer.concat([header, body]);
+}
+
+const AUTHENTICATION_OK = message("R", Buffer.from([0, 0, 0, 0]));
+const READY_FOR_QUERY = message("Z", Buffer.from("I"));
+const SELECT_DONE = Buffer.concat([message("C", Buffer.from("SELECT 0\0")), READY_FOR_QUERY]);
+
+/** Speaks enough of the PostgreSQL protocol for pg to connect and run simple queries. */
+function fakePostgres(): FakePostgres {
+  const started = new WeakSet<Socket<undefined>>();
+  const server: FakePostgres = { port: 0, answering: true, accepted: 0, closed: 0, stop: () => undefined };
+  const listener = Bun.listen({
+    hostname: "127.0.0.1",
+    port: 0,
+    socket: {
+      open() {
+        server.accepted += 1;
+      },
+      close() {
+        server.closed += 1;
+      },
+      data(socket, data) {
+        if (!started.has(socket)) {
+          started.add(socket);
+          socket.write(Buffer.concat([AUTHENTICATION_OK, READY_FOR_QUERY]));
+          return;
+        }
+        if (server.answering && data[0] === "Q".charCodeAt(0)) socket.write(SELECT_DONE);
+      },
+    },
+  });
+  server.port = listener.port;
+  server.stop = () => listener.stop(true);
+  return server;
+}
+
+function poolFor(server: FakePostgres): AuthPostgresPool {
+  return new AuthPostgresPool({
+    host: "127.0.0.1",
+    port: server.port,
+    user: "podokit",
+    database: "podokit",
+    max: 1,
+    query_timeout: 50,
+  });
+}
+
+async function until(condition: () => boolean): Promise<void> {
+  const deadline = Date.now() + 2_000;
+  while (!condition()) {
+    if (Date.now() > deadline) throw new Error("Condition not met in time");
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+describe("AuthPostgresPool", () => {
+  it("keeps a client whose queries were answered", async () => {
+    const server = fakePostgres();
+    const pool = poolFor(server);
+    try {
+      for (let round = 0; round < 2; round += 1) {
+        const client = await pool.connect();
+        await client.query("SELECT 1");
+        client.release();
+      }
+      expect(server.accepted).toBe(1);
+      expect(pool.idleCount).toBe(1);
+    } finally {
+      await pool.end();
+      server.stop();
+    }
+  });
+
+  it("discards a client released while its query still waits for the reply", async () => {
+    const server = fakePostgres();
+    const pool = poolFor(server);
+    try {
+      const client = await pool.connect();
+      server.answering = false;
+      await expect(client.query("SELECT 1")).rejects.toThrow("Query read timeout");
+      client.release();
+
+      expect(pool.totalCount).toBe(0);
+      await until(() => server.closed === 1);
+
+      server.answering = true;
+      const next = await pool.connect();
+      await next.query("SELECT 1");
+      next.release();
+      expect(server.accepted).toBe(2);
+      expect(pool.idleCount).toBe(1);
+    } finally {
+      await pool.end();
+      server.stop();
+    }
+  });
+
+  it("discards the client through the callback form and Pool.query", async () => {
+    const server = fakePostgres();
+    const pool = poolFor(server);
+    try {
+      server.answering = false;
+      await expect(pool.query("SELECT 1")).rejects.toThrow("Query read timeout");
+      expect(pool.totalCount).toBe(0);
+
+      const client = await new Promise<PoolClient>((resolve, reject) => {
+        pool.connect((error, connected) => (connected ? resolve(connected) : reject(error)));
+      });
+      await expect(client.query("SELECT 1")).rejects.toThrow("Query read timeout");
+      client.release();
+      expect(pool.totalCount).toBe(0);
+      await until(() => server.closed === 2);
+    } finally {
+      await pool.end();
+      server.stop();
+    }
+  });
+});