PostgreSQL: connection to server on port 5432 failed: Connection refused

#Что означает ошибка

«Connection refused» — порт 5432 никто не слушает по тому адресу, к которому вы подключаетесь. Причины: служба PostgreSQL остановлена, она слушает только localhost (параметр listen_addresses), используется другой порт, либо файрвол закрывает соединение. Отказ в доступе по паролю — это уже другая ошибка (no pg_hba.conf entry, password authentication failed), поэтому её не путайте.

#Причины и решения

#Пошаговое решение

1. Проверьте службуНа компьютере клиента откройте терминал (Windows: «Пуск» → «PowerShell»; Linux: «Терминал») и запишите адрес сервера и порт из настроек приложения. Если используете psql, выполните тест с реальными значениями: psql -h 127.0.0.1 -p 5432 -U username -d dbname на самом сервере или укажите настоящий адрес сервера на клиенте. Заглушки username и dbname замените. Connection refused означает, что TCP-соединение отвергнуто; это не ошибка пароля или правил pg_hba.conf. При password authentication failed перейдите к диагностике учётной записи.
2. Проверьте портНа СЕРВЕРЕ Linux администратор через SSH выполняет systemctl status postgresql --no-pager и, для Debian/Ubuntu с несколькими кластерами, pg_lsclusters (если утилита установлена). Проверьте точное имя и состояние нужного экземпляра: агрегированная служба postgresql может быть active без рабочего кластера. Если нужный экземпляр остановлен, изучите журнал journalctl -u ИМЯ_СЛУЖБЫ -n 80 --no-pager; запуск согласуйте с ответственным за базу. На Windows откройте Win+R → services.msc и найдите службу PostgreSQL по версии.
3. Посмотрите журналНа том же сервере выполните sudo ss -ltnp (Linux) или в PowerShell Get-NetTCPConnection -State Listen (Windows) и найдите реальный TCP-порт PostgreSQL. Строка 127.0.0.1:5432 означает, что сервис слушает только IPv4 на локальном компьютере; 0.0.0.0:5432 — на всех IPv4-интерфейсах; порт может отличаться от 5432. Если строки нет, проверьте журнал PostgreSQL, успешность запуска кластера и наличие другого занятого порта. Не открывайте брандмауэр, пока сервис не начал слушать.
4. Найдите конфигурациюЕсли сервер работает локально, администратор входит в psql (на Linux с разрешённой локальной проверкой: sudo -u postgres psql) и выполняет SHOW config_file; SHOW hba_file; SHOW port; SHOW listen_addresses;. Выберите именно фактически загружаемый postgresql.conf; сначала запишите его прежнее содержимое. Для удалённого доступа назначьте listen_addresses на конкретный внутренний IP сервера или иное согласованное значение, а не бездумно '*'; настройте подходящее правило pg_hba.conf для ограниченного IP клиента, пользователя и базы с безопасным методом аутентификации. Если подключение нужно только локально, эти изменения пропустите.
5. Настройте listen_addressesПосле изменения listen_addresses PostgreSQL требует перезапуска конкретного экземпляра, который прервёт активные соединения: согласуйте окно обслуживания, сохраните резервную копию конфигурации и используйте службу нужного кластера. Для изменений только pg_hba.conf обычно достаточно перечитать конфигурацию через SELECT pg_reload_conf(); из привилегированного сеанса. Снова выполните ss -ltnp и проверьте, что слушается нужный IP/порт. При ошибке запуска верните прежнюю конфигурацию и посмотрите последние строки журнала.
6. Настройте pg_hba.confНа клиенте проверьте доступ к выбранному серверу и порту: Windows PowerShell — Test-NetConnection -ComputerName ИМЯ -Port 5432, Linux/macOS — nc -vz ИМЯ 5432 при наличии nc. TcpTestSucceeded: False или refused требует проверки маршрута, VPN и сетевых правил, только после проверки слушателя. Администратор может разрешить порт строго с IP приложения во внутреннем брандмауэре; не публикуйте порт PostgreSQL во всём интернете. Успешный TCP-тест означает только доступ к порту.
7. ПерезапуститеЕсли соединение идёт из Docker, проверьте файл Compose и настройки сети: имя localhost внутри контейнера обозначает сам этот контейнер, а не хост/другой сервис. При общей сети Compose используйте имя сервиса базы и её внутренний порт, проверьте docker compose ps и журналы PostgreSQL docker compose logs --tail=80 ИМЯ_СЕРВИСА. Не добавляйте ports: '5432:5432' ради соединения двух сервисов в одной сети: это делает порт доступным на узле без необходимости.
8. Откройте портВ конце повторите штатное подключение из приложения. В psql после успешного входа выполните SELECT current_database(), current_user; и убедитесь, что это нужная база и роль. Если теперь появляется no pg_hba.conf entry или password authentication failed, первоначальная проблема доступности порта решена, но требуется отдельное исправление правила доступа или пароля. Сохраните точный текст новой ошибки и откатите лишние изменения сетевых настроек.
9. Команды для отдельных ситуацийВыберите только подходящий вариант. Это не одна последовательность: часть команд диагностирует проблему, а часть меняет настройки или данные.
   Выберите подходящий вариант — это не команды для последовательного выполнения

   Вариант 1Только диагностика; не запускайте/перезапускайте PostgreSQL и не меняйте сеть без проверки конкретного клас…

   Linux · Терминал (Bash)С осторожностьюНужен sudoКопировать всёВыделить

   Только диагностика; не запускайте/перезапускайте PostgreSQL и не меняйте сеть без проверки конкретного кластера.

   # Диагностика на Linux-сервере (не все команды есть в каждой системе):

   systemctl status postgresql --no-pager

   ss -ltnp

   # При разрешённой локальной аутентификации администратора:

   sudo -u postgres psql -c "SHOW listen_addresses;" -c "SHOW port;"

   Команда может изменить состояние системы или её настройки. Проверьте параметры и последствия перед запуском.

   Вариант 2Фрагменты конфигурации (замените подсеть).

   INIКопировать всёВыделить

   Фрагменты конфигурации (замените подсеть).

   # postgresql.conf
   listen_addresses = 'localhost,192.168.1.10'
   port = 5432
   # pg_hba.conf
   host    all    all    192.168.1.0/24    scram-sha-256

Для удалённых подключений используйте закрытую сеть/VPN и ограниченные правила доступа. Если база доступна только на сервере, безопаснее оставить listen_addresses = localhost и подключаться через согласованный SSH-туннель. В Docker публикация порта 5432:5432 обычно не нужна контейнерам в одной внутренней сети.