@podosoft/podokit 1.1.6 → 1.2.0

package/dist/deploy-render.js

@@ -385,6 +385,8 @@ metadata:
 ${entries.length ? `data:\n${entries.map(([key, value]) => `  ${key}: ${quote(value)}`).join("\n")}` : "data: {}"}
 `;
 }
+// Above the API's 800 ms per-check readiness bound; the Kubernetes default is 1 s.
+const API_PROBE_TIMEOUT_SECONDS = 2;
 function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeConfigDigest) {
     const name = `${profile.target.release}-${kind}`;
     const workloadSecret = kind === "api" ? profile.secrets.api : profile.secrets.web;
@@ -396,14 +398,17 @@ function deployment(profile, kind, workload, image, rolloutStateDigest, runtimeC
         ? `          readinessProbe:
             httpGet: { path: /health/ready, port: 3000 }
             periodSeconds: 5
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
           livenessProbe:
             httpGet: { path: /health, port: 3000 }
             initialDelaySeconds: 20
             periodSeconds: 10
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
           startupProbe:
             httpGet: { path: /health, port: 3000 }
             failureThreshold: 30
             periodSeconds: 2
+            timeoutSeconds: ${API_PROBE_TIMEOUT_SECONDS}
 `
         : `          readinessProbe:
             httpGet: { path: /, port: 3000 }

package/dist/templates/fullstack/apps/api/package.json

@@ -16,8 +16,8 @@
     "migration:generate": "bun run typeorm -- migration:generate"
   },
   "dependencies": {
-    "@podosoft/podokit-contracts": "^0.4.0",
-    "@podosoft/podokit-runtime": "^0.2.0",
+    "@podosoft/podokit-contracts": "^0.5.0",
+    "@podosoft/podokit-runtime": "^0.3.0",
     "@elysia/cors": "^1.4.2",
     "@elysia/openapi": "^1.4.15",
     "dotenv": "^16.4.5",

package/dist/templates/fullstack/apps/api/src/app.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it, mock, type Mock } from "bun:test";
+import { cachedOpenApiDocument, type OpenApiDocumentLoader } from "./app";
+import type { OpenApiContribution } from "./core/services";
+
+function baseSpec(): Response {
+  return Response.json({ openapi: "3.1.0", paths: { "/health": { get: {} } } });
+}
+
+function source(options: {
+  contributions: () => OpenApiContribution[];
+  routeCount?: () => number;
+  base?: () => Response;
+}): { base: Mock<() => Promise<Response>>; load: OpenApiDocumentLoader } {
+  const base = mock(async () => (options.base ?? baseSpec)());
+  const load = cachedOpenApiDocument({
+    routeCount: options.routeCount ?? (() => 1),
+    base,
+    contributions: async () => options.contributions(),
+  });
+  return { base, load };
+}
+
+describe("cachedOpenApiDocument", () => {
+  it("reuses the merged document while the inputs are unchanged", async () => {
+    const auth = { document: { paths: { "/sign-in": { post: {} } } }, pathPrefix: "/api/auth" };
+    const { base, load } = source({ contributions: () => [{ ...auth }] });
+
+    const first = await load();
+    const second = await load();
+
+    expect(second).toBe(first);
+    expect(first).toMatchObject({
+      paths: { "/health": { get: {} }, "/api/auth/sign-in": { post: {} } },
+    });
+    expect(base).toHaveBeenCalledTimes(1);
+  });
+
+  it("rebuilds when a contributor returns a new document", async () => {
+    let auth: OpenApiContribution = {
+      document: { paths: { "/sign-in": { post: {} } } },
+      pathPrefix: "/api/auth",
+    };
+    const { base, load } = source({ contributions: () => [auth] });
+
+    await load();
+    auth = { document: { paths: { "/passkey": { post: {} } } }, pathPrefix: "/api/auth" };
+    const rebuilt = await load();
+
+    expect(rebuilt).toMatchObject({ paths: { "/api/auth/passkey": { post: {} } } });
+    expect(rebuilt).not.toHaveProperty(["paths", "/api/auth/sign-in"]);
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+
+  it("rebuilds when routes are added", async () => {
+    let routes = 1;
+    const { base, load } = source({ contributions: () => [], routeCount: () => routes });
+
+    await load();
+    routes = 2;
+    await load();
+
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+
+  it("returns a failed base response without caching it", async () => {
+    let fail = true;
+    const { base, load } = source({
+      contributions: () => [],
+      base: () => fail ? Response.json({ success: false }, { status: 503 }) : baseSpec(),
+    });
+
+    const failed = await load();
+    fail = false;
+    const recovered = await load();
+
+    if (!(failed instanceof Response)) throw new Error("Expected the failed base response");
+    expect(failed.status).toBe(503);
+    expect(recovered).toMatchObject({ openapi: "3.1.0" });
+    expect(base).toHaveBeenCalledTimes(2);
+  });
+});

package/dist/templates/fullstack/apps/api/src/app.ts

@@ -8,9 +8,11 @@ import {
   appContext,
   createCoreServices,
   type AppPlugin,
+  type OpenApiContribution,
   type PodokitModule,
   type ServiceRegistry,
 } from "./core/services";
+import { isDatabaseUnavailable } from "./database/database";
 import { healthPlugin } from "./health/health.plugin";
 // podokit:begin:imports
 // podokit:end:imports
@@ -52,6 +54,47 @@ function mergeOpenApi(
   return { ...base, paths, components, tags };
 }
 
+export interface OpenApiDocumentSource {
+  routeCount: () => number;
+  base: () => Promise<Response>;
+  contributions: () => Promise<OpenApiContribution[]>;
+}
+
+export type OpenApiDocumentLoader = () => Promise<Record<string, unknown> | Response>;
+
+function sameContributions(left: OpenApiContribution[], right: OpenApiContribution[]): boolean {
+  return left.length === right.length && left.every((contribution, index) =>
+    contribution.document === right[index]?.document &&
+    contribution.pathPrefix === right[index]?.pathPrefix
+  );
+}
+
+/** Contributors return the same document object while their inputs are unchanged,
+ *  so identity plus the route count (the base spec's own cache key) identifies the
+ *  merged result without a staleness window. */
+export function cachedOpenApiDocument(source: OpenApiDocumentSource): OpenApiDocumentLoader {
+  let cached: {
+    routeCount: number;
+    contributions: OpenApiContribution[];
+    document: Record<string, unknown>;
+  } | undefined;
+  return async () => {
+    const contributions = await source.contributions();
+    const routeCount = source.routeCount();
+    if (
+      cached?.routeCount === routeCount &&
+      sameContributions(cached.contributions, contributions)
+    ) {
+      return cached.document;
+    }
+    const response = await source.base();
+    if (!response.ok) return response;
+    const document = mergeOpenApi(record(await response.json()), contributions);
+    cached = { routeCount, contributions, document };
+    return document;
+  };
+}
+
 function errorEnvelope(
   code: string,
   message: string,
@@ -124,6 +167,10 @@ const buildApp = (options: CreateAppOptions = {}) => {
         set.status = error.statusCode;
         return errorEnvelope(error.code, error.message, error.statusCode, path);
       }
+      if (isDatabaseUnavailable(error)) {
+        set.status = 503;
+        return errorEnvelope("DATABASE_UNAVAILABLE", "The database is temporarily unavailable", 503, path);
+      }
       const statusCode = code === "NOT_FOUND" ? 404 : code === "VALIDATION" ? 400 : 500;
       set.status = statusCode;
       const publicCode = code === "NOT_FOUND"
@@ -144,11 +191,12 @@ const buildApp = (options: CreateAppOptions = {}) => {
     ...modules.flatMap((module) => module.plugin ? [module.plugin] : []),
   ];
   for (const plugin of plugins) app.use(plugin(context));
-  app.get("/api-docs-json", async () => {
-    const response = await app.handle(new Request("http://localhost/api-docs-elysia-json"));
-    const base = record(await response.json());
-    return mergeOpenApi(base, await context.openapi.contributions());
-  }, {
+  const openApiDocument = cachedOpenApiDocument({
+    routeCount: () => app.routes.length,
+    base: () => app.handle(new Request("http://localhost/api-docs-elysia-json")),
+    contributions: () => context.openapi.contributions(),
+  });
+  app.get("/api-docs-json", () => openApiDocument(), {
     detail: { hide: true },
   });
   app.onStop(() => { void services.close(); });

package/dist/templates/fullstack/apps/api/src/config/env.validation.ts

@@ -11,6 +11,12 @@ const schema = z.object({
   POSTGRES_USER: z.string().default("podokit"),
   POSTGRES_PASSWORD: z.string().default("podokit"),
   POSTGRES_DB: z.string().default("podokit"),
+  DB_POOL_MAX: z.coerce.number().int().positive().default(20),
+  DB_CONNECT_TIMEOUT_MS: z.coerce.number().int().positive().default(10000),
+  DB_IDLE_TIMEOUT_MS: z.coerce.number().int().nonnegative().default(30000),
+  DB_AUTH_POOL_MAX: z.coerce.number().int().positive().default(10),
+  READINESS_CHECK_TIMEOUT_MS: z.coerce.number().int().positive().default(800),
+  READINESS_CACHE_MS: z.coerce.number().int().nonnegative().default(2000),
 });
 
 export type AppEnv = z.infer<typeof schema>;

package/dist/templates/fullstack/apps/api/src/core/api-contract.ts

@@ -35,9 +35,11 @@ const MODULE_ROUTES: Record<string, string[]> = {
     "POST /account/profile-image",
     "DELETE /account/profile-image",
     "GET /profile-images/{fileName}",
+    "GET /admin/sessions",
+    "DELETE /admin/sessions/{id}",
   ],
   "api-key-auth": ["GET /machine/ping"],
-  "audit-log": ["GET /audit-logs"],
+  "audit-log": ["GET /audit-logs", "GET /audit-logs/actions"],
   analytics: [
     "GET /analytics/config",
     "GET /admin/analytics/config",
@@ -70,6 +72,12 @@ const MODULE_ROUTES: Record<string, string[]> = {
   bullmq: ["POST /jobs", "GET /jobs/{id}"],
   "file-upload": ["POST /files", "GET /files/{key}/url"],
   "job-progress": ["POST /progress"],
+  "object-storage-local": [
+    "GET /files/content/*",
+    "PUT /storage/{key}",
+    "GET /storage/{key}",
+    "GET /storage/{key}/presigned",
+  ],
   "object-storage-s3": [
     "PUT /storage/{key}",
     "GET /storage/{key}",

package/dist/templates/fullstack/apps/api/src/core/services.spec.ts

@@ -1,11 +1,20 @@
 import { describe, expect, test } from "bun:test";
+import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
+import { validateEnv } from "../config/env.validation";
+import { PROVIDERS } from "../config/providers";
 import {
   AccessPolicy,
+  createCoreServices,
   OpenApiRegistry,
+  REQUEST_IDENTITY,
   RequestGuardRegistry,
   ServiceRegistry,
 } from "./services";
 
+function databaseProvider(): DatabaseProviderName {
+  return PROVIDERS.database;
+}
+
 describe("ServiceRegistry", () => {
   test("awaits startup in registration order and starts only once", async () => {
     const registry = new ServiceRegistry();
@@ -88,3 +97,24 @@ describe("OpenApiRegistry", () => {
     expect(() => registry.register("auth", () => ({ document: {} }))).toThrow("already exists");
   });
 });
+
+describe("RequestIdentity", () => {
+  test("treats every request as anonymous until an auth module overrides it", async () => {
+    const services = createCoreServices(validateEnv({
+      NODE_ENV: "test",
+      DATABASE_URL: databaseProvider() === "sqlite"
+        ? "sqlite://:memory:"
+        : "postgres://podokit:podokit@localhost:5432/podokit",
+    }));
+    const identity = services.resolve(REQUEST_IDENTITY);
+    const request = new Request("http://localhost/todos");
+    try {
+      expect(await identity.userId(request)).toBeUndefined();
+      expect(await identity.isAdmin(request)).toBe(false);
+      expect(await identity.roles(request)).toEqual([]);
+      expect(await identity.activeOrganizationId(request)).toBeUndefined();
+    } finally {
+      await services.close();
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/core/services.ts

@@ -6,7 +6,7 @@ import {
 } from "@podosoft/podokit-runtime";
 import type { AppEnv } from "../config/env.validation";
 import { Database } from "../database/database";
-import { ReadinessService } from "../health/readiness.service";
+import { DATABASE_READINESS_CHECK, ReadinessService } from "../health/readiness.service";
 
 export type { ServiceKey } from "@podosoft/podokit-runtime";
 
@@ -124,6 +124,9 @@ export class RequestGuardRegistry {
 
 export interface RequestIdentity {
   userId(request: Request): Promise<string | undefined>;
+  isAdmin(request: Request): Promise<boolean>;
+  roles(request: Request): Promise<string[]>;
+  activeOrganizationId(request: Request): Promise<string | undefined>;
 }
 
 export interface OpenApiContribution {
@@ -177,7 +180,14 @@ export interface PodokitModule {
 export function createCoreServices(env: AppEnv): ServiceRegistry {
   const services = new ServiceRegistry();
   const database = new Database(env);
-  const readiness = new ReadinessService();
+  const readiness = new ReadinessService({
+    timeoutMs: env.READINESS_CHECK_TIMEOUT_MS,
+    cacheMs: env.READINESS_CACHE_MS,
+    // Resolved on use: a module such as logging may replace the logger after this point.
+    onCheckFailure: (check, reason) => {
+      services.resolve(LOGGER).warn({ check, reason }, "Readiness check failed");
+    },
+  });
   const logger = pino({ level: process.env.LOG_LEVEL ?? "info" });
   const accessPolicy = new AccessPolicy();
   const requestGuards = new RequestGuardRegistry();
@@ -191,10 +201,16 @@ export function createCoreServices(env: AppEnv): ServiceRegistry {
   services.register(DATABASE, database, () => database.close());
   services.onStart(() => database.connect());
   services.register(READINESS, readiness);
+  readiness.register(DATABASE_READINESS_CHECK, () => services.resolve(DATABASE).ping());
   services.register(LOGGER, logger);
   services.register(ACCESS_POLICY, accessPolicy);
   services.register(REQUEST_GUARDS, requestGuards);
-  services.register(REQUEST_IDENTITY, { userId: async () => undefined });
+  services.register(REQUEST_IDENTITY, {
+    userId: async () => undefined,
+    isAdmin: async () => false,
+    roles: async () => [],
+    activeOrganizationId: async () => undefined,
+  });
   services.register(OPENAPI, openapiRegistry);
   return services;
 }

package/dist/templates/fullstack/apps/api/src/database/database.spec.ts

@@ -1,13 +1,20 @@
+import { SQL } from "bun";
 import { describe, expect, it } from "bun:test";
 import { existsSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";
-import type { AppEnv } from "../config/env.validation";
+import { validateEnv } from "../config/env.validation";
 import { PROVIDERS } from "../config/providers";
-import { databaseUrl, sqliteDatabasePath } from "./database";
+import {
+  Database,
+  databaseUrl,
+  isDatabaseUnavailable,
+  postgresPoolOptions,
+  sqliteDatabasePath,
+} from "./database";
 import type { DatabaseProviderName } from "@podosoft/podokit-runtime";
 
-const env: AppEnv = {
+const env = validateEnv({
   NODE_ENV: "test",
   PORT: 5002,
   POSTGRES_HOST: "localhost",
@@ -15,12 +22,44 @@ const env: AppEnv = {
   POSTGRES_USER: "podokit",
   POSTGRES_PASSWORD: "podokit",
   POSTGRES_DB: "podokit",
-};
+});
 
 function databaseProvider(): DatabaseProviderName {
   return PROVIDERS.database;
 }
 
+interface ProbedSql {
+  sql: SQL;
+  probes: () => number;
+  setAvailable: (available: boolean) => void;
+  close: () => Promise<void>;
+}
+
+// Counts `SELECT 1` probes against an in-memory database and can simulate an outage.
+function probedSql(): ProbedSql {
+  const target = new SQL(":memory:", { adapter: "sqlite" });
+  let probes = 0;
+  let available = true;
+  const sql = new Proxy(target, {
+    apply(query, thisArg: unknown, args: unknown[]): unknown {
+      const [strings] = args;
+      if (Array.isArray(strings) && strings.join("").trim() === "SELECT 1") {
+        probes += 1;
+        if (!available) return Promise.reject(new Error("database unavailable"));
+      }
+      return Reflect.apply(query, thisArg, args);
+    },
+  });
+  return {
+    sql,
+    probes: () => probes,
+    setAvailable: (value) => {
+      available = value;
+    },
+    close: () => target.close(),
+  };
+}
+
 describe("database provider", () => {
   it("uses DATABASE_URL as the canonical connection setting", () => {
     const provider = databaseProvider();
@@ -56,3 +95,109 @@ describe("database provider", () => {
     }
   });
 });
+
+describe("Database ping", () => {
+  it("queries the database on every ping", async () => {
+    const probe = probedSql();
+    const database = new Database(env, probe.sql);
+    try {
+      await database.ping();
+      const afterFirstPing = probe.probes();
+      await database.ping();
+      await database.ping();
+      expect(probe.probes()).toBe(afterFirstPing + 2);
+    } finally {
+      await probe.close();
+    }
+  });
+
+  it("reports an outage that starts after a successful connect", async () => {
+    const probe = probedSql();
+    const database = new Database(env, probe.sql);
+    try {
+      await database.connect();
+      probe.setAvailable(false);
+      await expect(database.ping()).rejects.toThrow("database unavailable");
+      probe.setAvailable(true);
+      await expect(database.ping()).resolves.toBeUndefined();
+    } finally {
+      await probe.close();
+    }
+  });
+
+  it("retries the connection after a failed attempt", async () => {
+    const probe = probedSql();
+    const database = new Database(env, probe.sql);
+    try {
+      probe.setAvailable(false);
+      await expect(database.connect()).rejects.toThrow("database unavailable");
+      probe.setAvailable(true);
+      await expect(database.ping()).resolves.toBeUndefined();
+      await expect(database.connect()).resolves.toBeUndefined();
+    } finally {
+      await probe.close();
+    }
+  });
+});
+
+describe("PostgreSQL pool settings", () => {
+  it("bounds connections and converts the millisecond settings to Bun seconds", () => {
+    expect(postgresPoolOptions(env)).toEqual({ max: 20, connectionTimeout: 10, idleTimeout: 30 });
+    expect(env.DB_AUTH_POOL_MAX).toBe(10);
+    expect(
+      postgresPoolOptions(validateEnv({ DB_POOL_MAX: "5", DB_CONNECT_TIMEOUT_MS: "2500", DB_IDLE_TIMEOUT_MS: "0" })),
+    ).toEqual({ max: 5, connectionTimeout: 2.5, idleTimeout: 0 });
+  });
+
+  it("rejects pool settings that would disable the limits", () => {
+    expect(() => validateEnv({ DB_POOL_MAX: "0" })).toThrow("DB_POOL_MAX");
+    expect(() => validateEnv({ DB_AUTH_POOL_MAX: "-1" })).toThrow("DB_AUTH_POOL_MAX");
+    expect(() => validateEnv({ DB_CONNECT_TIMEOUT_MS: "0" })).toThrow("DB_CONNECT_TIMEOUT_MS");
+  });
+});
+
+describe("isDatabaseUnavailable", () => {
+  it("recognizes Bun SQL connection failures", () => {
+    for (const code of [
+      "ERR_POSTGRES_CONNECTION_TIMEOUT",
+      "ERR_POSTGRES_CONNECTION_REFUSED",
+      "ERR_POSTGRES_CONNECTION_FAILED",
+      "ERR_POSTGRES_CONNECTION_CLOSED",
+    ]) {
+      expect(isDatabaseUnavailable(new SQL.PostgresError("Connection failed", { code }))).toBe(true);
+    }
+  });
+
+  it("recognizes pg pool and connection timeouts, also when wrapped", () => {
+    const acquire = new Error("timeout exceeded when trying to connect");
+    const connect = new Error("Connection terminated due to connection timeout");
+    expect(isDatabaseUnavailable(acquire)).toBe(true);
+    expect(isDatabaseUnavailable(connect)).toBe(true);
+    expect(isDatabaseUnavailable(new Error("Failed to get session", { cause: acquire }))).toBe(true);
+  });
+
+  it("leaves query and application errors alone", () => {
+    expect(isDatabaseUnavailable(new SQL.PostgresError("syntax error", { code: "ERR_POSTGRES_SYNTAX_ERROR" })))
+      .toBe(false);
+    expect(
+      isDatabaseUnavailable(new SQL.PostgresError("duplicate key", { code: "ERR_POSTGRES_SERVER_ERROR", errno: "23505" })),
+    ).toBe(false);
+    expect(isDatabaseUnavailable(new Error("timeout"))).toBe(false);
+    expect(isDatabaseUnavailable("ERR_POSTGRES_CONNECTION_TIMEOUT")).toBe(false);
+    expect(isDatabaseUnavailable(undefined)).toBe(false);
+  });
+
+  it("recognizes a real Bun SQL connection timeout", async () => {
+    // Accepts the TCP connection and never answers, like an overloaded server.
+    const server = Bun.listen({ hostname: "127.0.0.1", port: 0, socket: { data() {} } });
+    const sql = new SQL(`postgres://podokit:podokit@127.0.0.1:${server.port}/podokit`, { connectionTimeout: 0.2 });
+    try {
+      const error: unknown = await sql`SELECT 1`.then(() => undefined, (reason: unknown) => reason);
+      expect(error).toBeInstanceOf(SQL.PostgresError);
+      expect(isDatabaseUnavailable(error)).toBe(true);
+    } finally {
+      await sql.close();
+      server.stop(true);
+    }
+  });
+});

package/dist/templates/fullstack/apps/api/src/database/database.ts

@@ -47,35 +47,88 @@ export function sqliteDatabasePath(url: string): string {
   return path;
 }
 
+export interface PostgresPoolOptions {
+  max: number;
+  connectionTimeout: number;
+  idleTimeout: number;
+}
+
+/** Bun SQL takes these timeouts in seconds; the environment sets milliseconds. */
+export function postgresPoolOptions(env: AppEnv): PostgresPoolOptions {
+  return {
+    max: env.DB_POOL_MAX,
+    connectionTimeout: env.DB_CONNECT_TIMEOUT_MS / 1000,
+    idleTimeout: env.DB_IDLE_TIMEOUT_MS / 1000,
+  };
+}
+
+// Bun SQL and pg report a database that cannot be reached, or a connection that
+// could not be opened or taken from a full pool in time, with these shapes.
+const UNAVAILABLE_SQL_CODES = new Set([
+  "ERR_POSTGRES_CONNECTION_TIMEOUT",
+  "ERR_POSTGRES_CONNECTION_REFUSED",
+  "ERR_POSTGRES_CONNECTION_FAILED",
+  "ERR_POSTGRES_CONNECTION_CLOSED",
+]);
+const UNAVAILABLE_PG_MESSAGES = new Set([
+  "timeout exceeded when trying to connect",
+  "Connection terminated due to connection timeout",
+]);
+
+/** Whether an error, or one it wraps, means the database is unavailable rather than the request being wrong. */
+export function isDatabaseUnavailable(error: unknown): boolean {
+  let current: unknown = error;
+  for (let depth = 0; depth < 5 && current instanceof Error; depth += 1) {
+    if (current instanceof SQL.PostgresError && UNAVAILABLE_SQL_CODES.has(current.code)) return true;
+    if (UNAVAILABLE_PG_MESSAGES.has(current.message)) return true;
+    current = current.cause;
+  }
+  return false;
+}
+
+function createSql(provider: DatabaseProviderName, env: AppEnv): SQL {
+  const url = databaseUrl(env);
+  return provider === "sqlite"
+    ? new SQL(url, { adapter: "sqlite", create: true, readwrite: true, strict: true })
+    : new SQL(url, postgresPoolOptions(env));
+}
+
 export class Database {
   readonly provider: DatabaseProviderName = selectedDatabaseProvider();
   readonly sql: SQL;
   private ready?: Promise<void>;
 
-  constructor(env: AppEnv) {
-    const url = databaseUrl(env);
-    this.sql = this.provider === "sqlite"
-      ? new SQL(url, { adapter: "sqlite", create: true, readwrite: true, strict: true })
-      : new SQL(url, { max: 20 });
+  constructor(env: AppEnv, sql?: SQL) {
+    this.sql = sql ?? createSql(this.provider, env);
   }
 
   connect(): Promise<void> {
-    this.ready ??= (async () => {
-      if (this.provider === "sqlite") {
-        await this.sql`PRAGMA journal_mode = WAL`;
-        await this.sql`PRAGMA foreign_keys = ON`;
-        await this.sql`PRAGMA busy_timeout = 5000`;
-      }
-      await this.sql`SELECT 1`;
-    })();
+    if (!this.ready) {
+      const attempt = this.initialize();
+      this.ready = attempt;
+      // Forget a failed start so the next call retries instead of replaying the failure.
+      void attempt.catch(() => {
+        if (this.ready === attempt) this.ready = undefined;
+      });
+    }
     return this.ready;
   }
 
   async ping(): Promise<void> {
     await this.connect();
+    await this.sql`SELECT 1`;
   }
 
   async close(): Promise<void> {
     await this.sql.close();
   }
+
+  private async initialize(): Promise<void> {
+    if (this.provider === "sqlite") {
+      await this.sql`PRAGMA journal_mode = WAL`;
+      await this.sql`PRAGMA foreign_keys = ON`;
+      await this.sql`PRAGMA busy_timeout = 5000`;
+    }
+    await this.sql`SELECT 1`;
+  }
 }