Kaip išspręsti PostgreSQL „Connection Refused“ klaidą vietiniame serveryje (localhost) prievade 5432

Jei PostgreSQL rodo „connection refused“ (atmestas ryšys) adresu localhost:5432, pirmiausia reikia spręsti pasiekiamumo problemą, o ne slaptažodį. Paleiskite komandą pg_isready -h localhost -p 5432. Jei ji praneša no response (nėra atsakymo), PostgreSQL dažniausiai yra sustabdytas, klausosi kito prievado ar adreso, veikia kitoje aplinkoje (pvz., Docker) arba nepavyksta paleidimo metu. Jei praneša accepting connections (priima ryšius), serveris yra pasiekiamas, todėl nebeturėtumėte laikyti šios problemos prievado atmetimo klaida ir vietoj to tirti kitą klaidos pranešimą.

PostgreSQL pagal nutylėjimą naudoja TCP prievadą 5432, o dabartinė PostgreSQL 18 dokumentacija nurodo, kad listen_addresses numatytoji reikšmė yra localhost. 2026 m. rugsėjo 11 d. PostgreSQL 18 yra naujausias stabilus pagrindinis leidimas, o PostgreSQL 18.6 buvo išleistas 2026 m. rugpjūčio 13 d.; PostgreSQL 19 Beta 3 vis dar yra plėtros leidimas. Žemiau pateikti trikčių šalinimo veiksmai taikomi plačiai palaikomoms PostgreSQL versijoms, tačiau paketų pavadinimai, tarnybų pavadinimai ir failų vietos skiriasi priklausomai nuo operacinės sistemos ir diegimo programos. Peržiūrėkite oficialų PostgreSQL 18.6 leidimo pranešimą ir dabartinę ryšių nustatymų dokumentaciją.

1. Įsitikinkite, kad klaida tikrai yra „Connection Refused“

Pradėkite nuo tikslios klaidos teksto. Kai kurie PostgreSQL ryšio sutrikimai skamba panašiai, tačiau nurodo skirtingus sistemos sluoksnius.

Šis skirtumas padeda išvengti dažnos klaidos: slaptažodžių ar pg_hba.conf redagavimo, kai niekas neklauso prievado 5432. Šie nustatymai yra svarbūs tik tada, kai ryšys pasiekia PostgreSQL serverį.

2. Paleiskite pg_isready tiksliai tam hostui ir prievadui

pg_isready yra PostgreSQL nuosavas ryšio būsenos įrankis. Paleiskite:

pg_isready -h localhost -p 5432

PostgreSQL dokumentuoja keturias išėjimo būsenas: 0, kai serveris priima ryšius, 1, kai jis atmeta ryšius, 2, kai nėra atsakymo, ir 3, kai nebuvo pateikta galiojanti užklausa. Jums nereikia teisingo duomenų bazės pavadinimo, vartotojo vardo ar slaptažodžio, kad gautumėte pagrindinę serverio būseną. Peržiūrėkite oficialią pg_isready nuorodą.

Jei gaunate:

• localhost:5432 - accepting connections: prievadas 5432 yra pasiekiamas. Pabandykite savo tikrą psql ar programos ryšį ir šalinkite naują klaidą, jei ji nepavyksta.
• localhost:5432 - rejecting connections: serveris atsakė, tačiau dar nepriima įprastų ryšių, kas gali nutikti paleidimo ar atkūrimo metu. Patikrinkite serverio žurnalą ir palaukite, jei paleidimas teisėtai vyksta.
• localhost:5432 - no response: tęskite su serverio ir klausiklio patikrinimais žemiau.

Taip pat aiškiai išbandykite 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Jei 127.0.0.1 veikia, o localhost neveikia, problema greičiausiai susijusi su pavadinimų sprendimu arba IPv4/IPv6 susiejimu, o ne tuo, kad PostgreSQL visiškai neveikia.

3. Įsitikinkite, kad PostgreSQL serveris veikia

Jei PostgreSQL įdiegėte per operacinės sistemos paketą arba diegimo programą, naudokite įprastą to paketo tarnybos valdymo mechanizmą. PostgreSQL dokumentacija rekomenduoja naudoti supakuotą paleidimo infrastruktūrą, kai ji yra prieinama, vietoj to, kad kurtumėte atskirą paleidimo būdą.

Jei tiesiogiai valdote klasterį ir žinote jo duomenų katalogą, PostgreSQL pateikia pg_ctl:

pg_ctl status -D /kelias/i/duomenis
pg_ctl start -D /kelias/i/duomenis -l /kelias/i/postgresql.log

-D reikšmė turi nurodyti teisingą PostgreSQL duomenų katalogą, kuris yra tos duomenų bazės klasterio katalogas. Jei PGDATA yra sukonfigūruotas, pg_ctl gali jį naudoti vietoj to. Oficiali pg_ctl dokumentacija aprašo status, start, restart ir reload.

Windows

Atidarykite Tarnybas (Services) ir ieškokite jūsų diegimo programos sukurtos PostgreSQL tarnybos. Jei ji sustabdyta, paleiskite ją. Jei įdiegtos kelios PostgreSQL versijos, įsitikinkite, kad paleidžiate egzempliorių, susijusį su duomenų katalogu ir prievadu, kurio tikisi jūsų programa.

Linux

Paketų pavadinimai skiriasi tarp distribucijų. Supakuotas diegimas gali pateikti sistemos tarnybą, pvz., postgresql, arba versijai/klasteriui specifinį vienetą. Naudokite paketo tarnybos apibrėžimą, o ne darykite prielaidą, kad yra vienas universalus tarnybos pavadinimas.

macOS

Teisingas paleidimo mechanizmas priklauso nuo to, ar PostgreSQL gautas iš programos paketo, Homebrew, MacPorts, šaltinio kodo ar kito paketo. Galioja tas pats principas: paleiskite egzempliorių iš mechanizmo, kuris jį sukūrė, tada vėl paleiskite pg_isready.

Jei serveris iškart vėl sustoja, nebandykite jo nuolat paleidinėti iš naujo. Ištirkite jo paleidimo žurnalą. Netinkama konfigūracijos reikšmė, neprieinamas duomenų katalogas, prievado konfliktas, trūkstamas failas ar atkūrimo problema gali neleisti PostgreSQL išlikti veikiančiam.

4. Patikrinkite, ar kas nors iš tikrųjų klauso prievado 5432

Veikiantis PostgreSQL procesas nepakanka, jei jis susietas su kitu prievadu arba tik su Unix srities lizdu. Patikrinkite operacinės sistemos klausiklių lentelę.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Jei klausiklio nėra, arba PostgreSQL neveikia, arba naudoja kitą prievadą, arba yra susietas kitur, arba nepavyko paleisti. Jei kitą programą valdo prievadą 5432, PostgreSQL gali negalėti susieti to prievado. Prieš nuspręsdami sustabdyti kitą procesą arba perkelti PostgreSQL į kitą prievadą, patikrinkite PostgreSQL paleidimo žurnalą.

Jei sąmoningai sukonfigūravote PostgreSQL prievade 5433, pavyzdžiui, jūsų klientas turi naudoti 5433:

psql -h localhost -p 5433 -U postgres

Nemėginkite „ištaisyti“ sąmoningai pasirinkto ne numatytojo prievado keisdami PostgreSQL atgal į 5432, nebent tai iš tikrųjų yra norima jūsų architektūra.

5. Patikrinkite postgresql.conf: listen_addresses ir port

PostgreSQL nustatymas listen_addresses kontroliuoja, kurie TCP/IP sąsajos priima ryšio bandymus. Dokumentuota numatytoji reikšmė yra localhost. Nustatymas port pagal nutylėjimą yra 5432. Abu nustatymai taikomi paleidžiant serverį, todėl pakeitimams reikia paleisti serverį iš naujo.

Griežtai vietinei plėtros duomenų bazei atitinkami nustatymai dažniausiai atrodo taip:

listen_addresses = 'localhost'
port = 5432

Jei listen_addresses yra tuščia eilutė, PostgreSQL neklauso jokių IP sąsajų ir tik Unix srities lizdai gali būti naudojami ten, kur jie palaikomi. Atvirkščiai, nustatymas listen_addresses = '*' prašo PostgreSQL klausytis visų prieinamų sąsajų; tai paprastai nereikalinga tik localhost plėtros duomenų bazei ir gali padidinti pažeidžiamumą, jei autentifikavimo ir ugniasienės taisyklės nėra sukurtos nuotolinei prieigai.

Jei galite prisijungti per Unix srities lizdą, tačiau TCP per localhost nepavyksta, užklauskite veikiančio serverio, kad rastumėte aktyvius failus ir nustatymus:

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

Tai yra saugiau nei redaguoti pirmą rastą postgresql.conf, ypač mašinoje su keliais klasteriais ar PostgreSQL versijomis. PostgreSQL palaiko konfigūracijos failus už duomenų katalogo ribų, todėl failų keliai nėra universalūs. Peržiūrėkite oficialią konfigūracijos failų vietų dokumentaciją.

6. Jei PostgreSQL veikia Docker, „localhost“ priklauso nuo to, kur veikia klientas

Konteinerių tinklas keičia hosto pavadinimo reikšmę. Tai viena dažniausių priežasčių, kodėl duomenų bazė yra sveika, tačiau programa vis tiek gauna „connection refused“.

Programa veikia pagrindiniame kompiuteryje (host)

PostgreSQL konteineriui reikia paskelbto hosto prievado. Compose tarnyba gali turėti:

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

Tada klientas, veikiantis jūsų hoste, gali naudoti:

postgresql://postgres:JUSU_SLAPTAZODIS@localhost:5432/JUSU_DB

Programa veikia kitame Compose konteineryje

Programos konteineryje localhost reiškia patį programos konteinerį, o ne duomenų bazės konteinerį. Docker Compose suteikia tarnybų pavadinimų DNS, todėl jei duomenų bazės tarnyba pavadinta db, programa paprastai jungiasi prie:

postgresql://postgres:JUSU_SLAPTAZODIS@db:5432/JUSU_DB

Oficiali Docker Compose tinklo dokumentacija aiškiai skiria konteinerio tarpusavio ryšio tarnybos pavadinimą nuo hosto paskelbto prievado. Pavyzdžiui, jei susiejate 8001:5432, konteineriai vis tiek naudoja db:5432, o hostas naudoja localhost:8001. Peržiūrėkite oficialų Docker Compose tinklo vadovą.

Prieš redaguodami patį PostgreSQL, patikrinkite:

docker compose ps
docker compose logs db

Jei konteineris persikrauna, žurnalas dažniausiai yra vertingesnis nei nuolatinis ryšio eilučių keitimas.

7. Ugniasienės taisykles laikykite vėlesniu patikrinimu vietiniam „localhost“ atmetimui

Klientui ir serveriui tame pačiame kompiuteryje nepradėkite nuo prievado 5432 atidarymo visiems tinklams. Pirmiausia įsitikinkite, kad PostgreSQL klauso vietiniu lygmeniu. Plati ugniasienės taisyklė gali sukurti nereikalingą pažeidžiamumą neištaisydama sustabdyto serverio.

Ugniasienės tyrimas tampa aktualesnis, kai:

• PostgreSQL yra VM, konteinerio hoste, WSL aplinkoje ar kitoje tinklo vardų erdvėje.
• Pakeitėte listen_addresses, kad leistumėte ne kilpos (non-loopback) ryšius.
• Vietinė saugumo programinė įranga taiko taisykles kilpai arba programų procesams.
• Klausiklis egzistuoja ir veikia iš vienos aplinkos, bet ne iš kitos.

Jei nuotolinė prieiga yra sąmoninga, apribokite leidžiamus šaltinio tinklus ir autentifikavimo taisykles iki to, kas iš tikrųjų yra būtina. Prievado 5432 pasiekiamumas iš visur nėra vietinės programos sąlyga.

8. Neredaguokite pg_hba.conf, kol serveris nėra pasiekiamas

pg_hba.conf kontroliuoja PostgreSQL kliento autentifikavimą. host įrašas taikomas TCP/IP ryšiams. Jis nepaleidžia sustabdyto serverio klausytis, todėl tai paprastai yra neteisingas pirmasis pataisymas connection refused atveju.

Kai pg_isready praneša, kad serveris priima ryšius, autentifikavimo klaida gali teisėtai nukreipti jus į pg_hba.conf. Localhost TCP ryšiams taisyklės paprastai taikomos kilpos adresams, tokiems kaip 127.0.0.1/32 ir ::1/128, pasirinkus duomenų bazę, vaidmenį ir autentifikavimo metodą, tinkamą jūsų aplinkai.

PostgreSQL 18 numatytoji password_encryption reikšmė yra scram-sha-256, o jos dokumentacija pažymi MD5 šifruotus slaptažodžius kaip pasenusius. Venkite aklai kopijuoti senus autentifikavimo pavyzdžius. Peržiūrėkite dabartinę pg_hba.conf dokumentaciją ir dabartinius autentifikavimo nustatymus.

Unix tipo sistemose pakeitimus pg_hba.conf galima įkelti iš naujo naudojant pg_ctl reload arba SELECT pg_reload_conf();. PostgreSQL dokumentuoja Windows specifinį skirtumą: pakeitimai pg_hba.conf taikomi vėlesniems naujiems ryšiams be to paties SIGHUP reikalavimo.

9. Testuokite su psql, kai klausiklis yra sveikas

Kai pg_isready sako, kad serveris priima ryšius, išbandykite tą patį kelią, kurio tikisi jūsų programa:

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

Sėkmingas psql užklausos ženklas sako daug daugiau nei „tarnyba veikia“: jis patvirtina, kad tikras PostgreSQL klientas pasiekė serverį ir praėjo ryšio bei autentifikavimo etapus tiems parametrams.

Jei psql veikia, tačiau jūsų programa vis tiek praneša „connection refused“, palyginkite programos konfigūraciją simbolis po simbolio:

• Hosto pavadinimas
• Prievadas
• Duomenų bazės pavadinimas
• Vartotojo vardas
• Ar programa veikia hoste, Docker, VM ar kitoje aplinkoje
• Aplinkos kintamieji, kuriuos įkėlė faktinis veikiantis procesas
• Ar programa buvo paleista iš naujo po to, kai pasikeitė jos ryšio eilutė

Dažnas pavyzdys yra vietinis terminalas, sėkmingai naudojantis localhost:5432, tuo tarpu Dockerizuota žiniatinklio programa taip pat naudoja localhost:5432. Tokiu atveju žiniatinklio programa kreipiasi į save, o ne į duomenų bazės tarnybą. Tokiu atveju konteinerio duomenų bazės hosto keitimas į Compose tarnybos pavadinimą yra tinkamas sprendimas.

10. Skaitykite serverio žurnalą, jei PostgreSQL negali išlikti veikiantis

Jei tarnyba paleidžiama ir iškart baigia darbą, tinklo klaida yra tik simptomas. Paleidimo žurnalas yra vieta, kur PostgreSQL paaiškina, kodėl jis negalėjo tapti paruoštas.

Ieškokite pranešimų apie:

• Adresas arba prievadas jau naudojamas
• Neteisinga postgresql.conf sintaksė
• Trūkstamas arba neprieinamas duomenų katalogas
• Failų nuosavybės arba leidimų problemos
• Atkūrimo arba WAL problemos
• Nesuderinamas duomenų katalogas ir serverio pagrindinė versija

Jei tiesiogiai valdomą klasterį paleidžiate su pg_ctl, PostgreSQL rekomenduoja fiksuoti serverio išvestį, pavyzdžiui, naudojant -l logfile. Projekto serverio paleidimo dokumentacija paaiškina, kodėl paleidimo išvestis yra naudinga diagnostikai.

Greita diagnostika pagal scenarijų

Dažni pataisymai, kurie gali pabloginti situaciją

listen_addresses nustatymas į '*' be priežasties

Tai gali padaryti PostgreSQL pasiekiamą iš papildomų sąsajų, tačiau tai nėra būtina įprastam tame pačiame kompiuteryje vykstančiam localhost ryšiui. Tai taip pat gali padidinti pažeidžiamumą. Naudokite siauriausią susiejimą, atitinkantį jūsų architektūrą.

Prievado 5432 atidarymas visam tinklui

Ugniasienės išimtis negali priversti sustabdyto PostgreSQL proceso klausytis. Pirmiausia patvirtinkite klausiklį, tada pridėkite tik tą tinklo prieigą, kurios iš tikrųjų reikia.

postgres slaptažodžio atstatymas ryšio atmetimo atveju

Slaptažodžio autentifikavimas vyksta po to, kai klientas pasiekia PostgreSQL. Jei TCP ryšys atmetamas, slaptažodžio keitimas paprastai sprendžia neteisingą sluoksnį.

Neteisingo postgresql.conf redagavimas

Mašinos su keliais diegimais gali turėti kelis konfigūracijos failus. Kai tik įmanoma, naudokite veikiančią vietinę lizdo jungtį ir SHOW config_file;, arba identifikuokite to serverio proceso, kurį iš tikrųjų ketinate paleisti, duomenų katalogą.

Prielaida, kad 5432 yra privalomas

5432 yra numatytasis, o ne privalomas prievadas. Jei jūsų norimas klasteris sukonfigūruotas 5433 ir visi klientai naudoja 5433, tai yra teisinga. Nuoseklumas yra svarbesnis nei priverstinis numatytojo naudojimas.

Kada turėtumėte keisti savo trikčių šalinimo būdą

Turėtumėte nustoti dirbti su „connection refused“ konkrečiai, kai pg_isready praneša, kad priima ryšius, arba kai psql pasiekia autentifikavimo/duomenų bazės klaidą. Tame etape tinklo klausiklis atlieka savo darbą, ir tolesnis prievadų, ugniasienės taisyklių ar listen_addresses keitimas gali sukelti naujų problemų.

Taip pat, jei PostgreSQL negali paleisti, pereikite nuo kliento pusės trikčių šalinimo prie serverio paleidimo diagnostikos. Jei konteineris nuolat persikrauna, pereikite prie konteinerio žurnalo. Jei hosto klientas veikia, o konteinerio klientas nepavyksta, pereikite prie konteinerio DNS ir prievadų susiejimo. Naudingas klausimas nėra „Kokį PostgreSQL nustatymą turėčiau perjungti?“, o „Kuriame sluoksnyje ryšys nustoja progresuoti?“

Kaip atrodo sėkmingas pataisymas

Galite laikyti localhost pasiekiamumo problemą išspręstą, kai visi šie teiginiai yra teisingi aplinkoje, kurią iš tikrųjų naudojate:

1. pg_isready -h localhost -p 5432 praneša accepting connections, arba praneša ekvivalentų hostą/prievadą, kurį sąmoningai sukonfigūravote.
2. Operacinė sistema rodo, kad PostgreSQL klauso tikėtino adreso ir prievado.
3. psql gali pasiekti serverį naudodamas tą patį tinklo kelią kaip ir programa.
4. Jūsų programa nebegauja connection refused.
5. Jei atsiranda kita PostgreSQL klaida, šalinate tą naują klaidą atskirai, o ne toliau modifikuojate klausiklį.

Šios procedūros riba yra svarbi: ji diagnozuoja, ar PostgreSQL serveris gali būti pasiektas tikėtame hoste ir prievade. Ji viena negali išspręsti neteisingo slaptažodžio, trūkstamo vaidmens, trūkstamos duomenų bazės, SQL klaidos, schemos problemos ar programos ryšių baseino klaidos. Jos tampa aktualios tik tada, kai ryšys praeina atmetimo etapą.

Daugeliu localhost atvejų trumpiausias kelias vis tiek yra tas pats: išbandykite 5432 su pg_isready, patvirtinkite, kad norimas PostgreSQL egzempliorius veikia, patikrinkite klausiklį ir tik tada keiskite konfigūraciją. Tokia tvarka išlaiko trikčių šalinimą fokusuotą ir sumažina tikimybę paversti paprastą sustabdytos tarnybos problemą didesne tinklo ar saugumo problema.