Jak opravit chybu „Connection Refused“ u PostgreSQL na localhostu portu 5432

Pokud PostgreSQL hlásí „connection refused“ na localhost:5432, první věcí, kterou je třeba opravit, je dosažitelnost, nikoliv heslo. Spusťte příkaz pg_isready -h localhost -p 5432. Pokud hlásí no response, PostgreSQL je obvykle zastaven, naslouchá na jiném portu nebo adrese, běží v jiném prostředí, jako je Docker, nebo selhává při startu. Pokud hlásí accepting connections, server je dosažitelný a měli byste přestat řešit problém jako odmítnutí portu a místo toho prošetřit další chybovou hlášku.

PostgreSQL používá výchozí TCP port 5432 a aktuální dokumentace PostgreSQL 18 uvádí, že výchozí hodnota listen_addresses je localhost. K 11. září 2026 je PostgreSQL 18 aktuální stabilní hlavní verzí, přičemž verze PostgreSQL 18.6 byla vydána 13. srpna 2026; PostgreSQL 19 Beta 3 je stále vývojovou verzí. Níže uvedené kroky pro řešení problémů se obecně vztahují na podporované verze PostgreSQL, ale názvy balíčků, názvy služeb a umístění souborů se liší podle operačního systému a instalátoru. Podívejte se na oficiální oznámení o vydání PostgreSQL 18.6 a aktuální dokumentaci nastavení připojení.

1. Potvrďte, že chyba je skutečně „Connection Refused“

Začněte přesným textem chybové hlášky. Několik selhání připojení PostgreSQL zní podobně, ale ukazují na různé vrstvy zásobníku.

Vzor zprávy	Co vám obvykle říká	Kam se podívat dál
connection refused	TCP připojení nedosáhlo naslouchajícího procesu PostgreSQL na dané adrese a portu	Proces serveru, port, bind adresa, mapování kontejneru, lokální síťování
timeout expired nebo žádná odpověď	Síťová cesta nevygenerovala včasnou odpověď	Špatný hostitel, firewall, hranice kontejneru/VM, nedostupný server
password authentication failed	Dosáhli jste PostgreSQL a začalo ověřování	Uživatel, heslo, metoda ověřování
no pg_hba.conf entry	Dosáhli jste PostgreSQL, ale žádná odpovídající pravidlo pro ověřování klienta nepovolilo pokus	pg_hba.conf
database ... does not exist	Server je dosažitelný a ověřování pokročilo dostatečně daleko na to, aby identifikovalo požadavek na databázi	Název databáze a řetězec připojení

Toto rozlišení zabraňuje běžné odbočce: úpravě hesel nebo pg_hba.conf, zatímco na portu 5432 nic nenaslouchá. Tato nastavení jsou důležitá až poté, co připojení dosáhne serveru PostgreSQL.

2. Spusťte pg_isready proti přesnému hostiteli a portu

pg_isready je vlastní utilita PostgreSQL pro stav připojení. Spusťte:

pg_isready -h localhost -p 5432

PostgreSQL dokumentuje čtyři stavové kódy: 0, když server přijímá připojení, 1, když připojení odmítá, 2, když není žádná odpověď, a 3, když nebyl proveden žádný platný pokus. K získání základního stavu serveru nepotřebujete správný název databáze, uživatelské jméno ani heslo. Podívejte se na oficiální referenci pg_isready.

Pokud získáte:

• localhost:5432 - accepting connections: Port 5432 je dosažitelný. Zkuste své skutečné připojení přes psql nebo aplikaci a pokud selže, řešte novou hlášku.
• localhost:5432 - rejecting connections: Server odpověděl, ale zatím nepřijímá běžná připojení, což může nastat během startu nebo obnovy. Zkontrolujte log serveru a počkejte, pokud je start legitimně v procesu.
• localhost:5432 - no response: Pokračujte s níže uvedenými kontrolami serveru a naslouchání.

Také explicitně otestujte 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Pokud 127.0.0.1 funguje, ale localhost ne, problém je pravděpodobněji spojen s překladem názvů nebo bindováním IPv4/IPv6 než s tím, že by byl PostgreSQL zcela mimo provoz.

3. Ujistěte se, že server PostgreSQL běží

Pokud jste nainstalovali PostgreSQL prostřednictvím balíčku operačního systému nebo instalátoru, použijte běžný mechanismus správy služeb tohoto balíčku. Dokumentace PostgreSQL doporučuje používat balíčkovou infrastrukturu pro start, pokud je k dispozici, místo vymýšlení samostatné metody startu.

Pokud spravujete cluster přímo a znáte jeho datový adresář, PostgreSQL poskytuje pg_ctl:

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

Hodnota -D musí ukazovat na správný datový adresář PostgreSQL, což je adresář pro daný databázový cluster. Pokud je nakonfigurováno PGDATA, může pg_ctl použít tuto proměnnou. Oficiální dokumentace pg_ctl popisuje příkazy status, start, restart a reload.

Windows

Otevřete Služby a hledejte službu PostgreSQL vytvořenou vaším instalátorem. Pokud je zastavená, spusťte ji. Pokud je nainstalováno více verzí PostgreSQL, ověřte, že spouštíte instanci spojenou s datovým adresářem a portem, který vaše aplikace očekává.

Linux

Názvy balíčků se mezi distribucemi liší. Balíčková instalace může nabízet systémovou službu, jako je postgresql, nebo jednotku specifickou pro verzi/cluster. Použijte definici služby balíčku, místo abyste předpokládali jeden univerzální název služby.

macOS

Správný mechanismus startu závisí na tom, zda PostgreSQL pochází z aplikačního balíčku, Homebrew, MacPorts, ze zdrojového kódu nebo z jiného balíčku. Platí stejný princip: spusťte instanci z mechanismu, který ji vytvořil, a znovu spusťte pg_isready.

Pokud se server okamžitě znovu zastaví, nepřestávejte ho restartovat. Prozkoumejte jeho log startu. Špatná konfigurační hodnota, nedostupný datový adresář, konflikt portů, chybějící soubor nebo problém s obnovou mohou zabránit tomu, aby PostgreSQL zůstal spuštěný.

4. Ověřte, že něco skutečně naslouchá na portu 5432

>Běžící proces PostgreSQL nestačí, pokud je bindován na jiný port nebo pouze na Unix-domain socket. Zkontrolujte tabulku naslouchajících procesů 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

Pokud neexistuje žádný naslouchající proces, buď PostgreSQL neběží, používá jiný port, je bindován někde jinde, nebo se nepodařilo ho spustit. Pokud vlastní port 5432 jiný program, PostgreSQL nemusí být schopen tento port bindovat. Před rozhodnutím, zda zastavit jiný proces, nebo přesunout PostgreSQL na jiný port, zkontrolujte log startu PostgreSQL.

Pokud jste záměrně nakonfigurovali PostgreSQL na portu 5433, váš klient musí použít 5433:

psql -h localhost -p 5433 -U postgres

Neopravujte záměrně zvolený nevýchozí port tím, že vrátíte PostgreSQL zpět na 5432, pokud to není skutečně vaše požadovaná architektura.

5. Zkontrolujte postgresql.conf: listen_addresses a port

Nastavení listen_addresses v PostgreSQL řídí, které rozhraní TCP/IP přijímají pokusy o připojení. Dokumentovaná výchozí hodnota je localhost. Nastavení port má výchozí hodnotu 5432. Obě nastavení se aplikují při startu serveru, takže změny vyžadují restart serveru.

Pro striktně lokální vývojovou databázi vypadají relevantní nastavení obvykle takto:

listen_addresses = 'localhost'
port = 5432

Pokud je listen_addresses prázdný řetězec, PostgreSQL nenaslouchá na žádném IP rozhraní a pouze Unix-domain sokety mohou být použity tam, kde jsou podporovány. Naopak nastavení listen_addresses = '*' žádá PostgreSQL, aby naslouchal na všech dostupných rozhraních; to je obvykle zbytečné pro vývojovou databázi dostupnou pouze přes localhost a může zvýšit expozici, pokud nejsou ověřování a pravidla firewallu navržena pro vzdálený přístup.

Pokud se můžete připojit přes Unix-domain socket, ale TCP na localhost selhává, dotazujte se běžícího serveru, abyste našli aktivní soubory a nastavení:

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

Toto je bezpečnější než úprava prvního nalezeného postgresql.conf, zejména na stroji s několika clustery nebo verzemi PostgreSQL. PostgreSQL podporuje konfigurační soubory mimo datový adresář, takže cesty k souborům nejsou univerzální. Podívejte se na oficiální dokumentaci umístění konfiguračních souborů.

6. Pokud běží PostgreSQL v Dockeru, „localhost“ závisí na tom, kde běží klient

Síťování kontejnerů mění význam názvu hostitele. Toto je jeden z nejčastějších důvodů, proč je databáze zdravá, ale aplikace stále dostává chybu connection refused.

Aplikace běží na hostitelském stroji

Kontejner PostgreSQL potřebuje publikovaný hostitelský port. Služba Compose může obsahovat:

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

Poté klient běžící na vašem hostiteli může použít:

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

Aplikace běží v jiném kontejneru Compose

Uvnitř kontejneru aplikace se localhost vztahuje na samotný kontejner aplikace, nikoliv na kontejner databáze. Docker Compose poskytuje DNS pro názvy služeb, takže pokud je služba databáze pojmenována db, aplikace se obvykle připojuje k:

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

Oficiální dokumentace síťování Docker Compose explicitně rozlišuje mezi názvem služby pro komunikaci mezi kontejnery a publikovaným portem hostitele. Například pokud mapujete 8001:5432, kontejnery stále používají db:5432, zatímco hostitel používá localhost:8001. Podívejte se na oficiální průvodce síťováním Docker Compose.

Před úpravou samotného PostgreSQL zkontrolujte:

docker compose ps
docker compose logs db

Pokud se kontejner restartuje, log je obvykle cennější než opakované měnění řetězců připojení.

7. Pravidla firewallu řešte až později při odmítnutí na localhostu

Pro klienta a server na stejném stroji nezačínejte otevíráním portu 5432 pro celou síť. Nejprve potvrďte, že PostgreSQL naslouchá lokálně. Široké pravidlo firewallu může vytvořit zbytečnou expozici bez vyřešení zastaveného serveru.

Šetření firewallu se stává relevantnějším, když:

• PostgreSQL je ve VM, hostiteli kontejneru, prostředí WSL nebo jiném síťovém jmenném prostoru.
• Změnili jste listen_addresses, aby umožnila připojení mimo loopback.
• Lokální bezpečnostní software aplikuje pravidla na loopback nebo procesy aplikací.
• Naslouchající proces existuje a funguje z jednoho prostředí, ale ne z druhého.

Pokud je vzdálený přístup záměrný, omezte povolené zdrojové sítě a pravidla ověřování na to, co je skutečně nutné. Dosažitelnost portu 5432 odkudkoli není předpokladem pro lokální aplikaci.

8. Neupravujte pg_hba.conf, dokud není server dosažitelný

pg_hba.conf řídí ověřování klientů PostgreSQL. Záznam host se vztahuje na připojení TCP/IP. Nezpůsobí, že by zastavený server začal naslouchat, takže je obvykle špatným prvním řešením pro connection refused.

Jakmile pg_isready hlásí, že server přijímá připojení, chyba ověřování vás může oprávněně vést k pg_hba.conf. Pro připojení TCP na localhost jsou pravidla obvykle omezena na loopback adresy, jako jsou 127.0.0.1/32 a ::1/128, s databází, rolí a metodou ověřování zvolenou pro vaše prostředí.

PostgreSQL 18 má výchozí hodnotu password_encryption nastavenou na scram-sha-256 a jeho dokumentace označuje hesla šifrovaná MD5 jako zastaralá. Vyhněte se slepému kopírování starých příkladů ověřování. Podívejte se na aktuální dokumentaci pg_hba.conf a aktuální nastavení ověřování.

Na systémech typu Unix lze změny v pg_hba.conf znovu načíst pomocí pg_ctl reload nebo SELECT pg_reload_conf();. PostgreSQL dokumentuje rozdíl specifický pro Windows: změny v pg_hba.conf se aplikují na následná nová připojení bez stejného požadavku na SIGHUP.

9. Testujte pomocí psql, když je naslouchající proces zdravý

Jakmile pg_isready řekne, že server přijímá připojení, otestujte stejnou cestu, kterou očekává vaše aplikace:

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

Úspěšná výzva psql vám řekne mnohem více než „služba běží“: potvrzuje, že skutečný klient PostgreSQL dosáhl serveru a prošel fázemi připojení a ověřování pro tyto parametry.

Pokud psql funguje, ale vaše aplikace stále hlásí connection refused, porovnejte konfiguraci aplikace znak po znaku:

• Název hostitele
• Port
• Název databáze
• Uživatelské jméno
• Zda aplikace běží na hostiteli, v Dockeru, ve VM nebo v jiném prostředí
• Proměnné prostředí načtené skutečným běžícím procesem
• Zda byla aplikace restartována po změně jejího řetězce připojení

Běžným příkladem je lokální terminál úspěšně používající localhost:5432, zatímco web aplikace v Dockeru také používá localhost:5432. Web aplikace pak volá sama sebe, nikoliv službu databáze. V takovém případě je relevantním řešením změnit hostitele databáze kontejneru na název služby Compose.

10. Přečtěte si log serveru, pokud PostgreSQL nechce zůstat spuštěný

Pokud se služba spustí a okamžitě ukončí, síťová chyba je pouze příznakem. Log startu je místo, kde PostgreSQL vysvětluje, proč nemohl být připraven.

Hledejte zprávy o:

• Adrese nebo portu, které jsou již používány
• Neplatné syntaxi postgresql.conf
• Chybějícím nebo nedostupném datovém adresáři
• Problemech s vlastnictvím souborů nebo oprávněními
• Problemech s obnovou nebo WAL
• Nekompatibilním datovém adresáři a hlavní verzí serveru

Pokud spouštíte přímo spravovaný cluster pomocí pg_ctl, PostgreSQL doporučuje zachytávat výstup serveru, například pomocí -l logfile. Dokumentace startu serveru projektu vysvětluje, proč je výstup startu užitečný pro diagnostiku.

Rychlá diagnostika podle scénáře

Situace	Nejužitečnější první kontrola	Pravděpodobný směr
Nová lokální instalace; 5432 odmítá	pg_isready -h localhost -p 5432	Služba se možná nespustila nebo používá jiný port
Včera fungovalo; stroj byl restartován	Stav služby a log PostgreSQL	Služba se nespustila automaticky nebo start nyní selhává
psql na hostiteli funguje; aplikace v Dockeru selhává	Zkontrolujte hostitele připojení aplikace	Použijte název služby Compose místo localhost uvnitř kontejneru
Unix socket funguje; -h localhost selhává	SHOW listen_addresses; a SHOW port;	Naslouchání TCP je zakázáno nebo bindováno jinak
Na 5432 je naslouchající proces, ale není to PostgreSQL	Identifikujte proces vlastnící port	Řešte konflikt portů nebo použijte nakonfigurovaný port PostgreSQL
Chyba se změnila na selhání hesla	Přestaňte měnit síťová nastavení	Dosažitelnost je opravena; řešte ověřování
Chyba se změnila na no pg_hba.conf entry	Zkontrolujte odpovídající pravidla HBA	Dosažitelnost je opravena; řešte autorizaci klienta

Běžná řešení, která mohou situaci zhoršit

Nastavení listen_addresses na '*' bez důvodu

To může zpřístupnit PostgreSQL z dalších rozhraní, ale pro běžné připojení localhost na stejném stroji to není nutné. Může také rozšířit expozici. Použijte nejužší bindování, které odpovídá vaší architektuře.

Otevření portu 5432 pro celou síť

Výjimka ve firewallu nemůže donutit zastavený proces PostgreSQL naslouchat. Nejprve potvrďte naslouchající proces, poté přidejte pouze síťový přístup, který skutečně potřebujete.

Resetování hesla postgres kvůli odmítnutí připojení

Ověřování heslem probíhá poté, co klient dosáhne PostgreSQL. Pokud je TCP připojení odmítnuto, změna hesla obvykle řeší špatnou vrstvu.

Úprava špatného postgresql.conf

Stroje s více instalacemi mohou obsahovat několik konfiguračních souborů. Kdykoli je to možné, použijte funkční lokální socketové připojení a SHOW config_file;, nebo identifikujte datový adresář proces serveru, který skutečně zamýšlíte spustit.

Předpoklad, že 5432 je povinný

5432 je výchozí hodnota, nikoliv požadavek. Pokud je váš zamýšlený cluster nakonfigurován pro 5433 a všichni klienti používají 5433, je to platné. Konzistence je důležitější než vynucování výchozí hodnoty.

Kdy byste měli změnit svůj přístup k řešení problémů

Měli byste přestat pracovat na „connection refused“ konkrétně ve chvíli, kdy pg_isready hlásí přijímání připojení nebo psql dosáhne chyby ověřování/databáze. V tu chvíli síťový naslouchající proces dělá svou práci a pokračování ve změně portů, pravidel firewallu nebo listen_addresses může zavést nové problémy.

Stejně tak, pokud se PostgreSQL nespustí, přejděte od řešení problémů na straně klienta k diagnostice startu serveru. Pokud se kontejner neustále restartuje, přejděte na log kontejneru. Pokud klient na hostiteli funguje, ale klient v kontejneru selhává, přejděte na DNS kontejneru a mapování portů. Užitečná otázka není „Které nastavení PostgreSQL bych měl přepnout?“, ale „Na které vrstvě se připojení přestane vyvíjet?“

Jak vypadá úspěšná oprava

Můžete považovat problém s dosažitelností localhost za opravený, pokud jsou všechny následující podmínky pravdivé pro prostředí, které skutečně používáte:

1. pg_isready -h localhost -p 5432 hlásí accepting connections, nebo hlásí ekvivalentní hostitele/port, který jste záměrně nakonfigurovali.
2. Operační systém ukazuje, že PostgreSQL naslouchá na očekávané adrese a portu.
3. psql může dosáhnout serveru pomocí stejné síťové cesty jako aplikace.
4. Vaše aplikace již nedostává chybu connection refused.
5. Pokud se objeví jiná chyba PostgreSQL, řešíte tuto novou chybu samostatně, místo abyste pokračovali v úpravách naslouchajícího procesu.

Meze tohoto postupu jsou důležité: diagnostikuje, zda je server PostgreSQL dosažitelný na očekávaném hostiteli a portu. Sám o sobě nemůže opravit neplatné heslo, chybějící roli, chybějící databázi, chybu SQL, problém se schématem nebo chybu v poolu připojení aplikace. Tyto problémy se stanou relevantními až poté, co připojení projde fází odmítnutí.

Pro většinu případů localhost je nejkratší cesta stále stejná: otestujte 5432 pomocí pg_isready, potvrďte, že zamýšlená instance PostgreSQL běží, ověřte naslouchající proces a teprve poté měňte konfiguraci. Toto pořadí udržuje řešení problémů zaměřené a snižuje šanci, že se ze jednoduchého problému se zastavenou službou stane větší problém se sítí nebo bezpečností.