Instantiating Prisma Client
1. Creating PrismaClient Instance
import { PrismaClient } from "@prisma/client";
export const prisma = new PrismaClient();| Note | Detail |
|---|---|
| Connection | Lazy: opens on first query |
| Pooling | Internal pool (one process) |
2. Configuring Client Options
| Option | Purpose |
|---|---|
log | Logging config |
datasources | Override URL per environment |
errorFormat | "pretty" | "colorless" | "minimal" |
transactionOptions | Default timeout/isolation |
3. Using Singleton Pattern
Example: Next.js / Node singleton
import { PrismaClient } from "@prisma/client";
const globalForPrisma = globalThis as unknown as { prisma?: PrismaClient };
export const prisma = globalForPrisma.prisma ?? new PrismaClient();
if (process.env.NODE_ENV !== "production") globalForPrisma.prisma = prisma;| Why | Detail |
|---|---|
| Avoid leaks | Hot-reload creates multiple clients otherwise |
| Connections | Re-use pool across modules |
4. Managing Development Hot Reload
| Framework | Approach |
|---|---|
| Next.js | Singleton via globalThis |
| tsx / nodemon | Same singleton works |
| Bun | Use --hot + singleton |
5. Setting Error Formatting
| Mode | Output |
|---|---|
pretty | Colored, multi-line (dev default) |
colorless | Multi-line plain |
minimal | One-line (prod) |
6. Configuring Data Sources
const prisma = new PrismaClient({
datasources: { db: { url: process.env.READ_REPLICA_URL! } }
});| Use | Detail |
|---|---|
| Override URL | Different DB per tenant/env |
| Per-request | Instantiate scoped client (costly) |
7. Using Multiple Client Instances
| Pattern | Use Case |
|---|---|
| Per database | Microservices reading two DBs |
| Per tenant | Multi-tenant URL switching |
| Read/write split | One client per replica |
8. Implementing Lazy Loading
| Aspect | Detail |
|---|---|
| Default | Connection opens on first query |
| Force | await prisma.$connect() in warm path |
9. Handling Client Initialization Errors
| Error | Cause |
|---|---|
PrismaClientInitializationError | Bad URL, binary not found |
P1001 | Can't reach DB |
P1002 | Connection timed out |
10. Using Global Prisma Instance
// lib/prisma.ts
import { PrismaClient } from "@prisma/client";
export const prisma = (globalThis as any).prisma ?? new PrismaClient();
(globalThis as any).prisma = prisma;| Best Practice | Detail |
|---|---|
| Export from single module | Re-import everywhere |
| Disconnect | Gracefully on SIGTERM in servers |