Гайды

Почему не подключается база данных — три причины и как отличить их за минуту

Иллюстрация: пучок проводов, которые не влезают в одну розетку

Локально всё работает. Выкатил — база не подключается. И самое обидное: ошибка звучит так, будто у тебя наплыв пользователей, хотя пользователь ты один.

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

Причина 1: соединений слишком много (даже если пользователь ты один)

Симптом: FATAL: sorry, too many clients already, Max client connections reached, remaining connection slots are reserved.

Почему так. PostgreSQL на каждое соединение поднимает отдельный процесс — не поток, а полноценный процесс со своей памятью. Поэтому соединения дороги и их немного: на маленьких инстансах лимит бывает в районе шести десятков.

А теперь наложи на это serverless. Каждый холодный старт функции — это новый экземпляр приложения, и он открывает свой пул соединений. Десяток параллельных запросов легко превращается в десяток пулов по 5–10 соединений. Лимит выбран, и виноват не трафик, а арифметика.

Второй классический случай — клиент базы, созданный внутри обработчика запроса. Тогда каждое обращение открывает новое соединение и часто не закрывает его.

Как проверить. Выполни в SQL-редакторе два запроса:

show max_connections;
select count(*) from pg_stat_activity;

Если второе число подобралось к первому — диагноз подтверждён.

Как починить.

  • Подключайся через пулер в режиме транзакций. У Supabase это отдельный хост и порт 6543 — он держит горячие соединения и раздаёт их на время запроса, а не на время жизни функции.
  • В serverless ставь размер пула приложения в 1–2 соединения. Большой пул внутри функции бессмыслен: параллелизм там дают экземпляры, а не пул.
  • Создавай клиента один раз на модуль, а не внутри обработчика.

Причина 2: адрес есть, но сети до него нет

Симптом: connect ENETUNREACH, зависание до таймаута, ETIMEDOUT. При этом с ноутбука та же строка подключается прекрасно.

Почему так. Прямое подключение к базе у некоторых хостингов (в том числе у Supabase) живёт на IPv6. Твой домашний провайдер IPv6, скорее всего, умеет. А вот сеть хостинга, где крутится бэкенд, — далеко не всегда.

Получается фокус: одна и та же строка работает у тебя и не работает на сервере. Логично заподозрить пароль или файрвол, а дело в версии протокола.

Как проверить. Возьми ту же строку подключения и запусти её не локально, а из окружения, где падает, — например, во временной задаче на том же хостинге. Если локально работает, а там ENETUNREACH — это оно.

Как починить. Перейди на строку через пулер: у него есть адрес по IPv4. Для постоянно живущего сервера бери session-режим пулера, для функций — транзакционный. Отдельный IPv4-адрес для прямого подключения обычно продаётся как платная опция, но в 99% случаев он не нужен.

Причина 3: строка подключения врёт

Симптом: password authentication failed for user "postgres", database does not exist, getaddrinfo ENOTFOUND.

Тут три подварианта, и все — про копипаст.

  • Плейсхолдер не заменён. В строке так и осталось [YOUR-PASSWORD]. Смешно, но это причина номер один среди «паролей не подходит».
  • Спецсимволы в пароле не закодированы. Строка подключения — это URL. Если в пароле есть @, #, / или :, их нужно закодировать: @ превращается в %40, # в %23. Иначе парсер решит, что хост начинается посреди пароля — отсюда и странный ENOTFOUND.
  • Переменная окружения не доехала. Код читает пустую строку и подставляет дефолтный localhost. Проверь это первым делом — как именно, разобрано в статье почему не работают переменные окружения.

Как проверить. Выведи в лог не сам пароль, а его длину и первые символы хоста. Если длина нулевая — переменная не дошла. Если хост неожиданный — строка распарсилась не так, как ты думал.

Порядок отладки, который экономит вечер

  1. Подключись к базе клиентом со своей машины — так ты убедишься, что база вообще жива и пароль верный.
  2. Подключись той же строкой из окружения, где падает. Разница между шагами 1 и 2 — это почти всегда сеть или пулер.
  3. Только потом лезь в код приложения.

Половина потерянных вечеров — это отладка кода в ситуации, где не работал шаг 2. Если базу ты только заводишь, полезно пройти гайд по подключению базы к приложению — там строка подключения собирается по шагам.

Почему локально всё работает, а на сервере нет?

Потому что локально другой доступ к сети, другие переменные окружения и один экземпляр приложения вместо десяти. Три отличия — три причины из этой статьи.

Пулер решает все проблемы с соединениями?

Нет. Он снимает лимит клиентов и даёт IPv4, но не спасает от кода, который открывает соединение и не отпускает. Ещё в транзакционном режиме недоступны сессионные вещи вроде подготовленных запросов и LISTEN.

Сколько соединений нужно моему приложению?

Меньше, чем кажется. Обычному бэкенду хватает пула на 5–10 соединений, функции — 1–2. Больше соединений не ускоряют базу, а отнимают у неё память.

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

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

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

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

Все статьи →