Как хранить соединения с базой данных в Next.js-приложении?

Next.js выполняет серверный код в Node.js-окружении, но с особенностями: в режиме разработки модули перезагружаются при каждом изменении файла (hot reload), а в продакшене на Vercel функции работают как serverless-инстансы. Если создавать клиент БД прямо в модуле или в каждом API-роуте, приложение быстро откроет сотни соединений и упрётся в лимит пула. Поэтому соединение нужно кэшировать.

Почему нельзя просто экспортировать клиент

При hot reload модуль перезагружается, и старый клиент остаётся висеть, а новый создаётся заново. В serverless каждый холодный старт тоже создаёт новый клиент. Решение — хранить клиент в глобальном объекте, который не сбрасывается между перезагрузками модулей.

Пример singleton-подхода

// lib/prisma.ts
import { PrismaClient } from '@prisma/client';

const globalForPrisma = globalThis as unknown as {
  prisma: PrismaClient | undefined;
};

export const prisma =
  globalForPrisma.prisma ??
  new PrismaClient({
    log: ['query'],
  });

if (process.env.NODE_ENV !== 'production') {
  globalForPrisma.prisma = prisma;
}

Теперь любой импорт prisma в API-роутах, server actions или getServerSideProps использует один и тот же экземпляр. В dev-режиме он сохраняется в globalThis, а в продакшене создаётся один раз на инстанс функции.

Альтернативы и нюансы

• Для драйверов без встроенного пула (например, pg) создавайте Pool один раз и переиспользуйте его.
• В serverless лучше использовать пулеры вроде Prisma Data Proxy, Neon, Supabase Pooler или PgBouncer, чтобы не держать много соединений.
• Не храните соединение в React-компонентах или клиентском коде — только на сервере.

Итог: применяйте singleton-паттерн через globalThis для любого клиента БД в Next.js — это стандартный способ избежать утечек соединений и исчерпания пула как в dev, так и в serverless-продакшене.