@podosoft/podokit 1.3.0 → 1.4.1

package/dist/templates/modules/admin-dashboard/module.manifest.json

@@ -14,7 +14,8 @@
   "ownedGlobs": [
     "apps/web/src/lib/i18n/locales/**",
     "apps/web/src/lib/i18n/catalogs/app/**",
-    "apps/web/src/lib/server/public-paths.ts"
+    "apps/web/src/lib/server/public-paths.ts",
+    "apps/web/src/lib/server/asset-paths.ts"
   ],
   "managedOverrides": [
     "apps/web/src/lib/components/ui/input/input.svelte",
@@ -118,7 +119,7 @@
       "file": "AGENTS.md",
       "marker": "<!-- podokit:end:agents-modules -->",
       "optional": true,
-      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
+      "text": "### admin-dashboard\n- The `(admin)` route group and `admin-sidebar.svelte` are the admin-console shell for `/admin/*` only. Put signed-in product pages in `(app)` or in a separate route group with its own layout; do not place them under `(admin)`.\n- Admin console lives at `/admin/*` (users, sessions, organizations, audit, settings, account). Set `ADMIN_EMAILS`, then create or verify the initial account with `{{apiRun}} admin:bootstrap{{apiWorkspaceArg}}`; never commit or persist `ADMIN_BOOTSTRAP_PASSWORD`. When sign-up approval is enabled, self-registered users stay pending until an administrator approves them on `/admin/users`; administrator-created users bypass the queue.\n- Signed-in users can upload, replace, or remove their profile image from `/account` or `/admin/account`. Keep the shared policy visible in custom account UI: PNG, JPEG, or WebP; at most 2 MB and 2048 by 2048 pixels. Use the managed `/api/account/profile-image` endpoints instead of writing directly to storage or `user.image`.\n- `sidebar-user-menu.svelte` is specific to the admin sidebar. For a product shell outside `Sidebar.Provider`, use the managed `<AccountMenu {user} variant=\"identity\" side=\"top\" />` component.\n- Custom protected server layouts must call `requireBackendAvailable(locals)` from `#lib/server/guards.js` before redirecting anonymous users. This preserves sessions and returns 503 when authentication or maintenance policy cannot be checked.\n- Every page except the sign-in flow, `/`, and module pages requires a session, and fails closed with 503 when the API or site settings are unavailable. List the application's public pages (marketing, pricing, legal, `robots.txt`) in `APP_PUBLIC_PATHS` in the app-owned `apps/web/src/lib/server/public-paths.ts`; a prefix covers its subpaths. Do not edit the `PUBLIC_PATHS` list in the managed `guards.ts`.\n- `hooks.server.ts` loads the site settings and the session for pages, page data, form actions, remote functions, and the 404 page. When a `+server.ts` endpoint serves files or feeds that need neither, list its prefix in `APP_ASSET_PATHS` in the app-owned `apps/web/src/lib/server/asset-paths.ts` to skip both API calls; such endpoints see an anonymous `locals.user`, and page requests under the prefix still get the full context.\n- **Every list/table MUST use the shared `#lib/components/data-table.svelte` (`DataTable`)** \u2014 it gives sortable headers + a footer pagination. Add search/filters with `#lib/components/table-toolbar.svelte`. Never assemble `Table.Root`/`Table.Header`/`Table.Body` by hand. For responsive columns, use `hideBelow` and apply the row context's `cellClass(columnKey)` to the matching cell.\n"
     },
     {
       "file": "apps/api/src/app.ts",

package/dist/templates/modules/audit-log/module.manifest.json

@@ -34,7 +34,7 @@
     }
   ],
   "instructions": [
-    "Run migrations to create the audit_logs table: {{apiRun}} migration:run{{apiWorkspaceArg}}",
+    "Run migrations to create the audit_logs table: {{apiRun}} migrate:all{{apiWorkspaceArg}}",
     "Auth/admin actions are recorded by a Better Auth hook. Record semantic application events with AuditService.recordRequest() or recordAudit(); use recordAuditLater() only for high-volume, non-security events.",
     "List entries newest first (admin session required): curl -i -b cookies.txt 'localhost:5002/audit-logs?limit=50' and pass the X-Next-Cursor header back as ?cursor= for the next page"
   ],

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();
+    }
+  });
+});

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

@@ -0,0 +1,40 @@
+import { Pool, type PoolClient } from "pg";
+
+type ConnectCallback = Parameters<Pool["connect"]>[0];
+
+/** Whether `client` still waits for the reply to a query; pg sets `readyForQuery` once the server is ready for the next one. */
+function awaitingReply(client: PoolClient): boolean {
+  return Reflect.get(client, "readyForQuery") === false;
+}
+
+function discardWhileAwaitingReply(client: PoolClient): PoolClient {
+  const release = client.release;
+  client.release = (error?: Error | boolean): void => {
+    release.call(
+      client,
+      error || (awaitingReply(client) ? new Error("Released while waiting for a query reply") : undefined),
+    );
+  };
+  return client;
+}
+
+/**
+ * pg fails a query after `query_timeout` but leaves the connection waiting for
+ * the reply. `Pool.query` discards that client, but Kysely, which Better Auth
+ * runs on, releases it as healthy, so the pool would hand it out again and
+ * every later query on it would queue behind the missing reply. This pool
+ * discards a client released while it still waits for a reply: pg closes its
+ * socket, and the next query gets a new connection.
+ */
+export class AuthPostgresPool extends Pool {
+  override connect(): Promise<PoolClient>;
+  override connect(callback: ConnectCallback): void;
+  override connect(callback?: ConnectCallback): Promise<PoolClient> | void {
+    if (!callback) return super.connect().then(discardWhileAwaitingReply);
+    super.connect((error, client, done) => {
+      if (!client) return callback(error, client, done);
+      const guarded = discardWhileAwaitingReply(client);
+      callback(error, guarded, guarded.release);
+    });
+  }
+}

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

@@ -1,6 +1,7 @@
 // Keep this first: Better Auth checks the schema when ./auth/auth creates its
-// instance, and the migrations below are what make that schema match.
-import "./auth/skip-schema-validation";
+// instance, the migrations below are what make that schema match, and they may
+// run longer than the auth pool's query timeout.
+import "./auth/maintenance-command";
 import { getMigrations } from "better-auth/db/migration";
 import { auth } from "./auth/auth";
 import { closeAuthDatabase, postgresPool, sqliteDatabase } from "./auth/db";

package/dist/templates/modules/auth/module.manifest.json

@@ -19,7 +19,6 @@
     "@types/pg": "^8.11.10"
   },
   "scripts": {
-    "migrate:all": "bun scripts/run-migrations.mjs",
     "auth:configure": "bun scripts/configure-auth.mjs"
   },
   "env": [