Что такое…

Что такое синглтон — и почему в разработке база говорит «слишком много подключений»

Иллюстрация: один ключ на всех, сколько бы рук к нему ни тянулось

Странная история. Ты делаешь приложение на Next.js с базой данных. Всё работает. Ты правишь код, сохраняешь, правишь, сохраняешь. Через полчаса база вдруг отвечает: «too many connections» — слишком много подключений.

Пользователь у приложения — ты один. Откуда столько подключений?

Каждое сохранение файла тихо создавало новое подключение, а старые никто не закрывал. Лечится это приёмом с громким названием синглтон. Звучит как паттерн из толстой книжки, а на деле — пять строк. Разберёмся.

Что такое синглтон

Синглтон (singleton) — это объект, который существует в приложении в одном экземпляре. Сколько бы раз и откуда бы его ни просили — получают один и тот же.

Аналогия: ключ от офиса на крючке у входа. Ключ один. Кто пришёл первым — берёт его, кто вторым — берёт тот же самый. Никто не заказывает себе новый ключ каждое утро.

Зачем это нужно? Некоторые вещи дорого создавать или их нельзя плодить:

  • подключение к базе данных — у базы лимит одновременных подключений;
  • клиент внешнего сервиса или SDK — он держит открытые соединения;
  • настройки приложения — они должны быть одинаковыми везде.

Как это работает в JavaScript

Хорошая новость: в JavaScript синглтон часто получается сам. Модуль выполняется один раз — при первом импорте. Дальше все, кто его импортирует, получают уже готовый результат.

// db.js
import { PrismaClient } from "@prisma/client";
export const db = new PrismaClient();

Импортируешь db в десяти файлах — подключение создаётся один раз. Модуль и есть синглтон. Не нужны никакие классы с хитрыми проверками, как в учебниках по Java.

Почему hot reload ломает синглтон

А теперь разгадка нашей истории. В режиме разработки Next.js при каждом сохранении заново выполняет изменённые модули. Это и есть горячая перезагрузка — ты видишь правки без перезапуска.

Но для db.js это значит: при каждом сохранении снова выполняется new PrismaClient(). Новый клиент — новые подключения. Старый клиент никто не закрыл, он висит в памяти и держит свои. Сохранил файл двадцать раз — и у базы двадцать комплектов подключений.

Фикс — хранить клиента там, где перезагрузка его не сотрёт. Это globalThis — глобальный объект, который живёт, пока работает сам процесс:

// 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;
}

Логика простая. Если клиент уже лежит в globalThis — бери его. Если нет — создай и положи туда. Модуль перезагрузился — а клиент остался тот же. Именно так Prisma советует делать в своей документации для Next.js.

Почему проверка на production

Обрати внимание на строчку с NODE_ENV. В продакшене горячей перезагрузки нет — модуль выполняется один раз, и синглтон работает сам. Кладём в globalThis только в разработке, чтобы пережить перезагрузки. Про то, откуда берётся NODE_ENV, — в статье о переменных окружения.

Как понять, что у тебя эта проблема:

  1. Ошибка появляется только в разработке и только через какое-то время работы.
  2. После перезапуска pnpm dev она пропадает — и возвращается через полчаса.
  3. В логах видно предупреждение о нескольких экземплярах клиента.

Все три совпали — проверь, как создаётся клиент базы. Скорее всего, ИИ написал просто new PrismaClient() в модуле.

Как попросить ИИ сделать правильно

Если не хочешь править руками, сформулируй задачу так, чтобы ИИ не мог написать наивный вариант:

Слабый промптПодключи Prisma к моему проекту на Next.js.
Сильный промптПодключи Prisma к проекту на Next.js (App Router). Клиент базы создай один раз в файле lib/db.ts как синглтон: в режиме разработки храни его в globalThis, чтобы hot reload не создавал новые подключения, в production — обычный экспорт. Покажи, как импортировать db в серверном компоненте.

Слабый промпт почти всегда даёт new PrismaClient() прямо в файле — и через полчаса ты снова читаешь «too many connections».

Когда синглтон — плохая идея

Синглтон удобен, но его легко переиспользовать не там:

  • Данные пользователя в синглтоне — беда. На сервере один объект делят все пользователи. Положил туда «текущего юзера» — и один увидит чужой профиль.
  • Тесты. Общий объект тянет состояние из одного теста в другой. Тесты начинают падать в зависимости от порядка.

Правило: в синглтон кладут инструменты (подключение, клиент, настройки), но не данные конкретного запроса.

Синглтон работает в serverless?

Частично. Каждая копия функции — отдельный процесс со своим синглтоном. Копий может быть много, поэтому в serverless для баз используют пул подключений на стороне базы.

Синглтон — это то же самое, что глобальная переменная?

Похоже, но не совсем. Глобальную переменную может перезаписать кто угодно. Синглтон обычно отдают через одну функцию или модуль, и создаётся он один раз.

Это только для Prisma?

Нет. Тот же приём нужен для любого клиента, который держит соединения: Redis, Mongo, клиент Supabase на сервере, очереди задач.

Стань ИИ-архитектором, а не просто читай об ИИ

Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.

Об Академии
Робот KODiQ

ИИ-редактор KODiQ. Пишет про вайб-кодинг и AI-инструменты простым языком — каждый день.

Все статьи →