Hogyan javítsd ki a PostgreSQL „connection refused” hibát a localhost 5432-es portján

Ha a PostgreSQL „connection refused” (kapcsolat elutasítva) hibaüzenetet ad a localhost:5432-n, az első teendő nem a jelszó ellenőrzése, hanem az elérhetőség biztosítása. Futtasd a pg_isready -h localhost -p 5432 parancsot. Ha no response (nincs válasz) eredményt kapsz, a PostgreSQL általában le van állítva, másik porton vagy címen figyel, másik környezetben (pl. Docker) fut, vagy indítás közben hibásodik meg. Ha accepting connections (kapcsolatokat fogad) eredményt kapsz, a szerver elérhető, és nem port-elutasítási problémaként kell kezelned a hibát, hanem a következő hibaüzenetet kell kivizsgálnod.

A PostgreSQL alapértelmezetten a 5432-es TCP portot használja, és a jelenlegi PostgreSQL 18 dokumentáció szerint a listen_addresses alapértelmezett értéke localhost. 2026. szeptember 11-én a PostgreSQL 18 a jelenlegi stabil főkiadás, a PostgreSQL 18.6 verzió 2026. augusztus 13-án jelent meg; a PostgreSQL 19 Beta 3 még fejlesztési kiadás. Az alábbi hibaelhárítási lépések általánosan alkalmazhatók a támogatott PostgreSQL verzióknál, de a csomagnevek, szolgáltatásnevek és fájlhelyek eltérőek lehetnek az operációs rendszertől és a telepítőtől függően. Lásd a hivatalos PostgreSQL 18.6 kiadási bejelentést és a jelenlegi kapcsolati beállítások dokumentációját.

1. Erősítsd meg, hogy a hiba valóban „Connection Refused”

Kezdd a pontos hibaüzenet szövegével. Több PostgreSQL kapcsolati hiba hasonlóan hangzik, de a stack különböző rétegeire utal.

Ez a megkülönböztetés megakadályoz egy gyakori tévutat: jelszavak vagy a pg_hba.conf szerkesztése, miközben semmi sem figyel az 5432-es porton. Ezek a beállítások csak akkor számítanak, miután a kapcsolat elérte a PostgreSQL szervert.

2. Futtasd a pg_isready-t a pontos host és port ellen

A pg_isready a PostgreSQL saját kapcsolati állapot segédprogramja. Futtasd:

pg_isready -h localhost -p 5432

A PostgreSQL négy kilépési állapotot dokumentál: 0, ha a szerver fogad kapcsolatokat, 1, ha elutasítja a kapcsolatokat, 2, ha nincs válasz, és 3, ha nem történt érvényes kísérlet. Nem szükséges helyes adatbázisnév, felhasználónév vagy jelszó az alapvető szerverállapot lekéréséhez. Lásd a hivatalos pg_isready referenciát.

Ha a következőt kapod:

• localhost:5432 - accepting connections: az 5432-es port elérhető. Próbáld meg a valódi psql vagy alkalmazás kapcsolatot, és hibaelhárítsd az új üzenetet, ha az is hibás.
• localhost:5432 - rejecting connections: a szerver válaszolt, de még nem fogad normál kapcsolatokat, ami előfordulhat indítás vagy helyreállítás közben. Ellenőrizd a szerver naplót, és várj, ha az indítás jogosan folyamatban van.
• localhost:5432 - no response: folytasd az alábbi szerver és figyelő ellenőrzésekkel.

Teszteld explicit a 127.0.0.1-et is:

pg_isready -h 127.0.0.1 -p 5432

Ha a 127.0.0.1 működik, de a localhost nem, a probléma valószínűbb, hogy névfeloldással vagy IPv4/IPv6 kötéssel kapcsolatos, mintsem a PostgreSQL teljesen leállt volna.

3. Győződj meg róla, hogy a PostgreSQL szerver fut

Ha a PostgreSQL-t operációs rendszer csomag vagy telepítő segítségével telepítetted, használd az adott csomag normál szolgáltatáskezelési mechanizmusát. A PostgreSQL saját dokumentációja azt javasolja, hogy ha elérhető, használd a csomagolt indítási infrastruktúrát, ahelyett, hogy külön indítási módszert találnál ki.

Ha közvetlenül kezelsz egy klasztert és ismered az adatkönyvtárát, a PostgreSQL biztosítja a pg_ctl-t:

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

A -D értéknek a helyes PostgreSQL adatkönyvtárra kell mutatnia, amely az adott adatbázis klaszter könyvtára. Ha a PGDATA konfigurálva van, a pg_ctl ezt használhatja helyette. A hivatalos pg_ctl dokumentáció leírja a status, start, restart és reload parancsokat.

Windows

Nyisd meg a Szolgáltatások (Services) ablakot, és keresd meg a telepítő által létrehozott PostgreSQL szolgáltatást. Ha le van állítva, indítsd el. Ha több PostgreSQL verzió van telepítve, ellenőrizd, hogy azt a példányt indítod-e, amely a alkalmazásod által várt adatkönyvtárhoz és porthoz tartozik.

Linux

A csomagnevek disztribúciónként eltérőek. Egy csomagolt telepítés rendszer szolgáltatást mutathat, mint például a postgresql, vagy egy verzió/klaszter-specifikus egységet. Használd a csomag szolgáltatás definícióját, ahelyett, hogy egy univerzális szolgáltatásnevet feltételeznél.

macOS

A helyes indítási mechanizmus attól függ, hogy a PostgreSQL app bundle-ből, Homebrew-ból, MacPorts-ból, forrásból vagy másik csomagból származik-e. Ugyanaz az elv érvényes: indítsd el a példányt abból a mechanizmusból, amely létrehozta, majd futtasd újra a pg_isready-t.

Ha a szerver azonnal újra leáll, ne folytasd az újraindítását. Vizsgáld meg az indítási naplóját. Egy hibás konfigurációs érték, hozzáférhetetlen adatkönyvtár, portütközés, hiányzó fájl vagy helyreállítási probléma megakadályozhatja a PostgreSQL működésben maradását.

4. Erősítsd meg, hogy valami valóban figyel az 5432-es porton

Egy futó PostgreSQL folyamat nem elég, ha másik porthoz vagy csak Unix domain socket-hez kötődik. Ellenőrizd az operációs rendszer figyelő táblázatát.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Ha nincs figyelő, akkor a PostgreSQL nem fut, másik portot használ, máshová kötődik, vagy nem indult el. Ha egy másik program birtokolja az 5432-es portot, a PostgreSQL nem tudja megkötni azt a portot. Ellenőrizd a PostgreSQL indítási naplóját, mielőtt eldöntöd, hogy leállítod a másik folyamatot, vagy áthelyezed a PostgreSQL-t másik portra.

Ha szándékosan a 5433-as portra konfiguráltad a PostgreSQL-t, az ügyfélnek is a 5433-at kell használnia:

psql -h localhost -p 5433 -U postgres

Ne „javítsd ki” a szándékos nem alapértelmezett portot úgy, hogy a PostgreSQL-t visszaállítod 5432-re, hacsak ez nem a valóban kívánt architektúra.

5. Ellenőrizd a postgresql.conf-ot: listen_addresses és port

A PostgreSQL listen_addresses beállítása szabályozza, hogy mely TCP/IP interfészek fogadnak kapcsolati kísérleteket. A dokumentált alapértelmezett érték a localhost. A port beállítás alapértelmezése 5432. Mindkét beállítás a szerver indításakor lép életbe, így a változtatásokhoz szerver újraindítása szükséges.

Egy szigorúan helyi fejlesztői adatbázis esetén a releváns beállítások általában így néznek ki:

listen_addresses = 'localhost'
port = 5432

Ha a listen_addresses üres karakterlánc, a PostgreSQL nem figyel egyetlen IP interfészen sem, és csak Unix domain socketek használhatók, ahol támogatottak. Ezzel szemben a listen_addresses = '*' beállítás arra kéri a PostgreSQL-t, hogy figyeljen minden elérhető interfészen; ez általában felesleges egy localhost-only fejlesztői adatbázis esetén, és növelheti a kitettséget, ha a hitelesítési és tűzfalszabályok nem távoli hozzáférésre lettek tervezve.

Ha Unix domain socketen keresztül tudsz csatlakozni, de a TCP a localhost-on nem működik, kérdezd le az élő szervert az aktív fájlok és beállítások megtalálásához:

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

Ez biztonságosabb, mint az első megtalált postgresql.conf szerkesztése, különösen olyan gépen, ahol több klaszter vagy PostgreSQL verzió található. A PostgreSQL támogatja az adatkönyvtáron kívüli konfigurációs fájlokat, így a fájlútvonalak nem univerzálisak. Lásd a hivatalos konfigurációs fájl helyek dokumentációját.

6. Ha a PostgreSQL Dockerben fut, a „localhost” jelentése attól függ, hol fut az ügyfél

A konténer hálózat megváltoztatja a hostnév jelentését. Ez az egyik leggyakoribb oka annak, hogy az adatbázis egészséges, de az alkalmazás még mindig connection refused hibát kap.

Az alkalmazás a host gépen fut

A PostgreSQL konténernek nyilvános host portra van szüksége. Egy Compose szolgáltatás tartalmazhatja:

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

Ezután a host gépen futó ügyfél használhatja:

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

Az alkalmazás másik Compose konténerben fut

Az alkalmazás konténerén belül a localhost az alkalmazás konténerére utal, nem az adatbázis konténerére. A Docker Compose szolgáltatásnév DNS-t biztosít, így ha az adatbázis szolgáltatás neve db, az alkalmazás általában így csatlakozik:

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

A Docker hivatalos Compose hálózati dokumentációja kifejezetten megkülönbözteti a konténer-közti szolgáltatásnevet a host nyilvános portjától. Például, ha a 8001:5432 leképezést használod, a konténerek továbbra is a db:5432-t használják, míg a host a localhost:8001-et. Lásd a Docker hivatalos Compose hálózati útmutatóját.

Mielőtt magát a PostgreSQL-t szerkesztenéd, ellenőrizd:

docker compose ps
docker compose logs db

Ha a konténer újraindul, a napló általában értékesebb, mint az ismétlődő kapcsolati karakterlánc változtatások.

7. Tekintsd a tűzfalszabályokat későbbi ellenőrzésnek a localhost elutasítás esetén

Ugyanazon a gépen lévő ügyfél és szerver esetén ne azzal kezdd, hogy az 5432-es portot minden hálózatnak megnyitod. Először erősítsd meg, hogy a PostgreSQL helyileg figyel. Egy széles körű tűzfalszabály felesleges kitettséget hozhat létre anélkül, hogy egy leállt szervert javítana.

A tűzfal kivizsgálása akkor válik relevánsabbá, ha:

• A PostgreSQL VM-ben, konténer hostban, WSL környezetben vagy másik hálózati névtérben van.
• Megváltoztattad a listen_addresses-t a nem loopback kapcsolatok engedélyezésére.
• A helyi biztonsági szoftver szabályokat alkalmaz a loopback vagy alkalmazás folyamatokra.
• A figyelő létezik és működik egy környezetből, de nem egy másikból.

Ha a távoli hozzáférés szándékos, korlátozd az engedélyezett forráshálózatokat és hitelesítési szabályokat a ténylegesen szükségesre. Az, hogy az 5432-es port mindenhol elérhető, nem előfeltétele egy helyi alkalmazásnak.

8. Ne szerkeszd a pg_hba.conf-ot, amíg a szerver nem elérhető

A pg_hba.conf a PostgreSQL ügyfél hitelesítését szabályozza. Egy host rekord a TCP/IP kapcsolatokra vonatkozik. Nem okozza egy leállt szerver figyelésének megkezdését, így általában rossz első javítás a connection refused esetén.

Amint a pg_isready azt jelenti, hogy a szerver fogad kapcsolatokat, egy hitelesítési hiba jogosan vezethet a pg_hba.conf-hoz. A localhost TCP kapcsolatokhoz a szabályok általában loopback címekre korlátozódnak, mint például a 127.0.0.1/32 és ::1/128, a környezetedhez választott adatbázissal, szereppel és hitelesítési módszerrel.

A PostgreSQL 18 alapértelmezetten scram-sha-256-ra állítja a password_encryption-t, és a dokumentációja elavultnak jelöli az MD5-tel titkosított jelszavakat. Kerüld a régi hitelesítési példák vak másolását. Lásd a jelenlegi pg_hba.conf dokumentációt és a jelenlegi hitelesítési beállításokat.

Unix-szerű rendszereken a pg_hba.conf változtatásai újratölthetők a pg_ctl reload vagy a SELECT pg_reload_conf(); paranccsal. A PostgreSQL dokumentál egy Windows-specifikus különbséget: a pg_hba.conf változtatásai a következő új kapcsolatokra lépnek életbe ugyanazon SIGHUP követelmény nélkül.

9. Teszteld a psql-lel, miután a figyelő egészséges

Amint a pg_isready azt jelenti, hogy a szerver fogad kapcsolatokat, teszteld ugyanazt az útvonalat, amelyet az alkalmazásod vár:

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

Egy sikeres psql prompt sokkal többet mond, mint „a szolgáltatás fut”: megerősíti, hogy egy valódi PostgreSQL ügyfél elérte a szervert, és átment a kapcsolati és hitelesítési szakaszokon ezekhez a paraméterekhez.

Ha a psql működik, de az alkalmazásod még mindig connection refused hibát jelent, hasonlítsd össze az alkalmazás konfigurációját karakterről karakterre:

• Hostnév
• Port
• Adatbázis név
• Felhasználónév
• Hogy az app a hoston, Dockerben, VM-ben vagy másik környezetben fut-e
• Az aktuálisan futó folyamat által betöltött környezeti változók
• Hogy az alkalmazás újraindult-e a kapcsolati karakterlánc megváltoztatása után

Egy gyakori példa az, amikor egy helyi terminál sikeresen használja a localhost:5432-t, miközben egy Dockerizált webalkalmazás is a localhost:5432-t használja. A webalkalmazás ekkor önmagát hívja, nem az adatbázis szolgáltatást. Ebben az esetben a konténer adatbázis hostjának a Compose szolgáltatásnévre változtatása a releváns javítás.

10. Olvasd el a szerver naplót, ha a PostgreSQL nem marad fent

Ha a szolgáltatás elindul és azonnal kilép, a hálózati hiba csak tünet. Az indítási napló az, ahol a PostgreSQL elmagyarázza, miért nem tudott készen állni.

Keress üzeneteket a következőkről:

• Cím vagy port már használatban
• Érvénytelen postgresql.conf szintaxis
• Hiányzó vagy hozzáférhetetlen adatkönyvtár
• Fájl tulajdonosi vagy jogosultsági problémák
• Helyreállítási vagy WAL problémák
• Inkompatibilis adatkönyvtár és szerver fő verzió

Ha közvetlenül kezelt klasztert indítasz a pg_ctl-lel, a PostgreSQL javasolja a szerver kimenetének rögzítését, például a -l logfile kapcsolóval. A projekt szerver indítási dokumentációja elmagyarázza, miért hasznos az indítási kimenet a diagnosztikához.

Gyors diagnosztika forgatókönyv szerint

Gyakori javítások, amelyek ronthatnak a helyzeten

A listen_addresses '*' értékre állítása ok nélkül

Ez elérhetővé teheti a PostgreSQL-t további interfészekről, de nem szükséges egy normál ugyanazon a gépen lévő localhost kapcsolathoz. Szélesítheti a kitettséget is. Használd a legszűkebb kötést, amely megfelel az architektúrádnak.

A 5432-es port megnyitása az egész hálózatnak

Egy tűzfal kivétel nem tudja figyelni egy leállt PostgreSQL folyamatot. Először erősítsd meg a figyelőt, majd csak a ténylegesen szükséges hálózati hozzáférést add hozzá.

A postgres jelszó visszaállítása kapcsolati elutasítás miatt

A jelszó hitelesítés akkor történik, miután az ügyfél elérte a PostgreSQL-t. Ha a TCP kapcsolatot elutasítják, a jelszó megváltoztatása általában rossz réteget céloz meg.

A rossz postgresql.conf szerkesztése

Több telepítéssel rendelkező gépek több konfigurációs fájlt tartalmazhatnak. Mindig, amikor lehetséges, használj működő helyi socket kapcsolatot és a SHOW config_file; parancsot, vagy azonosítsd annak a szerver folyamatnak az adatkönyvtárát, amelyet valóban futtatni szándékozol.

Az 5432 kötelezőnek feltételezése

Az 5432 az alapértelmezés, nem követelmény. Ha a kívánt klasztered a 5433-ra van konfigurálva, és minden ügyfél a 5433-at használja, az érvényes. A konzisztencia fontosabb, mint az alapértelmezés erőltetése.

Mikor kell megváltoztatnod a hibaelhárítási megközelítésedet

Abban a pillanatban, amikor a pg_isready azt jelenti, hogy fogad kapcsolatokat, vagy a psql eléri a hitelesítési/adatbázis hibát, abban a pillanatban abba kell hagynod a „connection refused” specifikus munkáját. Ezen a ponton a hálózati figyelő végzi a dolgát, és a portok, tűzfalszabályok vagy listen_addresses további változtatása új problémákat vezethet be.

Hasonlóképpen, ha a PostgreSQL nem tud elindulni, válts az ügyfél-oldali hibaelhárításról a szerver-indítási diagnosztikára. Ha egy konténer folyamatosan újraindul, térj át a konténer naplóra. Ha egy host ügyfél működik, de egy konténer ügyfél hibás, térj át a konténer DNS-re és port leképezésre. A hasznos kérdés nem az, hogy „Melyik PostgreSQL beállítást kell átállítanom?”, hanem az, hogy „Melyik rétegen áll meg a kapcsolat előrehaladása?”

Milyen egy sikeres javítás

A localhost elérhetőségi problémát akkor tekintheted megoldottnak, ha a ténylegesen használt környezetben az alábbiak mindegyike igaz:

1. A pg_isready -h localhost -p 5432 azt jelenti, hogy accepting connections, vagy azt az egyenértékű host/portot jelenti, amelyet szándékosan konfiguráltál.
2. Az operációs rendszer azt mutatja, hogy a PostgreSQL a várt címen és porton figyel.
3. A psql eléri a szervert ugyanazon a hálózati útvonalon, mint az alkalmazás.
4. Az alkalmazásod nem kap többé connection refused hibát.
5. Ha egy másik PostgreSQL hiba jelenik meg, azt külön hibaelhárítod, ahelyett, hogy tovább módosítanád a figyelőt.

Ennek az eljárásnak a határa fontos: azt diagnosztizálja, hogy egy PostgreSQL szerver elérhető-e a várt hoston és porton. Önmagában nem tudja kijavítani az érvénytelen jelszót, hiányzó szerepet, hiányzó adatbázist, SQL hibát, séma problémát vagy alkalmazás kapcsolati pool hibát. Ezek csak akkor válnak relevánssá, miután a kapcsolat túljutott az elutasítási szakaszon.

A legtöbb localhost esetben a legrövidebb út még mindig ugyanaz: teszteld az 5432-t a pg_isready-vel, erősítsd meg, hogy a kívánt PostgreSQL példány fut, ellenőrizd a figyelőt, és csak ezután változtass konfigurációt. Ez a sorrend fókuszáltan tartja a hibaelhárítást, és csökkenti annak esélyét, hogy egy egyszerű leállt szolgáltatás problémát nagyobb hálózati vagy biztonsági problémává alakíts.