Nitro server routes lack connection lifecycle hooks causing pool exhaustion

Answer the question first

1. Does Nitro provide a cleanup guarantee? No. Nitro has no request/response hook that forces the ORM to close or return a connection before a serverless function freezes. event.waitUntil is best‑effort and may be cut off by the platform’s timeout.

2. How to size the pool? The rule of thumb is:
max_connections_on_DB >= max_concurrent_instances × per_instance_pool_size. When an external pooler (PgBouncer, Prisma Accelerate, RDS Proxy, etc.) sits between the function and the DB, keep per_instance_pool_size to 1‑2 connections and size the pooler to the DB limit.

3. Pattern for preserving a pooled client across invocations. Store the ORM client on globalThis so that warm instances reuse the same TCP connection pool. In serverless, the global survives across warm invocations; cold starts may open a new pool, but the pooler limits the total number of concurrent connections.

Likely explanation

In a typical Nuxt 3 + Nitro setup, each incoming request executes the route handler in a fresh execution context. If the handler creates a new ORM client (e.g., new PrismaClient() or createConnection()), that client opens a fresh TCP connection or adds to its internal pool. Nitro does not wait for that client to finish before the function terminates, so the connection can remain open until the platform’s freeze or until the DB times out. Under burst traffic, many cold instances spawn concurrently, each opening a connection, quickly hitting the database’s max_connections limit.

Confirmed facts

• Global scope in Nitro survives across warm invocations on most serverless runtimes (Vercel, Netlify, Cloudflare Workers on the V8 runtime). It is reset only on cold start.
• Prisma and Drizzle support a lazy‑initialized singleton pattern documented for Next.js and Nuxt.
• External poolers (PgBouncer, Prisma Accelerate, RDS Proxy) accept HTTP or TCP connections from many functions and enforce a hard limit on concurrent DB connections.
• Edge runtimes (Cloudflare Workers, Vercel Edge) cannot maintain persistent TCP connections; HTTP‑based drivers must be used.

Practical steps for your Nuxt 3 app

1. Create a global client factory (shown for Prisma, similar for Drizzle):

   export const getPrisma = () => {
     if (!(globalThis as any).prisma) {
       (globalThis as any).prisma = new PrismaClient({
         log: ['query'],
       });
     }
     return (globalThis as any).prisma;
   };
   

2. Use the factory in every route:

   export default defineEventHandler(async (event) => {
     const prisma = getPrisma();
     const users = await prisma.user.findMany();
     return users;
   });
   

3. Configure an external pooler if you expect burst traffic or run on serverless:
   • PostgreSQL: set up PgBouncer in transaction mode, or use Prisma Accelerate.
   • MySQL: use MySQL Proxy or RDS Proxy.
4. Size the pooler to the database’s max_connections (e.g., 100). Keep the per‑function pool to 1 connection.
5. Verify by sending a burst load (e.g., hey -n 1000 -c 50 http://yourapp/api/users) and monitoring pg_stat_activity or the pooler metrics to confirm connections do not grow beyond the pooler limit.
6. Log client creation to ensure the singleton is reused:

   if (!(globalThis as any).prisma) {
     console.log('Creating new Prisma client');
   }
   

When you need to adjust pool size

Platform	Max concurrent instances	Per‑instance pool size	DB connections used
Node server	1	1‑2	1‑2
Vercel serverless	~10	1	~10
Netlify serverless	~15	1	~15
Cloudflare Workers (V8)	~50	1	~50

Missing diagnostic detail

To fine‑tune the pool size and choose the right pooler, could you let us know which database provider and driver you are using (PostgreSQL, MySQL, SQLite, etc.) and which Nitro preset (node-server, vercel, netlify, cloudflare) you target?