Lesson 25 / 35

Client Lifecycle, Connection Pools and Project Layout

Create one ORM client per process, size its connection pool, and keep database access behind a small service layer.

By · 15 years in web development

One client, many requests

Opening a database connection is expensive: a network handshake, authentication and memory on the server. So each ORM keeps a connection pool, a set of open connections that queries borrow and return. The pool belongs to the client object (PrismaClient, the TypeORM DataSource, the Sequelize instance), which means you should create one client per process and share it, typically from a module such as db.ts. Creating a new client per request opens a new pool each time and quickly exhausts the database's connection limit. Pool size is configured differently: Sequelize uses the pool option (max, min, idle, acquire), TypeORM passes driver options through extra (for PostgreSQL, extra: { max: 10 }), and Prisma reads it from its connection settings or driver adapter depending on version. In serverless platforms each function instance has its own pool, so a traffic spike can create hundreds of connections; a connection pooler such as PgBouncer, or a provider's pooled endpoint, sits in front of the database to absorb that.

Request path through a typical app

A request reaches a route handler, which calls a service, which uses the shared ORM client, which borrows a pooled connection to talk to the database.

Five connected stages: incoming request, service layer, shared ORM client, connection pool, database.
Figure 8.1: request -> service -> ORM client -> connection pool -> database

A shared Prisma client that survives hot reload

Development servers that reload modules would otherwise create a new client on every edit. Storing it on globalThis reuses the existing one.

// src/db.ts
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;
}

Pool options in Sequelize and TypeORM

Values are examples; size the pool against your database's connection limit divided by the number of app instances.

// Sequelize
const sequelize = new Sequelize(process.env.DATABASE_URL!, {
  pool: { max: 10, min: 0, idle: 10_000, acquire: 30_000 },
});

// TypeORM (PostgreSQL driver options go in extra)
const dataSource = new DataSource({
  type: 'postgres',
  url: process.env.DATABASE_URL,
  entities: [User, Post],
  extra: { max: 10 },
});

Keep the ORM out of your route handlers

Put queries in small service or repository functions such as getPublishedPosts(authorId). Handlers stay thin, queries become reusable and testable, and switching ORMs later touches one folder instead of every route.

Quick check: An Express app creates new PrismaClient() inside every request handler. What problem is most likely under load?

  • Queries return stale data from a cache
  • Too many connection pools are opened and the database runs out of connections
  • Migrations run on every request
  • TypeScript types are lost
Answer

Too many connection pools are opened and the database runs out of connections — Each client owns its own pool. Creating one per request multiplies connections until the database limit is hit. Create one client per process and reuse it.