Як виправити помилку «Connection Refused» у PostgreSQL на localhost:5432

Якщо PostgreSQL видає помилку «connection refused» на localhost:5432, перше, що потрібно виправити, — це доступність, а не пароль. Виконайте команду pg_isready -h localhost -p 5432. Якщо вона повідомляє no response, зазвичай це означає, що PostgreSQL зупинено, він прослуховує інший порт або адресу, працює в іншому середовищі (наприклад, у Docker) або не може запуститися. Якщо вона повідомляє accepting connections, сервер доступний, і вам слід припинити розглядати проблему як відмову порту та досліджувати наступне повідомлення про помилку.

PostgreSQL за замовчуванням використовує TCP-порт 5432, і поточна документація PostgreSQL 18 вказує, що значення listen_addresses за замовчуванням дорівнює localhost. Станом на 11 вересня 2026 року PostgreSQL 18 є поточним стабільним основним випуском, а версія PostgreSQL 18.6 була випущена 13 серпня 2026 року; PostgreSQL 19 Beta 3 досі є розробницьким випуском. Наведені нижче кроки усунення несправностей загалом застосовні до підтримуваних версій PostgreSQL, але назви пакетів, служб та розташування файлів відрізняються залежно від операційної системи та інсталятора. Перегляньте офіційне оголошення про випуск PostgreSQL 18.6 та поточну документацію щодо налаштувань з'єднання.

1. Переконайтеся, що помилка дійсно «Connection Refused»

Почніть з точного тексту помилки. Кілька збоїв з'єднання з PostgreSQL звучать подібно, але вказують на різні шари стека.

Це розрізнення запобігає типовій помилці: редагуванню паролів або pg_hba.conf, коли нічого не прослуховує порт 5432. Ці налаштування мають значення лише після того, як з'єднання досягне сервера PostgreSQL.

2. Виконайте pg_isready для точного хоста та порту

pg_isready — це власна утиліта статусу з'єднання PostgreSQL. Виконайте:

pg_isready -h localhost -p 5432

PostgreSQL документує чотири стани виходу: 0, коли сервер приймає з'єднання, 1, коли він відхиляє з'єднання, 2, коли немає відповіді, і 3, коли не було зроблено жодної дійсної спроби. Вам не потрібні правильні ім'я бази даних, ім'я користувача чи пароль, щоб отримати базовий статус сервера. Перегляньте офіційну довідку pg_isready.

Якщо ви отримаєте:

• localhost:5432 - accepting connections: порт 5432 доступний. Спробуйте ваше реальне з'єднання psql або додатку та усуньте нове повідомлення про помилку, якщо воно виникне.
• localhost:5432 - rejecting connections: сервер відповів, але ще не приймає звичайні з'єднання, що може статися під час запуску або відновлення. Перевірте журнал сервера та зачекайте, якщо запуск дійсно триває.
• localhost:5432 - no response: продовжуйте перевірки сервера та слухача нижче.

Також явно протестуйте 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Якщо 127.0.0.1 працює, а localhost — ні, проблема, ймовірніше, пов'язана з розв'язанням імен або прив'язкою IPv4/IPv6, ніж з повним відключенням PostgreSQL.

3. Переконайтеся, що сервер PostgreSQL запущено

Якщо ви встановили PostgreSQL через пакет операційної системи або інсталятор, використовуйте звичайний механізм керування службами цього пакету. Документація PostgreSQL рекомендує використовувати інфраструктуру запуску з пакета, коли вона доступна, замість винайдення окремого методу запуску.

Якщо ви керуєте кластером безпосередньо і знаєте його каталог даних, PostgreSQL надає pg_ctl:

pg_ctl status -D /path/to/data
pg_ctl start -D /path/to/data -l /path/to/postgresql.log

Значення -D повинно вказувати на правильний каталог даних PostgreSQL, який є каталогом для цього кластера бази даних. Якщо налаштовано PGDATA, pg_ctl може використовувати його замість цього. Офіційна документація pg_ctl описує команди status, start, restart та reload.

Windows

Відкрийте Служби (Services) і знайдіть службу PostgreSQL, створену вашим інсталятором. Якщо вона зупинена, запустіть її. Якщо встановлено кілька версій PostgreSQL, переконайтеся, що ви запускаєте екземпляр, пов'язаний з каталогом даних та портом, який очікує ваш додаток.

Linux

Назви пакетів відрізняються серед дистрибутивів. Пакетна установка може надавати системну службу, таку як postgresql, або модуль, специфічний для версії/кластера. Використовуйте визначення служби пакета, а не припускайте одну універсальну назву служби.

macOS

Правильний механізм запуску залежить від того, чи походить PostgreSQL з пакету додатку, Homebrew, MacPorts, вихідного коду чи іншого пакету. Той самий принцип застосовується: запустіть екземпляр за допомогою механізму, який його створив, а потім повторно виконайте pg_isready.

Якщо сервер одразу знову зупиняється, не продовжуйте його перезапускати. Перевірте його журнал запуску. Неправильне значення конфігурації, недоступний каталог даних, конфлікт портів, відсутній файл або проблема відновлення можуть заважати PostgreSQL залишатися запущеним.

4. Перевірте, чи щось дійсно прослуховує порт 5432

Запущеного процесу PostgreSQL недостатньо, якщо він прив'язаний до іншого порту або лише до сокета домену Unix. Перевірте таблицю слухачів операційної системи.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Якщо слухача немає, то або PostgreSQL не запущено, або він використовує інший порт, або прив'язаний в іншому місці, або не зміг запуститися. Якщо інша програма володіє портом 5432, PostgreSQL може не мати можливості прив'язатися до цього порту. Перевірте журнал запуску PostgreSQL, перш ніж вирішувати, чи зупиняти інший процес, чи переміщувати PostgreSQL на інший порт.

Якщо ви навмисно налаштували PostgreSQL на порт 5433, наприклад, ваш клієнт повинен використовувати 5433:

psql -h localhost -p 5433 -U postgres

Не «виправляйте» навмисно нестандартний порт, повертаючи PostgreSQL на 5432, якщо це дійсно не є бажаною архітектурою.

5. Перевірте postgresql.conf: listen_addresses та port

Налаштування listen_addresses у PostgreSQL контролює, які інтерфейси TCP/IP приймають спроби з'єднання. Документоване значення за замовчуванням — localhost. Налаштування port за замовчуванням дорівнює 5432. Обидва налаштування застосовуються при запуску сервера, тому зміни вимагають перезапуску сервера.

Для суто локальної бази даних розробки відповідні налаштування зазвичай виглядають так:

listen_addresses = 'localhost'
port = 5432

Якщо listen_addresses є порожнім рядком, PostgreSQL не прослуховує жодного IP-інтерфейсу, і можна використовувати лише сокети домену Unix там, де вони підтримуються. Навпаки, встановлення listen_addresses = '*' змушує PostgreSQL прослуховувати всі доступні інтерфейси; це зазвичай непотрібно для бази даних розробки, доступної лише через localhost, і може збільшити вразливість, якщо правила автентифікації та брандмауера не розроблені для віддаленого доступу.

Якщо ви можете підключитися через сокет домену Unix, але TCP на localhost не працює, запитайте активний сервер, щоб знайти активні файли та налаштування:

SHOW config_file;
SHOW hba_file;
SHOW listen_addresses;
SHOW port;

Це безпечніше, ніж редагувати перший знайдений postgresql.conf, особливо на машині з кількома кластерами або версіями PostgreSQL. PostgreSQL підтримує конфігураційні файли поза каталогом даних, тому шляхи до файлів не є універсальними. Перегляньте офіційну документацію щодо розташування конфігураційних файлів.

6. Якщо PostgreSQL працює в Docker, «localhost» залежить від того, де працює клієнт

Мережа контейнерів змінює значення імені хоста. Це одна з найпоширеніших причин, чому база даних працює нормально, а додаток все одно отримує відмову у з'єднанні.

Додаток працює на машині хоста

Контейнеру PostgreSQL потрібен опублікований порт хоста. Служба Compose може містити:

services:
  db:
    image: postgres:18
    ports:
      - "5432:5432"

Тоді клієнт, що працює на вашому хості, може використовувати:

postgresql://postgres:YOUR_PASSWORD@localhost:5432/YOUR_DB

Додаток працює в іншому контейнері Compose

Всередині контейнера додатку localhost посилається на сам контейнер додатку, а не на контейнер бази даних. Docker Compose надає DNS для імен служб, тому, якщо служба бази даних називається db, додаток зазвичай підключається до:

postgresql://postgres:YOUR_PASSWORD@db:5432/YOUR_DB

Офіційна документація Docker щодо мережі Compose явно розрізняє ім'я служби між контейнерами та опублікований порт хоста. Наприклад, якщо ви маппите 8001:5432, контейнери все одно використовують db:5432, тоді як хост використовує localhost:8001. Перегляньте офіційний посібник Docker щодо мережі Compose.

Перш ніж редагувати сам PostgreSQL, перевірте:

docker compose ps
docker compose logs db

Якщо контейнер перезапускається, журнал зазвичай більш цінний, ніж повторна зміна рядків з'єднання.

7. Розглядайте правила брандмауера як пізнішу перевірку для відмови на localhost

Для клієнта та сервера на одній машині не починайте з відкриття порту 5432 для всієї мережі. Спочатку переконайтеся, що PostgreSQL прослуховує локально. Широке правило брандмауера може створити непотрібну вразливість, не виправляючи зупинений сервер.

Розслідування брандмауера стає більш актуальним, коли:

• PostgreSQL знаходиться у ВМ, хості контейнера, середовищі WSL або іншому мережевому просторі імен.
• Ви змінили listen_addresses, щоб дозволити з'єднання, що не є петльовими.
• Локальне програмне забезпечення безпеки застосовує правила до петльового інтерфейсу або процесів додатків.
• Слухач існує і працює з одного середовища, але не з іншого.

Якщо віддалений доступ є навмисним, обмежте дозволені мережі джерел та правила автентифікації тим, що дійсно потрібно. Доступність порту 5432 звідусіль не є передумовою для локального додатку.

8. Не редагуйте pg_hba.conf, доки сервер не стане доступним

pg_hba.conf контролює автентифікацію клієнтів PostgreSQL. Запис host застосовується до з'єднань TCP/IP. Він не змушує зупинений сервер почати прослуховування, тому зазвичай це неправильне перше рішення для connection refused.

Як тільки pg_isready повідомить, що сервер приймає з'єднання, помилка автентифікації може справедливо спрямувати вас до pg_hba.conf. Для TCP-з'єднань localhost правила зазвичай обмежені петльовими адресами, такими як 127.0.0.1/32 та ::1/128, з вибором бази даних, ролі та методу автентифікації для вашого середовища.

PostgreSQL 18 встановлює password_encryption за замовчуванням у scram-sha-256, і його документація позначає паролі, зашифровані MD5, як застарілі. Уникайте сліпого копіювання старих прикладів автентифікації. Перегляньте поточну документацію pg_hba.conf та поточні налаштування автентифікації.

На системах Unix-подібного типу зміни до pg_hba.conf можна перезавантажити за допомогою pg_ctl reload або SELECT pg_reload_conf();. PostgreSQL документує специфічну для Windows відмінність: зміни до pg_hba.conf застосовуються до наступних нових з'єднань без тієї ж вимоги SIGHUP.

9. Тестуйте за допомогою psql після того, як слухач стане здоровим

Як тільки pg_isready скаже, що сервер приймає з'єднання, протестуйте той самий шлях, який очікує ваш додаток:

psql -h localhost -p 5432 -U postgres -d postgres

Успішний запит psql повідомляє вам набагато більше, ніж «служба працює»: він підтверджує, що реальний клієнт PostgreSQL досяг сервера і пройшов етапи з'єднання та автентифікації для цих параметрів.

Якщо psql працює, але ваш додаток все ще повідомляє про відмову у з'єднанні, порівняйте конфігурацію додатку символ за символом:

• Ім'я хоста
• Порт
• Ім'я бази даних
• Ім'я користувача
• Чи працює додаток на хості, у Docker, у ВМ чи в іншому середовищі
• Змінні середовища, завантажені фактичним запущеним процесом
• Чи був додаток перезапущений після зміни рядка з'єднання

Типовим прикладом є локальний термінал, який успішно використовує localhost:5432, тоді як веб-додаток у Docker також використовує localhost:5432. У такому випадку веб-додаток викликає сам себе, а не службу бази даних. У цьому випадку зміна хоста бази даних контейнера на ім'я служби Compose є відповідним виправленням.

10. Читайте журнал сервера, якщо PostgreSQL не може залишатися запущеним

Якщо служба запускається і одразу завершується, мережева помилка є лише симптомом. Журнал запуску — це місце, де PostgreSQL пояснює, чому він не зміг стати готовим.

Шукайте повідомлення про:

• Адресу або порт, які вже використовуються
• Неправильний синтаксис postgresql.conf
• Відсутній або недоступний каталог даних
• Проблеми з власністю файлів або дозволами
• Проблеми відновлення або WAL
• Несумісність каталогу даних та основної версії сервера

Якщо ви запускаєте кластер, керований безпосередньо, за допомогою pg_ctl, PostgreSQL рекомендує захоплювати вивід сервера, наприклад, за допомогою -l logfile. Документація щодо запуску сервера проєкту пояснює, чому вивід запуску корисний для діагностики.

Швидка діагностика за сценаріями

Типові виправлення, які можуть погіршити ситуацію

Встановлення listen_addresses у '*' без причини

Це може зробити PostgreSQL доступним з додаткових інтерфейсів, але це не потрібно для нормального з'єднання localhost на тій самій машині. Це також може розширити вразливість. Використовуйте найвужчу прив'язку, яка відповідає вашій архітектурі.

Відкриття порту 5432 для всієї мережі

Виняток брандмауера не може змусити зупинений процес PostgreSQL прослуховувати. Спочатку підтвердіть слухача, а потім додайте лише той мережевий доступ, який вам дійсно потрібен.

Скидання пароля postgres для відмови у з'єднанні

Автентифікація за паролем відбувається після того, як клієнт досягає PostgreSQL. Якщо TCP-з'єднання відхилено, зміна пароля зазвичай вирішує неправильний шар.

Редагування неправильного postgresql.conf

Машини з кількома встановленнями можуть містити кілька конфігураційних файлів. Коли це можливо, використовуйте робоче локальне з'єднання через сокет та SHOW config_file;, або ідентифікуйте каталог даних процесу сервера, який ви дійсно збираєтеся запустити.

Припущення, що 5432 є обов'язковим

5432 — це значення за замовчуванням, а не вимога. Якщо ваш цільовий кластер налаштований на 5433, і всі клієнти використовують 5433, це дійсно. Послідовність важливіша за примусове використання значення за замовчуванням.

Коли слід змінити підхід до усунення несправностей

Ви повинні припинити працювати над «connection refused» конкретно, як тільки pg_isready повідомляє про прийняття з'єднань або psql досягає помилки автентифікації/бази даних. У цей момент мережевий слухач виконує свою роботу, і продовження зміни портів, правил брандмауера або listen_addresses може створити нові проблеми.

Так само, якщо PostgreSQL не може запуститися, перейдіть від усунення несправностей на стороні клієнта до діагностики запуску сервера. Якщо контейнер постійно перезапускається, перейдіть до журналу контейнера. Якщо клієнт на хості працює, а клієнт у контейнері — ні, перейдіть до DNS контейнера та маппінгу портів. Корисне питання не «Яке налаштування PostgreSQL мені переключити?», а «На якому шарі з'єднання перестає просуватися?»

Як виглядає успішне виправлення

Ви можете вважати проблему доступності localhost виправленою, коли всі наступні умови виконуються для середовища, яке ви дійсно використовуєте:

1. pg_isready -h localhost -p 5432 повідомляє accepting connections, або повідомляє еквівалентний хост/порт, який ви навмисно налаштували.
2. Операційна система показує, що PostgreSQL прослуховує очікувану адресу та порт.
3. psql може досягти сервера, використовуючи той самий мережевий шлях, що й додаток.
4. Ваш додаток більше не отримує connection refused.
5. Якщо з'являється інша помилка PostgreSQL, ви усуваєте цю нову помилку окремо, а не продовжуєте модифікувати слухача.

Важливо розуміти межі цієї процедури: вона діагностує, чи можна досягти сервера PostgreSQL на очікуваному хості та порту. Сама по собі вона не може виправити недійсний пароль, відсутню роль, відсутню базу даних, помилку SQL, проблему зі схемою або помилку пулу з'єднань додатку. Це стає актуальним лише після того, як з'єднання пройде етап відмови.

Для більшості випадків localhost найкоротший шлях залишається тим самим: протестуйте 5432 за допомогою pg_isready, підтвердіть, що цільовий екземпляр PostgreSQL запущено, перевірте слухача і лише потім змінюйте конфігурацію. Такий порядок зосереджує усунення несправностей і зменшує ймовірність перетворення простої проблеми зупиненої служби на більшу мережеву або проблему безпеки.