What is a singleton — and why your dev database says "too many connections"

A weird story. You're building a Next.js app with a database. Everything works. You edit code, save, edit, save. Half an hour later the database suddenly replies: "too many connections".
The app has exactly one user — you. Where did all those connections come from?
Every file save quietly created a new connection, and nobody closed the old ones. The cure is a trick with a grand name: the singleton. It sounds like a pattern from a thick textbook, but in practice it's five lines. Let's dig in.
What a singleton is
A singleton is an object that exists in your app as a single instance. However many times and from wherever it's requested — everyone gets the same one.
Analogy: the office key on a hook by the door. There's one key. Whoever comes first takes it; whoever comes second takes that same key. Nobody orders a brand-new key every morning.
Why bother? Some things are expensive to create or must not be multiplied:
- a connection to the database — the database has a limit on simultaneous connections;
- a client for an external service or SDK — it keeps connections open;
- app settings — they must be the same everywhere.
How it works in JavaScript
Good news: in JavaScript a singleton often happens on its own. A module runs once — on the first import. After that, everyone importing it gets the already-built result.
// db.js
import { PrismaClient } from "@prisma/client";
export const db = new PrismaClient();
Import db in ten files — the connection is created once. The module is the singleton. No need for classes with clever checks like in Java textbooks.
Why hot reload breaks the singleton
Now the answer to our story. In development, Next.js re-runs changed modules on every save. That's hot reload — you see edits without restarting.
But for db.js it means: every save runs new PrismaClient() again. New client — new connections. Nobody closed the old client; it hangs in memory holding its own. Save the file twenty times — and the database has twenty sets of connections.
The fix: keep the client somewhere a reload won't wipe it. That's globalThis — the global object that lives as long as the process itself:
// db.js
import { PrismaClient } from "@prisma/client";
const globalForDb = globalThis;
export const db = globalForDb.db ?? new PrismaClient();
if (process.env.NODE_ENV !== "production") {
globalForDb.db = db;
}
Simple logic. If the client is already in globalThis — use it. If not — create it and put it there. The module reloaded, but the client stays the same. This is exactly what Prisma recommends in its Next.js docs.
Why the production check
Notice the NODE_ENV line. Production has no hot reload — the module runs once and the singleton just works. We stash it in globalThis only in development, to survive reloads. Where NODE_ENV comes from is covered in the piece on environment variables.
How to tell you have this problem:
- The error shows up only in development and only after a while.
- Restarting
pnpm devmakes it go away — and it comes back half an hour later. - The logs warn about multiple client instances.
All three match — check how the database client is created. Most likely the AI just wrote new PrismaClient() in a module.
How to ask the AI to do it right
If you don't want to fix it by hand, phrase the task so the AI can't write the naive version:
Connect Prisma to my Next.js project.Connect Prisma to a Next.js project (App Router). Create the database client once in lib/db.ts as a singleton: in development keep it in globalThis so hot reload does not create new connections, in production use a plain export. Show how to import db in a server component.The weak prompt almost always yields new PrismaClient() right in the file — and half an hour later you're reading "too many connections" again.
When a singleton is a bad idea
Singletons are handy, but easy to misuse:
- User data in a singleton is trouble. On the server, one object is shared by all users. Put "the current user" there — and someone sees a stranger's profile.
- Tests. A shared object drags state from one test into another. Tests start failing depending on their order.
Rule: put tools in a singleton (connection, client, settings), never data for a specific request.
Does a singleton work in serverless?
Partly. Each copy of the function is a separate process with its own singleton. There can be many copies, so in serverless databases rely on a connection pooler on the database side.
Is a singleton the same as a global variable?
Similar, but not quite. Anyone can overwrite a global variable. A singleton is usually handed out through one function or module, and it's created once.
Is this only for Prisma?
No. The same trick applies to any client that holds connections: Redis, Mongo, a server-side Supabase client, job queues.
The AI Architect 2027 course: step by step from computer basics to your own app and first customers. 543 short lessons on your phone.





