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

Локально всё работает. Выкатил — база не подключается. И самое обидное: ошибка звучит так, будто у тебя наплыв пользователей, хотя пользователь ты один.
Хорошая новость: у этой поломки всего три частые причины, и они различаются по тексту ошибки. Не гадай — прочитай симптом и иди сразу в нужный раздел.
Причина 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 — это почти всегда сеть или пулер.
- Только потом лезь в код приложения.
Половина потерянных вечеров — это отладка кода в ситуации, где не работал шаг 2. Если базу ты только заводишь, полезно пройти гайд по подключению базы к приложению — там строка подключения собирается по шагам.
Почему локально всё работает, а на сервере нет?
Потому что локально другой доступ к сети, другие переменные окружения и один экземпляр приложения вместо десяти. Три отличия — три причины из этой статьи.
Пулер решает все проблемы с соединениями?
Нет. Он снимает лимит клиентов и даёт IPv4, но не спасает от кода, который открывает соединение и не отпускает. Ещё в транзакционном режиме недоступны сессионные вещи вроде подготовленных запросов и LISTEN.
Сколько соединений нужно моему приложению?
Меньше, чем кажется. Обычному бэкенду хватает пула на 5–10 соединений, функции — 1–2. Больше соединений не ускоряют базу, а отнимают у неё память.
Курс «Профессия 2027: ИИ-архитектор»: шаг за шагом от основ компьютера до своего приложения и первых клиентов. 543 коротких урока на телефоне.





