fix(webapp): don't eagerly connect the webhook database clients

When hosted webhooks use a dedicated database (`WEBHOOK_DATABASE_URL`),
webapp processes no longer open connections to it at startup. They
connect on first use, so services that never handle webhooks hold no
webhook database connections.

Mono-RevId: 1650824151421dd3f296cadd8b1b12521021ae92

Author: ericallam

apps/webapp/app/db.server.ts

@@ -252,6 +252,7 @@ export const webhookPrisma: WebhookDatabase = singleton("webhookPrisma", () => {
         url: env.WEBHOOK_DATABASE_URL,
         clientType: "webhook-writer",
         connectionLimit: env.WEBHOOK_DATABASE_CONNECTION_LIMIT ?? env.DATABASE_CONNECTION_LIMIT,
+        eagerConnect: false,
       })
     )
   );
@@ -272,6 +273,7 @@ export const webhookPartitionPrisma: WebhookDatabase = singleton("webhookPartiti
         url: env.WEBHOOK_DATABASE_DIRECT_URL,
         clientType: "webhook-partitions",
         connectionLimit: 1,
+        eagerConnect: false,
       })
     )
   );
@@ -291,6 +293,7 @@ export const webhookReplica: WebhookReplicaDatabase = singleton("webhookReplica"
             url: env.WEBHOOK_DATABASE_READ_REPLICA_URL,
             clientType: "webhook-reader",
             connectionLimit: env.WEBHOOK_DATABASE_CONNECTION_LIMIT ?? env.DATABASE_CONNECTION_LIMIT,
+            eagerConnect: false,
           })
         )
       )
@@ -744,13 +747,16 @@ export function buildWriterClient({
   poolTimeout,
   connectTimeout,
   useDriverAdapter = false,
+  eagerConnect = true,
 }: {
   url: string;
   clientType: string;
   connectionLimit?: number;
   poolTimeout?: number;
   connectTimeout?: number;
   useDriverAdapter?: boolean;
+  /** Open a connection at build time. Off for clients most processes never query. */
+  eagerConnect?: boolean;
 }): PrismaClient {
   const databaseUrl = buildPrismaConnectionUrl(url, {
     connectionLimit: connectionLimit.toString(),
@@ -836,17 +842,19 @@ export function buildWriterClient({
         log: logConfig,
       });
 
-  registerDatabaseMetricsSource(
-    driverPool
+  let used = eagerConnect;
+  registerDatabaseMetricsSource({
+    ...(driverPool
       ? {
           clientType,
           usesDriverAdapter: true,
           client,
           pool: driverPool.pool,
           poolCounters: driverPool.poolCounters,
         }
-      : { clientType, usesDriverAdapter: false, client }
-  );
+      : { clientType, usesDriverAdapter: false, client }),
+    isActive: () => used,
+  });
 
   // Only use structured logging if we're not already logging to stdout
   if (process.env.PRISMA_LOG_TO_STDOUT !== "1") {
@@ -890,6 +898,18 @@ export function buildWriterClient({
     queryPerformanceMonitor.onQuery("writer", log);
   });
 
+  if (!eagerConnect) {
+    return client.$extends({
+      name: "first-query-marker",
+      query: {
+        $allOperations: ({ query, args }) => {
+          used = true;
+          return query(args);
+        },
+      },
+    }) as unknown as PrismaClient;
+  }
+
   // Connect eagerly; Prisma will connect on use anyway.
   // Swallow the error when testing (DB likely unavailable)
   const connectPromise = client.$connect();
@@ -933,13 +953,16 @@ export function buildReplicaClient({
   poolTimeout,
   connectTimeout,
   useDriverAdapter = false,
+  eagerConnect = true,
 }: {
   url: string;
   clientType: string;
   connectionLimit?: number;
   poolTimeout?: number;
   connectTimeout?: number;
   useDriverAdapter?: boolean;
+  /** Open a connection at build time. Off for clients most processes never query. */
+  eagerConnect?: boolean;
 }): PrismaClient {
   const replicaUrl = buildPrismaConnectionUrl(url, {
     connectionLimit: connectionLimit.toString(),
@@ -1025,17 +1048,19 @@ export function buildReplicaClient({
         log: logConfig,
       });
 
-  registerDatabaseMetricsSource(
-    driverPool
+  let used = eagerConnect;
+  registerDatabaseMetricsSource({
+    ...(driverPool
       ? {
           clientType,
           usesDriverAdapter: true,
           client: replicaClient,
           pool: driverPool.pool,
           poolCounters: driverPool.poolCounters,
         }
-      : { clientType, usesDriverAdapter: false, client: replicaClient }
-  );
+      : { clientType, usesDriverAdapter: false, client: replicaClient }),
+    isActive: () => used,
+  });
 
   // Only use structured logging if we're not already logging to stdout
   if (process.env.PRISMA_LOG_TO_STDOUT !== "1") {
@@ -1078,6 +1103,18 @@ export function buildReplicaClient({
     queryPerformanceMonitor.onQuery("replica", log);
   });
 
+  if (!eagerConnect) {
+    return replicaClient.$extends({
+      name: "first-query-marker",
+      query: {
+        $allOperations: ({ query, args }) => {
+          used = true;
+          return query(args);
+        },
+      },
+    }) as unknown as PrismaClient;
+  }
+
   // Connect eagerly; Prisma will connect on use anyway.
   // Swallow the error when testing (DB likely unavailable)
   const connectPromise = replicaClient.$connect();

apps/webapp/app/utils/databaseMetrics.server.ts

@@ -28,6 +28,8 @@ export type DatabaseMetricsSource = {
   client: MetricsCapableClient;
   pool?: PoolLike;
   poolCounters?: { opened: () => number; closed: () => number };
+  /** False until a lazy client's first query; reading engine metrics would connect it. */
+  isActive?: () => boolean;
 };
 
 type NormalizedPoolMetrics = {
@@ -131,14 +133,16 @@ export function normalizeDatabaseMetrics(
 
 export async function collectDatabaseClientMetrics(): Promise<NormalizedDatabaseMetrics[]> {
   return Promise.all(
-    Array.from(sources.values()).map(async (source) => {
-      let json: PrismaMetricsJson | undefined;
-      try {
-        json = await source.client.$metrics.json();
-      } catch {
-        json = undefined;
-      }
-      return normalizeDatabaseMetrics(source, json);
-    })
+    Array.from(sources.values())
+      .filter((source) => source.isActive?.() ?? true)
+      .map(async (source) => {
+        let json: PrismaMetricsJson | undefined;
+        try {
+          json = await source.client.$metrics.json();
+        } catch {
+          json = undefined;
+        }
+        return normalizeDatabaseMetrics(source, json);
+      })
   );
 }

apps/webapp/test/runOpsDbTopology.test.ts

@@ -6,6 +6,7 @@ import {
   sameDatabaseTarget,
   selectRunOpsTopology,
 } from "~/db.server";
+import { collectDatabaseClientMetrics } from "~/utils/databaseMetrics.server";
 
 const cp = { writer: {} as any, replica: {} as any };
 
@@ -383,3 +384,53 @@ describe("selectRunOpsTopology (integration, real containers)", () => {
     }
   }, 120_000);
 });
+
+describe("eagerConnect", () => {
+  it("a client built with eagerConnect: false opens no connection until its first query, even when metrics are collected", async () => {
+    const pg = await new PostgreSqlContainer("docker.io/postgres:14").start();
+    const url = pg.getConnectionUri();
+    const observer = buildWriterClient({ url, clientType: "observer", connectionLimit: 1 });
+    const clients = [observer];
+    const backends = async () => {
+      const [row] = await observer.$queryRawUnsafe<{ n: number }[]>(
+        `SELECT count(*)::int AS n FROM pg_stat_activity WHERE backend_type = 'client backend' AND pid <> pg_backend_pid()`
+      );
+      return row.n;
+    };
+    try {
+      const baseline = await backends();
+
+      const lazyWriter = buildWriterClient({
+        url,
+        clientType: "lazy-writer",
+        connectionLimit: 1,
+        eagerConnect: false,
+      });
+      const lazyReplica = buildReplicaClient({
+        url,
+        clientType: "lazy-replica",
+        connectionLimit: 1,
+        eagerConnect: false,
+      });
+      clients.push(lazyWriter, lazyReplica);
+      const collectedTypes = async () =>
+        (await collectDatabaseClientMetrics()).map((metrics) => metrics.clientType);
+      expect(await collectedTypes()).not.toContain("lazy-writer");
+      await new Promise((resolve) => setTimeout(resolve, 500));
+      expect(await backends()).toBe(baseline);
+
+      await lazyWriter.$queryRawUnsafe("SELECT 1");
+      await lazyReplica.$queryRawUnsafe("SELECT 1");
+      expect(await backends()).toBe(baseline + 2);
+      expect(await collectedTypes()).toEqual(
+        expect.arrayContaining(["lazy-writer", "lazy-replica"])
+      );
+
+      clients.push(buildWriterClient({ url, clientType: "eager-writer", connectionLimit: 1 }));
+      await expect.poll(backends, { timeout: 5_000 }).toBe(baseline + 3);
+    } finally {
+      await Promise.all(clients.map((client) => client.$disconnect()));
+      await pg.stop();
+    }
+  }, 60_000);
+});