Avoid module-scoped DB clients in Workers templates

[sethcarlton]

Issue
In Cloudflare Workers, using a module-level singleton DB client over TCP can fail on subsequent requests.

The first request succeeds, but after idle time the TCP connection is closed. A subsequent request reuses the stale client and hangs until Workers cancels the request with:

The Workers runtime canceled this request because it detected that your Worker's code had hung and would never generate a response.
Ref: https://developers.cloudflare.com/workers/observability/errors/

Fix
In Workers, a request-scoped TCP DB client should be created , so idle/stale connections are not reused and do not crash the worker.

Notes
The issue only surfaces when using TCP, but I think the sane default would be to always scope the instance to the request (in workers) and not worry about detecting the driver.

[nathanschram]

I think you've traced this correctly - the Workers template is creating a module-scoped DB client over TCP, which is a known anti-pattern in the Workers runtime.

What's happening is that export const db = drizzle(env.DATABASE_URL, { schema }) in the generated index.ts opens a TCP connection at module load time. In Workers, module-scope code runs once on cold start and persists across requests. After the worker goes idle, the runtime closes the underlying TCP socket, but the db variable still references the dead connection. Next request tries to query through it and hangs until Workers kills it.

The Cloudflare docs are pretty explicit about this - from the TCP sockets reference:

TCP sockets cannot be created in global scope and shared across requests. You should always create TCP sockets within a handler.

Looking at the template code, I think this affects more than just the Drizzle + Postgres path. The MySQL template (drizzle/mysql/src/index.ts.hbs) and the Prisma + Postgres template (prisma/postgres/src/index.ts.hbs) have the same module-scoped pattern for Workers. The Neon and PlanetScale paths are fine since they use HTTP-based drivers.

For the fix, I think exporting a factory function instead of a singleton would be the cleanest approach for the TCP-based drivers:

--- a/packages/template-generator/templates/db/drizzle/postgres/src/index.ts.hbs
+++ b/packages/template-generator/templates/db/drizzle/postgres/src/index.ts.hbs
 import * as schema from "./schema";
 import { drizzle } from "drizzle-orm/node-postgres";
 import { env } from "@{{projectName}}/env/server";

-export const db = drizzle(env.DATABASE_URL || "", { schema });
+export const createDb = () => drizzle(env.DATABASE_URL || "", { schema });
+export type Database = ReturnType<typeof createDb>;

The trade-off is that consumer templates (todo router, auth, etc.) would need to change from import { db } to calling createDb() inside the request handler - so it's a broader change than just these template files. As you mentioned, scoping to the request regardless of driver is probably the sane default for Workers.

Happy to open a PR if that'd be easier - let me know how you'd prefer to approach it.