PostgreSQL: connection refused на порту 5432

#Что значит «Connection refused»

Это отказ на уровне TCP, ещё до разговора с самой базой: соединение было отклонено на указанном адресе и порту (причина может быть и в явном сетевом запрете). Не путайте с «password authentication failed» (сервер принял вас, но не пустил) и с «timeout» (пакеты теряются файрволом). Для «refused» цепочка проверки короткая: запущена ли служба → на каком адресе слушает → пропускает ли файрвол → верный ли порт.

#Пошаговая проверка подключения

1. Уточните адрес и порт из ошибкиНа компьютере, где не удаётся подключиться, откройте полное сообщение программы или журнала. Запишите имя сервера/IP и порт после слова port (часто 5432). Сопоставьте их с настройками приложения или строкой подключения. Не меняйте адрес на localhost наугад: внутри контейнера он означает сам контейнер. Если адрес ошибочный, исправьте только его и повторите подключение.
2. Проверьте, запущен ли PostgreSQL на сервереВойдите на сервер PostgreSQL, а не на клиентский ПК. На Linux с systemd откройте терминал и выполните systemctl status postgresql --no-pager. В Debian/Ubuntu дополнительно можно выполнить pg_lsclusters, чтобы увидеть нужный кластер и порт. Для подробностей сбоя с правами администратора прочитайте sudo journalctl -u postgresql -n 50 --no-pager (если служба имеет другое имя, укажите его). В Windows нажмите Win+R, введите services.msc и найдите службу PostgreSQL соответствующей версии. Если служба не запущена, выясните причину по журналам, не удаляйте postmaster.pid и не запускайте её до проверки состояния данных.
3. Проверьте адрес, на котором сервер принимает соединенияНа Linux на самом сервере выполните sudo ss -ltnp | grep 5432, заменив 5432 на реальный порт. Запись 127.0.0.1:5432 означает, что удалённые клиенты не смогут подключаться напрямую; 0.0.0.0:5432 означает прослушивание IPv4-интерфейсов, но не гарантирует разрешённый доступ. Если доступна локальная учётная запись администратора БД, сверяйте параметры через sudo -u postgres psql -c "SHOW listen_addresses; SHOW port;". Если вывода нет, проверьте правильность порта, службы и кластера прежде, чем менять конфигурацию.
4. Проверьте путь с клиентского компьютераНа Windows-клиенте откройте PowerShell через «Пуск» и выполните Test-NetConnection 192.168.1.20 -Port 5432, подставив фактический внутренний адрес и порт. На Linux/macOS в терминале используйте nc -vz 192.168.1.20 5432 при наличии nc. Успешная проверка TCP означает, что порт достижим; затем возможны уже ошибки авторизации. При Connection refused сверяйте адрес, слушающий интерфейс, переадресацию портов и режим Docker. При тайм-ауте отдельно проверяйте маршруты и межсетевые экраны.
5. Изменяйте настройки доступа только при подтверждённой необходимостиЕсли база действительно должна принимать подключения из внутренней сети, администратор сначала создаёт резервную копию настроек, определяет нужный внутренний IP и согласует окно перезапуска. В postgresql.conf ограничьте listen_addresses нужными интерфейсами, в pg_hba.conf разрешите конкретные адреса клиентов и роли. Для изменения listen_addresses требуется перезапуск экземпляра; для pg_hba.conf на Linux/Unix — перечитывание конфигурации. Не открывайте порт 5432 всему интернету. После согласованных изменений повторите тест TCP и пробное подключение приложения.

#Шаг 1. Служба запущена?

Если служба в состоянии failed, сначала прочитайте её журнал: причиной могут быть неверные настройки, отсутствие места, ошибки прав или проблемы каталога данных. Не удаляйте postmaster.pid: наличие файла само по себе не доказывает «зависшую» базу. Запускать службу следует только после диагностики и проверки состояния кластера; включение автозапуска — отдельное эксплуатационное решение.

На Windows откройте services.msc и проверьте службу «postgresql-x64-NN», на macOS с Homebrew выполните brew services list.

#Шаг 2. На каком адресе слушает сервер

Если база должна принимать подключения только с локального компьютера, оставьте listen_addresses=localhost. Для действительно необходимых удалённых клиентов сначала уточните внутренний адрес сервера и действующий экземпляр: sudo -u postgres psql -c "SHOW config_file; SHOW listen_addresses; SHOW port;". Меняйте параметры по плану с резервной копией конфигурации и явным ограничением разрешённых адресов; pg_hba.conf управляет аутентификацией, а не исправляет TCP connection refused.

listen_addresses = 'localhost,192.168.1.20'
port = 5432

host    appdb    app    192.168.1.0/24    scram-sha-256

Изменение listen_addresses требует перезапуска именно нужного экземпляра PostgreSQL и может прервать все его соединения; согласуйте окно работ. Изменение только pg_hba.conf обычно достаточно перечитать через SELECT pg_reload_conf();. При правильном TCP-подключении, но отсутствии подходящей записи в pg_hba.conf, сервер сообщит no pg_hba.conf entry — это уже другой этап проверки.

#Шаг 3. Файрвол и порт

Проверяйте доступность с клиентской машины командой nc -vz ВНУТРЕННИЙ_IP 5432 (Linux/macOS) или Test-NetConnection ВНУТРЕННИЙ_IP -Port 5432 (PowerShell), заменив адрес на фактический. В Docker используйте имя сервиса базы внутри одной сети Compose; публиковать базу на внешнем интерфейсе ради соседнего контейнера не нужно.

#Особые случаи: Docker, WSL и облако

В Docker localhost внутри контейнера приложения не указывает на соседний контейнер: подключайтесь по имени сервиса из Compose. Для доступа только с компьютера-хоста можно привязать опубликованный порт к loopback (127.0.0.1:5432:5432) после проверки, что он свободен. В WSL2 выясните, где установлен сервер (Windows или Linux). Для облачной базы проверьте документацию провайдера, частную сеть и список разрешённых источников; не открывайте 5432 всему интернету.