Ako opraviť chybu „Connection Refused“ pri pripojení k PostgreSQL na localhoste port 5432

Ak PostgreSQL hlási „connection refused“ na localhost:5432, prvá vec, ktorú treba opraviť, je dosiahnuteľnosť, nie heslo. Spustite príkaz pg_isready -h localhost -p 5432. Ak hlási no response, PostgreSQL je zvyčajne zastavený, počúva na inom porte alebo adrese, beží v inom prostredí, ako je Docker, alebo zlyháva počas spúšťania. Ak hlási accepting connections, server je dosiahnuteľný a mali by ste prestať riešiť problém ako odmietnutie portu a namiesto toho vyšetriť ďalšiu chybovú hlášku.

PostgreSQL používa predvolene TCP port 5432 a aktuálna dokumentácia PostgreSQL 18 uvádza, že predvolená hodnota pre listen_addresses je localhost. K 11. septembru 2026 je PostgreSQL 18 aktuálnym stabilným hlavným vydaním, pričom verzia PostgreSQL 18.6 bola vydaná 13. augusta 2026; PostgreSQL 19 Beta 3 je stále vývojové vydanie. Nasledujúce kroky riešenia problémov sa všeobecne vzťahujú na podporované verzie PostgreSQL, ale názvy balíkov, názvy služieb a umiestnenia súborov sa líšia podľa operačného systému a inštalátora. Pozrite si oficiálne oznámenie o vydaní PostgreSQL 18.6 a aktuálnu dokumentáciu nastavení pripojenia.

1. Potvrďte, že chyba je skutočne „Connection Refused“

Začnite presným textom chyby. Niekoľko zlyhaní pripojenia k PostgreSQL znie podobne, ale ukazuje na rôzne vrstvy zásobníka.

Vzor správy	Čo vám to zvyčajne hovorí	Kde hľadať ďalej
connection refused	TCP pripojenie nedosiahlo počúvajúci proces PostgreSQL na danej adrese a porte	Proces servera, port, viazaná adresa, mapovanie kontajnera, lokálna sieť
timeout expired alebo žiadna odpoveď	Sieťová cesta nevyprodukovala včasnú odpoveď	Nesprávny hostiteľ, firewall, hranica kontajnera/VM, nedostupný server
password authentication failed	Dosiahli ste PostgreSQL a začala autentifikácia	Používateľ, heslo, metóda autentifikácie
no pg_hba.conf entry	Dosiahli ste PostgreSQL, ale žiadne zodpovedajúce pravidlo autentifikácie klienta nepovolilo pokus	pg_hba.conf
database ... does not exist	Server je dosiahnuteľný a autentifikácia pokročila dostatočne ďaleko na identifikáciu požiadavky na databázu	Názov databázy a reťazec pripojenia

Toto rozlíšenie zabraňuje bežnej odbočke: úprave hesiel alebo pg_hba.conf, keď na porte 5432 nič nepočúva. Tieto nastavenia sú dôležité až po tom, čo pripojenie dosiahne server PostgreSQL.

2. Spustite pg_isready proti presnému hostiteľovi a portu

pg_isready je vlastný nástroj PostgreSQL na kontrolu stavu pripojenia. Spustite:

pg_isready -h localhost -p 5432

PostgreSQL dokumentuje štyri stavy ukončenia: 0, keď server prijíma pripojenia, 1, keď odmieta pripojenia, 2, keď nie je žiadna odpoveď, a 3, keď nebol vykonaný žiadny platný pokus. Na získanie základného stavu servera nepotrebujete správny názov databázy, používateľské meno ani heslo. Pozrite si oficiálnu referenciu pg_isready.

Ak dostanete:

• localhost:5432 - accepting connections: port 5432 je dosiahnuteľný. Skúste svoje skutočné pripojenie psql alebo aplikácie a ak zlyhá, riešte novú hlášku.
• localhost:5432 - rejecting connections: server odpovedal, ale zatiaľ neprijíma normálne pripojenia, čo môže nastať počas spúšťania alebo obnovy. Skontrolujte log servera a počkajte, ak je spúšťanie legitímne v procese.
• localhost:5432 - no response: pokračujte kontrolami servera a počúvajúceho procesu nižšie.

Tiež explicitne otestujte 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Ak 127.0.0.1 funguje, ale localhost nie, problém je pravdepodobnejšie spojený s prevodom názvov alebo viazaním IPv4/IPv6 než s úplným výpadkom PostgreSQL.

3. Uistite sa, že server PostgreSQL beží

Ak ste nainštalovali PostgreSQL prostredníctvom balíka operačného systému alebo inštalátora, použite bežný mechanizmus správy služieb daného balíka. Vlastná dokumentácia PostgreSQL odporúča používať zabalenú infraštruktúru spúšťania, ak je k dispozícii, namiesto vymýšľania samostatnej metódy spúšťania.

Ak spravujete klastre priamo a poznáte jeho dátový adresár, PostgreSQL poskytuje pg_ctl:

pg_ctl status -D /cesta/k/datum
pg_ctl start -D /cesta/k/datum -l /cesta/k/postgresql.log

Hodnota -D musí ukazovať na správny dátový adresár PostgreSQL, čo je adresár pre daný databázový klastre. Ak je nakonfigurovaná premenná PGDATA, pg_ctl ju môže použiť namiesto toho. Oficiálna dokumentácia pg_ctl opisuje príkazy status, start, restart a reload.

Windows

Otvorte Služby a vyhľadajte službu PostgreSQL vytvorenú vaším inštalátorom. Ak je zastavená, spustite ju. Ak je nainštalovaných viacero verzií PostgreSQL, overte, či spúšťate inštanciu spojenú s dátovým adresárom a portom, ktorý vaša aplikácia očakáva.

Linux

Názvy balíkov sa medzi distribúciami líšia. Zabalená inštalácia môže ponúknuť systémovú službu, ako je postgresql, alebo konkrétnu jednotku pre verziu/klastre. Použite definíciu služby balíka namiesto predpokladania jedného univerzálneho názvu služby.

macOS

Správny mechanizmus spúšťania závisí od toho, či PostgreSQL pochádza z balíka aplikácie, Homebrew, MacPorts, zdroja alebo iného balíka. Platí rovnaký princíp: spustite inštanciu z mechanizmu, ktorý ju vytvoril, a potom znova spustite pg_isready.

Ak sa server okamžite znova zastaví, nepokračujte v jeho reštartovaní. Preskúmajte jeho log spúšťania. Nesprávna konfiguračná hodnota, nedostupný dátový adresár, konflikt portov, chýbajúci súbor alebo problém s obnovou môžu zabrániť tomu, aby PostgreSQL zostal aktívny.

4. Overte, či niečo skutočne počúva na porte 5432

>Bežiaci proces PostgreSQL nestačí, ak je viazaný na iný port alebo iba na Unix-domain socket. Skontrolujte tabuľku počúvajúcich procesov operačného systému.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Ak neexistuje žiadny počúvajúci proces, buď PostgreSQL nebeží, používa iný port, je viazaný niekde inde, alebo sa nepodarilo spustiť. Ak vlastní port 5432 iný program, PostgreSQL nemusí byť schopný viazať tento port. Pred rozhodnutím, či zastaviť iný proces, alebo presunúť PostgreSQL na iný port, skontrolujte log spúšťania PostgreSQL.

Ak ste zámerne nakonfigurovali PostgreSQL na porte 5433, napríklad, váš klient musí použiť 5433:

psql -h localhost -p 5433 -U postgres

Nesnažte sa „opraviť“ zámerne nenastavený predvolený port zmenou PostgreSQL späť na 5432, pokiaľ to nie je skutočne vaša požadovaná architektúra.

5. Skontrolujte postgresql.conf: listen_addresses a port

Nastavenie listen_addresses v PostgreSQL kontroluje, ktoré rozhrania TCP/IP prijímajú pokusy o pripojenie. Dokumentovaná predvolená hodnota je localhost. Nastavenie port má predvolenú hodnotu 5432. Obe nastavenia sa aplikujú pri spustení servera, takže zmeny vyžadujú reštart servera.

Pre prísne lokálnu vývojovú databázu relevantné nastavenia zvyčajne vyzerajú takto:

listen_addresses = 'localhost'
port = 5432

Ak je listen_addresses prázdny reťazec, PostgreSQL nepočúva na žiadnom IP rozhraní a na podporovaných systémoch sa dajú použiť iba Unix-domain sokety. Naopak, nastavenie listen_addresses = '*' žiada PostgreSQL, aby počúval na všetkých dostupných rozhraniach; to je zvyčajne zbytočné pre lokálnu vývojovú databázu a môže zvýšiť expozíciu, ak autentifikácia a pravidlá firewallu nie sú navrhnuté pre vzdialený prístup.

Ak sa môžete pripojiť cez Unix-domain soket, ale TCP na localhoste zlyhá, dotazujte sa živého servera, aby ste našli aktívne súbory a nastavenia:

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

Toto je bezpečnejšie ako úprava prvého nájdeného postgresql.conf, najmä na počítači s viacerými klastermi alebo verziami PostgreSQL. PostgreSQL podporuje konfiguračné súbory mimo dátového adresára, takže cesty k súborom nie sú univerzálne. Pozrite si oficiálnu dokumentáciu o umiestnení konfiguračných súborov.

6. Ak beží PostgreSQL v Dockeri, „localhost“ závisí od toho, kde beží klient

Sieťovanie kontajnerov mení význam názvu hostiteľa. Toto je jeden z najbežnejších dôvodov, prečo je databáza zdravá, ale aplikácia stále dostáva odmietnutie pripojenia.

Aplikácia beží na hostiteľskom počítači

Kontajner PostgreSQL potrebuje publikovaný hostiteľský port. Služba Compose môže obsahovať:

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

Potom klient bežiaci na vašom hostiteľovi môže použiť:

postgresql://postgres:VAŠE_HESLO@localhost:5432/VAŠA_DB

Aplikácia beží v inom kontajneri Compose

Vnútri kontajnera aplikácie sa localhost vzťahuje na samotný kontajner aplikácie, nie na kontajner databázy. Docker Compose poskytuje DNS názvy služieb, takže ak je služba databázy pomenovaná db, aplikácia sa zvyčajne pripája k:

postgresql://postgres:VAŠE_HESLO@db:5432/VAŠA_DB

Oficiálna dokumentácia siete Docker Compose explicitne rozlišuje medzi názvom služby pre komunikáciu kontajner-kontajner a publikovaným portom hostiteľa. Napríklad, ak mapujete 8001:5432, kontajnery stále používajú db:5432, zatiaľ čo hostiteľ používa localhost:8001. Pozrite si oficiálnu príručku siete Docker Compose.

Pred úpravou samotného PostgreSQL skontrolujte:

docker compose ps
docker compose logs db

Ak sa kontajner reštartuje, log je zvyčajne cennejší ako opakované zmeny reťazcov pripojenia.

7. Pravidlá firewallu považujte za neskoršiu kontrolu pri odmietnutí na localhoste

Pre klienta a server na rovnakom počítači nezačínajte otváraním portu 5432 pre celú sieť. Najprv potvrďte, že PostgreSQL lokálne počúva. Široké pravidlo firewallu môže vytvoriť zbytočnú expozíciu bez vyriešenia zastaveného servera.

Vyšetrovanie firewallu sa stáva relevantnejším, keď:

• PostgreSQL je vo VM, hostiteľovi kontajnera, prostredí WSL alebo inom sieťovom priestore.
• Zmenili ste listen_addresses na povolenie pripojení mimo loopback.
• Lokálny bezpečnostný softvér aplikuje pravidlá na loopback alebo procesy aplikácií.
• Počúvajúci proces existuje a funguje z jedného prostredia, ale nie z druhého.

Ak je vzdialený prístup zámerne, obmedzte povolené zdrojové siete a pravidlá autentifikácie na to, čo je skutočne potrebné. Dosiahnuteľnosť portu 5432 odkiaľkoľvek nie je predpokladom pre lokálnu aplikáciu.

8. Neupravujte pg_hba.conf, kým nie je server dosiahnuteľný

pg_hba.conf kontroluje autentifikáciu klientov PostgreSQL. Záznam host sa vzťahuje na pripojenia TCP/IP. Nespôsobí, že zastavený server začne počúvať, takže je zvyčajne nesprávnou prvou opravou pre connection refused.

Akonáhle pg_isready hlási, že server prijíma pripojenia, chyba autentifikácie vás môže oprávnene viesť k pg_hba.conf. Pre TCP pripojenia na localhost sú pravidlá zvyčajne obmedzené na loopback adresy, ako sú 127.0.0.1/32 a ::1/128, s databázou, rolou a metódou autentifikácie zvolenou pre vaše prostredie.

PostgreSQL 18 nastavuje predvolene password_encryption na scram-sha-256 a jeho dokumentácia označuje MD5 šifrované heslá za zastarané. Vyhnite sa slepému kopírovaniu starých príkladov autentifikácie. Pozrite si aktuálnu dokumentáciu pg_hba.conf a aktuálne nastavenia autentifikácie.

Na Unixových systémoch možno zmeny v pg_hba.conf znova načítať pomocou pg_ctl reload alebo SELECT pg_reload_conf();. PostgreSQL dokumentuje rozdiel špecifický pre Windows: zmeny v pg_hba.conf sa aplikujú na nasledujúce nové pripojenia bez rovnakej požiadavky SIGHUP.

9. Testujte pomocou psql po tom, čo je počúvajúci proces zdravý

Akonáhle pg_isready povie, že server prijíma pripojenia, otestujte rovnakú cestu, ktorú očakáva vaša aplikácia:

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

Úspešný prompt psql vám povie oveľa viac než len „služba beží“: potvrdzuje, že skutočný klient PostgreSQL dosiahol server a prešiel fázami pripojenia a autentifikácie pre tieto parametre.

Ak psql funguje, ale vaša aplikácia stále hlási odmietnutie pripojenia, porovnajte konfiguráciu aplikácie znak po znaku:

• Názov hostiteľa
• Port
• Názov databázy
• Používateľské meno
• Či aplikácia beží na hostiteľovi, v Dockeri, vo VM alebo v inom prostredí
• Premenné prostredia načítané skutočným bežiacim procesom
• Či bola aplikácia reštartovaná po zmene jej reťazca pripojenia

Bežným príkladom je lokálny terminál, ktorý úspešne používa localhost:5432, zatiaľ čo web aplikácia v Dockeri tiež používa localhost:5432. Web aplikácia potom volá sama seba, nie službu databázy. V takom prípade je relevantnou opravou zmena hostiteľa databázy kontajnera na názov služby Compose.

10. Prečítajte si log servera, ak PostgreSQL nechce zostať aktívny

Ak sa služba spustí a okamžite ukončí, sieťová chyba je iba symptóm. Log spúšťania je miesto, kde PostgreSQL vysvetľuje, prečo sa nemohol stať pripraveným.

Hľadajte správy o:

• Adrese alebo porte už používanom
• Neplatnej syntaxi postgresql.conf
• Chýbajúcom alebo nedostupnom dátovom adresári
• Problémoch s vlastníctvom súborov alebo povoleniami
• Problémoch s obnovou alebo WAL
• Nekompatibilnom dátovom adresári a hlavnej verzii servera

Ak spúšťate priamo spravovaný klastre pomocou pg_ctl, PostgreSQL odporúča zachytiť výstup servera, napríklad pomocou -l logfile. Dokumentácia spúšťania servera projektu vysvetľuje, prečo je výstup spúšťania užitočný na diagnostiku.

Rýchla diagnostika podľa scenára

Situácia	Najužitočnejšia prvá kontrola	Pravdepodobný smer
Nová lokálna inštalácia; 5432 odmieta	pg_isready -h localhost -p 5432	Služba sa nemusela spustiť alebo môže používať iný port
Včera fungovalo; reštart počítača	Stav služby a log PostgreSQL	Služba sa nespustila automaticky alebo spúšťanie teraz zlyháva
psql na hostiteľovi funguje; aplikácia Docker zlyháva	Preskúmajte hostiteľa pripojenia aplikácie	Použite názov služby Compose namiesto localhost vnútri kontajnera
Unix soket funguje; -h localhost zlyháva	SHOW listen_addresses; a SHOW port;	TCP počúvajúci proces je zakázaný alebo viazaný inak
5432 má počúvajúci proces, ale nie je to PostgreSQL	Identifikujte proces vlastniaci port	Vyriešte konflikt portov alebo použite nakonfigurovaný port PostgreSQL
Chyba sa zmenila na zlyhanie hesla	Prestaňte meniť sieťové nastavenia	Dosiahnuteľnosť je opravená; riešte autentifikáciu
Chyba sa zmenila na no pg_hba.conf entry	Skontrolujte zodpovedajúce pravidlá HBA	Dosiahnuteľnosť je opravená; riešte autorizáciu klienta

Bežné opravy, ktoré môžu situáciu zhoršiť

Nastavenie listen_addresses na '*' bez dôvodu

To môže sprístupniť PostgreSQL z ďalších rozhraní, ale nie je to nevyhnutné pre normálne pripojenie localhost na rovnakom počítači. Môže to tiež rozšíriť expozíciu. Použite najužšie viazanie, ktoré zodpovedá vašej architektúre.

Otvorenie portu 5432 pre celú sieť

Výnimka vo firewalle nemôže prinútiť zastavený proces PostgreSQL, aby počúval. Najprv potvrďte počúvajúci proces, potom pridajte iba prístup k sieti, ktorý skutočne potrebujete.

Obnovenie hesla postgres pre odmietnutie pripojenia

Autentifikácia heslom sa deje po tom, čo klient dosiahne PostgreSQL. Ak je TCP pripojenie odmietnuté, zmena hesla zvyčajne rieši nesprávnu vrstvu.

Úprava nesprávneho postgresql.conf

Počítače s viacerými inštaláciami môžu obsahovať niekoľko konfiguračných súborov. Kedykoľvek je to možné, použite funkčné lokálne soketové pripojenie a SHOW config_file;, alebo identifikujte dátový adresár procesa servera, ktorý skutočne zamýšľate spustiť.

Predpoklad, že 5432 je povinný

5432 je predvolený, nie povinný. Ak je váš zamýšľaný klastre nakonfigurovaný na 5433 a každý klient používa 5433, je to platné. Konzistencia je dôležitejšia ako vynucovanie predvoleného nastavenia.

Kedy by ste mali zmeniť svoj prístup k riešeniu problémov

Mali by ste prestať pracovať na „connection refused“ konkrétne v momente, keď pg_isready hlási prijímanie pripojení alebo keď psql dosiahne chybu autentifikácie/databázy. V tom bode sieťový počúvajúci proces robí svoju prácu a pokračovanie v zmene portov, pravidiel firewallu alebo listen_addresses môže zaviesť nové problémy.

Rovnako, ak sa PostgreSQL nespustí, prejdite od riešenia problémov na strane klienta k diagnostike spúšťania servera. Ak sa kontajner neustále reštartuje, prejdite na log kontajnera. Ak hostiteľský klient funguje, ale klientsky kontajner zlyháva, prejdite na DNS kontajnera a mapovanie portov. Užitočná otázka nie je „Ktoré nastavenie PostgreSQL by som mal prepínať?“, ale „Na ktorej vrstve sa pripojenie prestane posúvať?“

Ako vyzerá úspešná oprava

Môžete považovať problém s dosiahnuteľnosťou localhost za vyriešený, keď platia všetky nasledujúce podmienky pre prostredie, ktoré skutočne používate:

1. pg_isready -h localhost -p 5432 hlási accepting connections, alebo hlási ekvivalentného hostiteľa/port, ktorý ste zámerne nakonfigurovali.
2. Operačný systém ukazuje, že PostgreSQL počúva na očakávanej adrese a porte.
3. psql môže dosiahnuť server pomocou rovnakej sieťovej cesty ako aplikácia.
4. Vaša aplikácia už nedostáva connection refused.
5. Ak sa objaví iná chyba PostgreSQL, riešite túto novú chybu samostatne, namiesto pokračovania v úpravách počúvajúceho procesu.

Limit tohto postupu je dôležitý: diagnostikuje, či je server PostgreSQL dosiahnuteľný na očakávanom hostiteľovi a porte. Sám o sebe nemôže opraviť neplatné heslo, chýbajúcu rolu, chýbajúcu databázu, chybu SQL, problém so schémou alebo chybu v pooli pripojení aplikácie. Tie sa stanú relevantnými až po tom, čo pripojenie prejde fázou odmietnutia.

Pre väčšinu prípadov localhost je najkratšia cesta stále rovnaká: otestujte 5432 pomocou pg_isready, potvrďte, že zamýšľaná inštancia PostgreSQL beží, overte počúvajúci proces a až potom meňte konfiguráciu. Toto poradie udržuje riešenie problémov zamerané a znižuje šancu, že sa jednoduchý problém so zastavenou službou zmení na väčší sieťový alebo bezpečnostný problém.