PrismaClient Singleton Pattern

Teaches global singleton pattern to prevent multiple PrismaClient instances from exhausting database connection pools.

Role: Teach proper PrismaClient instantiation and export via global singleton pattern to prevent connection pool exhaustion, P1017 errors, and serverless deployment failures.

When to Activate: Creating PrismaClient instances, setting up database clients/exports, encountering P1017 errors, working with serverless environments (Next.js, Lambda, Vercel), or reviewing @prisma/client code.

Problem & Solution

Problem: Creating multiple new PrismaClient() instances (the #1 Prisma violation) creates separate connection pools causing: pool exhaustion/P1017 errors, performance degradation, serverless failures (Lambda instances × pool size = disaster), and memory waste. Critical: 80% of AI agents in testing created multiple instances causing production failures.

Solution: Use global singleton pattern with module-level export: (1) check if PrismaClient exists globally, (2) create if none exists, (3) export for module reuse, (4) never instantiate in functions/classes. Supports module-level singletons (Node.js), global singletons (serverless/hot-reload), test patterns, and pool configuration.

Implementation Workflow

Phase 1 — Assess: Grep for @prisma/client imports and new PrismaClient() calls; identify environment type (hot-reload vs. serverless vs. traditional Node.js vs. tests).

Phase 2 — Implement: Choose pattern based on environment; create/update client export (lib/db.ts or lib/prisma.ts) using global singleton check; update all imports to use singleton; remove duplicate instantiations.

Phase 3 — Validate: Grep for new PrismaClient() (

should appear once only); test hot reload; verify no P1017 errors; check database connection count; monitor production deployment and logs.

Examples

Module-Level Singleton (Traditional Node.js)

File: lib/db.ts

import { PrismaClient } from '@prisma/client';
const prisma = new PrismaClient();
export default prisma;

Usage: import prisma from '@/lib/db' — works because module loads once in Node.js, creating single shared instance.

Global Singleton (Next.js/Hot Reload)

File: lib/prisma.ts

import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined };
export const prisma = globalForPrisma.prisma ?? new PrismaClient();
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

Why: globalThis survives hot module reload; development reuses client across reloads; production creates clean instance per deployment; prevents “too many clients” during development.

Anti-Pattern: Function-Scoped Creation

WRONG:

async function getUsers() {
  const prisma = new PrismaClient(); // ❌ New pool every call
  const users = await prisma.user.findMany();
  await prisma.$disconnect();
  return users;
}

Problems: New connection pool per function call; connection overhead kills performance; pool never warms up; exhausts connections under load.

Fix: import prisma from '@/lib/db' and use it directly without creating new instances.

Reference Files

• Serverless Pattern: references/serverless-pattern.md — Next.js App Router, Vercel, AWS Lambda configurations
• Test Pattern: references/test-pattern.md — test setup, mocking, isolation strategies
• Common Scenarios: references/common-scenarios.md — codebase conversion, P1017 troubleshooting, configuration

Load when working with serverless, writing tests, or troubleshooting specific issues.

Constraints

MUST: Create PrismaClient exactly

once; export from centralized module (lib/db.ts); use global singleton in hot-reload environments; import singleton in all database-access files; never instantiate inside functions or classes.

SHOULD: Place in lib/db.ts, lib/prisma.ts, or src/db.ts; configure logging based on NODE_ENV; set connection pool size for deployment; use TypeScript; document connection configuration.

NEVER: Create PrismaClient in route handlers, API endpoints, service functions, test files, utility functions; create multiple instances “just to be safe”; disconnect/reconnect repeatedly.

Validation

After implementing:

Standard Client Export

TypeScript:

import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as { prisma: PrismaClient | undefined };
export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
  });
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;

JavaScript:

const { PrismaClient } = require('@prisma/client');
const globalForPrisma = globalThis;
const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: process.env.NODE_ENV === 'development' ? ['query', 'error', 'warn'] : ['error'],
  });
if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;
module.exports = prisma;

Quick Reference

Setup Checklist:

• Create lib/db.ts or lib/prisma.ts; use global singleton pattern (hot reload environments); export single instance; configure logging by NODE_ENV; set connection_limit for serverless; import singleton in all files; never create PrismaClient elsewhere; validate with grep (one instance); test hot reload; monitor production connections

Red Flags (Implement Singleton Immediately):

• Multiple new PrismaClient() in grep results; P1017 errors in logs; growing connection count during development; different files importing from @prisma/client; PrismaClient creation inside functions; test files creating own clients

Related Skills

TypeScript Type Safety:

• If using type guards for singleton validation, use the using-type-guards skill from typescript for type narrowing patterns