Как да поправите грешката „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 идва от app bundle, Homebrew, MacPorts, изходен код или друг пакет. Същият принцип се прилага: стартирайте екземпляра от механизма, който го е създал, след което изпълнете отново pg_isready.

Ако сървърът веднага спре отново, не продължавайте да го рестартирате. Инспектирайте неговия лог за стартиране. Лоша конфигурационна стойност, недостъпна директория с данни, конфликт на портове, липсващ файл или проблем с възстановяването могат да попречат на PostgreSQL да остане активен.

4. Проверете дали нещо всъщност слуша на порт 5432

Работещ процес на PostgreSQL не е достатъчен, ако е привързан към различен порт или само към Unix-domain сокет. Проверете таблицата на слушателите на операционната система.

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-domain сокети могат да се използват, където се поддържат. Обратно, задаването на listen_addresses = '*' кара PostgreSQL да слуша на всички налични интерфейси; това обикновено е ненужно за база данни за разработка само за localhost и може да увеличи излагането, ако правилата за автентикация и firewall не са проектирани за отдалечен достъп.

Ако можете да се свържете чрез Unix-domain сокет, но 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. Третирайте правилата на Firewall като по-късна проверка за отказ на localhost

За клиент и сървър на една и съща машина, не започвайте с отваряне на порт 5432 за всяка мрежа. Първо потвърдете, че PostgreSQL слуша локално. Широко правило за firewall може да създаде ненужно излагане, без да поправи спрян сървър.

Разследването на firewall става по-релевантно, когато:

• PostgreSQL е във VM, хост на контейнер, WSL среда или друго мрежово пространство от имена.
• Сте променили listen_addresses, за да разрешите връзки, които не са loopback.
• Локален софтуер за сигурност прилага правила към loopback или процеси на приложения.
• Слушателят съществува и работи от една среда, но не и от друга.

Ако отдалеченият достъп е намерен, ограничете разрешените източни мрежи и правилата за автентикация до това, което наистина е необходимо. Достъпността на порт 5432 от навсякъде не е предпоставка за локално приложение.

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

pg_hba.conf контролира автентикацията на клиентите на PostgreSQL. Запис host се прилага за TCP/IP връзки. Той не кара спрян сървър да започне да слуша, така че обикновено е грешното първо решение за connection refused.

След като pg_isready докладва, че сървърът приема връзки, грешка при автентикацията може легитимно да ви насочи към pg_hba.conf. За TCP връзки на localhost, правилата обикновено са ограничени до loopback адреси като 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

Успешният prompt на psql ви казва много повече от „услугата работи“: той потвърждава, че реален клиент на PostgreSQL е достигнал сървъра и е преминал етапите на връзка и автентикация за тези параметри.

Ако psql работи, но вашето приложение все още докладва отказ на връзката, сравнете конфигурацията на приложението символ по символ:

• Име на хост
• Порт
• Име на база данни
• Потребителско име
• Дали приложението работи на хоста, в Docker, във VM или в друга среда
• Променливи на средата, заредени от действителния работещ процес
• Дали приложението е рестартирано след промяна на неговия низ за връзка

Чест пример е локален терминал, използващ успешно localhost:5432, докато уеб приложение в Docker също използва localhost:5432. Уеб приложението тогава извиква себе си, а не услугата на базата данни. В този случай промяната на хоста на базата данни на контейнера към името на Compose услугата е релевантното решение.

10. Прочетете лога на сървъра, ако PostgreSQL няма да остане активен

Ако услугата стартира и веднага излезе, мрежовата грешка е само симптом. Логът за стартиране е мястото, където PostgreSQL обяснява защо не е могъл да стане готов.

Търсете съобщения за:

• Адрес или порт вече се използват
• Невалиден синтаксис на postgresql.conf
• Липсваща или недостъпна директория с данни
• Проблеми с притежанието или разрешенията на файловете
• Проблеми с възстановяването или WAL
• Несъвместима директория с данни и основна версия на сървъра

Ако стартирате директно управляван клъстер с pg_ctl, PostgreSQL препоръчва записването на изхода на сървъра, например с -l logfile. Документацията за стартиране на сървъра на проекта обяснява защо изходът от стартирането е полезен за диагностика.

Бърза диагностика по сценарий

Често срещани решения, които могат да влошат ситуацията

Задаване на listen_addresses на '*' без причина

Това може да направи PostgreSQL достъпен от допълнителни интерфейси, но не е необходимо за нормална връзка на localhost на една и съща машина. То също така може да разшири излагането. Използвайте най-тясното привързване, което съответства на вашата архитектура.

Отваряне на порт 5432 за цялата мрежа

Изключение в firewall не може да накара спрян процес на PostgreSQL да слуша. Потвърдете слушателя първо, след което добавете само мрежовия достъп, от който наистина имате нужда.

Нулиране на паролата на postgres за отказ на връзката

Автентикацията с парола се случва след като клиентът достигне PostgreSQL. Ако TCP връзката е отказана, промяната на паролата обикновено адресира грешния слой.

Редактиране на грешния postgresql.conf

Машини с множество инсталации могат да съдържат няколко конфигурационни файла. Където е възможно, използвайте работеща локална сокет връзка и SHOW config_file;, или идентифицирайте директорията с данни на сървърния процес, който всъщност възнамерявате да стартирате.

Приемане, че 5432 е задължителен

5432 е стандартът, а не изискване. Ако вашият желан клъстер е конфигуриран за 5433 и всеки клиент използва 5433, това е валидно. Последователността е по-важна от налагането на стандарта.

Кога трябва да промените подхода си за отстраняване на неизправности

Трябва да спрете да работите върху „connection refused“ конкретно, след като pg_isready докладва приемане на връзки или psql достигне грешка при автентикация/база данни. В този момент мрежовият слушател върши работата си, и продължаването да променяте портове, правила на firewall или 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 работи, проверете слушателя и само тогава променяйте конфигурацията. Този ред държи отстраняването на неизправности фокусирано и намалява шанса да превърнете прост проблем със спряна услуга в по-голям мрежов или проблем със сигурността.