Kako odpraviti napako 'Connection Refused' pri povezavi s PostgreSQL na lokalnem gostitelju, vrata 5432

Če PostgreSQL javi napako »connection refused« na localhost:5432, je prva stvar, ki jo je treba popraviti, dosegljivost, ne geslo. Zaženite pg_isready -h localhost -p 5432. Če poroča no response (ni odgovora), je PostgreSQL običajno ustavljen, posluša na drugih vratih ali naslovu, teče v drugem okolju, kot je Docker, ali pa med zagonom odpove. Če poroča accepting connections (sprejema povezave), je strežnik dosegljiv in prenehajte obravnavati težavo kot težavo z zavrnitvijo vrat ter raziščite naslednje sporočilo o napaki.

PostgreSQL privzeto uporablja TCP vrata 5432, trenutna dokumentacija PostgreSQL 18 pa navaja, da je privzeta vrednost za listen_addresses localhost. Po 11. septembru 2026 je PostgreSQL 18 trenutna stabilna glavna izdaja, pri čemer je bila različica PostgreSQL 18.6 izdana 13. avgusta 2026; PostgreSQL 19 Beta 3 je še vedno razvojna izdaja. Spodnji koraki za odpravljanje težav na splošno veljajo za podprte različice PostgreSQL, vendar se imena paketov, imena storitev in lokacije datotek razlikujejo glede na operacijski sistem in namestitveni program. Glejte uradno napoved izdaje PostgreSQL 18.6 in trenutno dokumentacijo o nastavitvah povezave.

1. Potrdite, da je napaka res »Connection Refused«

Začnite z natančnim besedilom napake. Nekaj napak pri povezavi s PostgreSQL zveni podobno, a kažejo na različne plasti sklada.

Ta razlika prepreči pogosto napačno pot: urejanje gesel ali pg_hba.conf, medtem ko nič ne posluša na vratih 5432. Te nastavitve so pomembne šele, ko povezava doseže strežnik PostgreSQL.

2. Zaženite pg_isready proti natančnemu gostitelju in vratom

pg_isready je lastno orodje PostgreSQL za preverjanje stanja povezave. Zaženite:

pg_isready -h localhost -p 5432

PostgreSQL dokumentira štiri izhodna stanja: 0, ko strežnik sprejema povezave, 1, ko povezave zavrne, 2, ko ni odgovora, in 3, ko ni bil izveden veljaven poskus. Za pridobitev osnovnega stanja strežnika ne potrebujete pravilnega imena baze podatkov, uporabniškega imena ali gesla. Glejte uradno referenco pg_isready.

Če dobite:

• localhost:5432 - accepting connections: vrata 5432 so dosegljiva. Poskusite z dejansko povezavo psql ali aplikacije in odpravite težavo z novim sporočilom, če ta odpove.
• localhost:5432 - rejecting connections: strežnik je odgovoril, a še ne sprejema običajnih povezav, kar se lahko zgodi med zagonom ali obnovitvijo. Preverite dnevnik strežnika in počakajte, če je zagon legitimno v teku.
• localhost:5432 - no response: nadaljujte s spodnjimi preverjanji strežnika in poslušalca.

Izrecno preizkusite tudi 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Če 127.0.0.1 deluje, localhost pa ne, je težava bolj verjetno povezana z razreševanjem imen ali vezavo IPv4/IPv6 kot s popolnim izpadom PostgreSQL.

3. Prepričajte se, da strežnik PostgreSQL deluje

Če ste PostgreSQL namestili prek paketa operacijskega sistema ali namestitvenega programa, uporabite običajni mehanizem za upravljanje storitev tega paketa. Dokumentacija PostgreSQL priporoča uporabo zapakirane infrastrukture za zagon, kadar je na voljo, namesto izmišljanja ločenega načina zagona.

Če neposredno upravljate gručo in poznate njen podatkovni imenik, PostgreSQL zagotavlja pg_ctl:

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

Vrednost -D mora kazati na pravilen podatkovni imenik PostgreSQL, ki je imenik za to gručo baz podatkov. Če je konfiguriran PGDATA, ga lahko pg_ctl uporabi namesto tega. Uradna dokumentacija pg_ctl opisuje ukaze status, start, restart in reload.

Windows

Odprite Storitve in poiščite storitev PostgreSQL, ki jo je ustvaril vaš namestitveni program. Če je ustavljena, jo zaženite. Če je nameščenih več različic PostgreSQL, preverite, ali zaganjate instanco, povezano s podatkovnim imenikom in vrati, ki jih pričakuje vaša aplikacija.

Linux

Imena paketov se med distribucijami razlikujejo. Zapakirana namestitev lahko izpostavi sistemsko storitev, kot je postgresql, ali enoto, specifično za različico/gručo. Uporabite definicijo storitve paketa, namesto da predpostavljate eno univerzalno ime storitve.

macOS

Pravilen mehanizem zagona je odvisen od tega, ali je PostgreSQL prišel iz aplikacijskega paketa, Homebrew, MacPorts, izvorne kode ali drugega paketa. Velja isto načelo: zaženite instanco iz mehanizma, ki jo je ustvaril, nato ponovno zaženite pg_isready.

Če se strežnik takoj znova ustavi, ga ne poskušajte nenehno znova zaganjati. Preglejte njegov dnevnik zagona. Napačna vrednost konfiguracije, nedostopen podatkovni imenik, konflikt vrat, manjkajoča datoteka ali težava z obnovitvijo lahko preprečijo, da bi PostgreSQL ostal aktiven.

4. Preverite, ali kaj dejansko posluša na vratih 5432

Dejstvo, da je proces PostgreSQL aktiven, ni dovolj, če je vezan na druga vrata ali samo na vtičnico Unix domene. Preverite tabelo poslušalcev operacijskega sistema.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Če ni poslušalca, PostgreSQL bodisi ne teče, uporablja druga vrata, je vezan nekje drugje ali pa zagon ni uspel. Če druga programska oprema lasti vrata 5432, morda PostgreSQL ne more vezati teh vrat. Preden se odločite, ali boste ustavili drugi proces ali premaknili PostgreSQL na druga vrata, preverite dnevnik zagona PostgreSQL.

Če ste namenoma konfigurirali PostgreSQL na vratih 5433, mora vaš odjemalec uporabljati 5433:

psql -h localhost -p 5433 -U postgres

Namenoma neprivzetih vrat ne »popravljajte« tako, da PostgreSQL spremenite nazaj na 5432, razen če je to res vaša želena arhitektura.

5. Preverite postgresql.conf: listen_addresses in port

Nastavitev listen_addresses v PostgreSQL nadzira, kateri vmesniki TCP/IP sprejemajo poskuse povezave. Dokumentirana privzeta vrednost je localhost. Nastavitev port ima privzeto vrednost 5432. Obe nastavitvi se uporabita ob zagonu strežnika, zato spremembe zahtevajo ponovni zagon strežnika.

Za strogo lokalno razvojno bazo podatkov so ustrezne nastavitve običajno videti takole:

listen_addresses = 'localhost'
port = 5432

Če je listen_addresses prazen niz, PostgreSQL ne posluša na nobenem IP vmesniku in kjer je podprto, se lahko uporabljajo samo vtičnice Unix domene. Po drugi strani nastavitev listen_addresses = '*' zahteva, da PostgreSQL posluša na vseh razpoložljivih vmesnikih; to je običajno nepotrebno za razvojno bazo podatkov, ki je dostopna samo prek localhosta, in lahko poveča izpostavljenost, če preverjanje pristnosti in pravila požarnega zida niso zasnovana za oddaljen dostop.

Če se lahko povežete prek vtičnice Unix domene, a TCP na localhostu odpove, poizvedite po aktivnem strežniku, da locirate aktivne datoteke in nastavitve:

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

To je varneje kot urejanje prve najdene datoteke postgresql.conf, zlasti na računalniku z več gručami ali različicami PostgreSQL. PostgreSQL podpira konfiguracijske datoteke zunaj podatkovnega imenika, zato poti do datotek niso univerzalne. Glejte uradno dokumentacijo o lokacijah konfiguracijskih datotek.

6. Če PostgreSQL teče v Dockerju, je pomen »localhost« odvisen od tega, kje teče odjemalec

Omrežje kontejnerjev spremeni pomen imena gostitelja. To je eden najpogostejših razlogov, zakaj je baza podatkov zdrava, aplikacija pa še vedno prejme zavrnitev povezave.

Aplikacija teče na gostiteljskem računalniku

Kontejner PostgreSQL potrebuje objavljena gostiteljska vrata. Storitev Compose bi lahko vsebovala:

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

Nato lahko odjemalec, ki teče na vašem gostitelju, uporabi:

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

Aplikacija teče v drugem kontejnerju Compose

Znotraj kontejnerja aplikacije localhost kaže na ta kontejner aplikacije sam, ne na kontejner baze podatkov. Docker Compose zagotavlja DNS imena storitev, zato če je storitev baze podatkov poimenovana db, se aplikacija običajno poveže z:

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

Uradna dokumentacija Docker Compose o omrežjih izrecno razlikuje med imenom storitve med kontejnerji in objavljenimi vrati gostitelja. Na primer, če preslikate 8001:5432, kontejnerji še vedno uporabljajo db:5432, gostitelj pa localhost:8001. Glejte uradni vodnik Docker Compose o omrežjih.

Preden urejate sam PostgreSQL, preverite:

docker compose ps
docker compose logs db

Če se kontejner znova zaganja, je dnevnik običajno bolj koristen kot nenehno spreminjanje nizov povezav.

7. Pravila požarnega zida obravnavajte kot kasnejšo preverbo za zavrnitev na localhostu

Za odjemalca in strežnik na istem računalniku ne začnite tako, da vrata 5432 odprete vsem omrežjem. Najprej potrdite, da PostgreSQL posluša lokalno. Široko pravilo požarnega zida lahko ustvari nepotrebno izpostavljenost, ne da bi popravilo ustavljen strežnik.

Preiskava požarnega zida postane bolj relevantna, ko:

• PostgreSQL je v VM, gostitelju kontejnerja, okolju WSL ali drugem omrežnem prostoru.
• Ste spremenili listen_addresses, da dovolite povezave, ki niso zankovite (non-loopback).
• Lokalna varnostna programska oprema uporablja pravila za zanko (loopback) ali procese aplikacij.
• Poslušalec obstaja in deluje iz enega okolja, ne pa iz drugega.

Če je oddaljen dostop namenoma, omejite dovoljena izvorna omrežja in pravila preverjanja pristnosti na tisto, kar je dejansko potrebno. Dosegljivost vrat 5432 od povsod ni pogoj za lokalno aplikacijo.

8. Ne urejajte pg_hba.conf, dokler strežnik ni dosegljiv

pg_hba.conf nadzira preverjanje pristnosti odjemalcev PostgreSQL. Zapis host velja za povezave TCP/IP. Ne povzroči, da bi ustavljen strežnik začel poslušati, zato je običajno napačen prvi popravek za connection refused.

Ko pg_isready poroča, da strežnik sprejema povezave, lahko napaka pri preverjanju pristnosti upravičeno vodi v pg_hba.conf. Za povezave TCP na localhostu so pravila običajno omejena na naslove zanke, kot sta 127.0.0.1/32 in ::1/128, pri čemer sta baza podatkov, vloga in metoda preverjanja pristnosti izbrani glede na vaše okolje.

PostgreSQL 18 ima privzeto nastavljeno password_encryption na scram-sha-256, njegova dokumentacija pa označuje gesla, šifrirana z MD5, kot zastarela. Ne kopirajte slepo starih primerov preverjanja pristnosti. Glejte trenutno dokumentacijo pg_hba.conf in trenutne nastavitve preverjanja pristnosti.

V sistemih, podobnih Unixu, lahko spremembe v pg_hba.conf ponovno naložite z pg_ctl reload ali SELECT pg_reload_conf();. PostgreSQL dokumentira razliko, specifično za Windows: spremembe v pg_hba.conf se uporabijo za naslednje nove povezave brez iste zahteve po signalu SIGHUP.

9. Preizkusite s psql, ko je poslušalec zdrav

Ko pg_isready pove, da strežnik sprejema povezave, preizkusite isto pot, kot jo pričakuje vaša aplikacija:

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

Uspešen poziv psql vam pove veliko več kot le »storitev teče«: potrjuje, da je pravi odjemalec PostgreSQL dosegel strežnik in prestal faze povezave in preverjanja pristnosti za te parametre.

Če psql deluje, vaša aplikacija pa še vedno javlja zavrnitev povezave, primerjajte konfiguracijo aplikacije znak za znakom:

• Ime gostitelja
• Vrata
• Ime baze podatkov
• Uporabniško ime
• Ali aplikacija teče na gostitelju, v Dockerju, v VM ali v drugem okolju
• Spremenljivke okolja, naložene z dejanskim tekočim procesom
• Ali je bila aplikacija ponovno zagnana po spremembi niza povezave

Pogost primer je lokalni terminal, ki uspešno uporablja localhost:5432, medtem ko spletna aplikacija v Dockerju prav tako uporablja localhost:5432. Spletna aplikacija nato kliče sama sebe, ne storitve baze podatkov. V tem primeru je ustrezna rešitev sprememba gostitelja baze podatkov kontejnerja na ime storitve Compose.

10. Preberite dnevnik strežnika, če PostgreSQL ne more ostati aktiven

Če se storitev zažene in takoj konča, je omrežna napaka le simptom. V dnevniku zagona PostgreSQL pojasni, zakaj ni mogel postati pripravljen.

Iščite sporočila o:

• Naslovu ali vratih, ki so že v uporabi
• Neveljavni sintaksi postgresql.conf
• Manjkajočem ali nedostopnem podatkovnem imeniku
• Težavah z lastništvom datotek ali dovoljenji
• Težavah z obnovitvijo ali WAL
• Nezdružljivosti podatkovnega imenika in glavne različice strežnika

Če zaženete neposredno upravljano gručo z pg_ctl, PostgreSQL priporoča zajemanje izhoda strežnika, na primer z -l logfile. Dokumentacija o zagonu strežnika projekta pojasnjuje, zakaj je izhod zagona koristen za diagnozo.

Hitra diagnoza po scenarijih

Pogosti popravki, ki lahko poslabšajo situacijo

Nastavitev listen_addresses na '*' brez razloga

To lahko omogoči dostop do PostgreSQL z dodatnih vmesnikov, vendar ni potrebno za običajno povezavo localhost na istem računalniku. Prav tako lahko poveča izpostavljenost. Uporabite najožjo vezavo, ki ustreza vaši arhitekturi.

Odpiranje vrat 5432 celotnemu omrežju

Izjema v požarnem zidu ne more povzročiti, da bi ustavljen proces PostgreSQL poslušal. Najprej potrdite poslušalca, nato dodajte samo dostop do omrežja, ki ga dejansko potrebujete.

Ponastavitev gesla postgres zaradi zavrnitve povezave

Preverjanje pristnosti z geslom se zgodi, ko odjemalec doseže PostgreSQL. Če je TCP povezava zavrnjena, sprememba gesla običajno naslavlja napačno plast.

Urejanje napačne datoteke postgresql.conf

Računalniki z več namestitvami lahko vsebujejo več konfiguracijskih datotek. Kadar je mogoče, uporabite delujočo lokalno povezavo z vtičnico in SHOW config_file; ali identificirajte podatkovni imenik procesa strežnika, ki ga dejansko nameravate zagnati.

Predpostavka, da so vrata 5432 obvezna

5432 je privzeta vrednost, ne zahteva. Če je vaša namenjena gruča konfigurirana za 5433 in vsi odjemalci uporabljajo 5433, je to veljavno. Doslednost je pomembnejša kot vsiljevanje privzete vrednosti.

Kdaj morate spremeniti svoj pristop k odpravljanju težav

Pri delu na »connection refused« morate nehati, ko pg_isready poroča o sprejemanju povezav ali ko psql doseže napako pri preverjanju pristnosti/bazi podatkov. V tem trenutku omrežni poslušalec opravlja svoje delo in nadaljnje spreminjanje vrat, pravil požarnega zida ali listen_addresses lahko uvede nove težave.

Prav tako, če se PostgreSQL ne more zagnati, preidite od odpravljanja težav na strani odjemalca k diagnozi zagona strežnika. Če se kontejner nenehno znova zaganja, preidite na dnevnik kontejnerja. Če gostiteljski odjemalec deluje, odjemalec kontejnerja pa odpove, preidite na DNS kontejnerja in preslikavo vrat. Koristno vprašanje ni »Katero nastavitev PostgreSQL naj preklopim?«, temveč »Na kateri plasti povezava preneha napredovati?«

Kako uspešen popravek izgleda

Težavo z dosegljivostjo localhosta lahko štejete za odpravljeno, ko so za okolje, ki ga dejansko uporabljate, resnične vse naslednje trditve:

1. pg_isready -h localhost -p 5432 poroča accepting connections ali poroča o enakovrednem gostitelju/vratih, ki ste jih namenoma konfigurirali.
2. Operacijski sistem prikazuje, da PostgreSQL posluša na pričakovanem naslovu in vratih.
3. psql lahko doseže strežnik z uporabo iste omrežne poti kot aplikacija.
4. Vaša aplikacija ne prejema več connection refused.
5. Če se pojavi drugačna napaka PostgreSQL, to novo napako odpravljate ločeno, namesto da bi še naprej spreminjali poslušalca.

Meja tega postopka je pomembna: diagnosticira, ali je strežnik PostgreSQL dosegljiv na pričakovanem gostitelju in vratih. Sam po sebi ne more popraviti neveljavnega gesla, manjkajoče vloge, manjkajoče baze podatkov, napake SQL, težave s shemo ali napake v bazenu povezav aplikacije. Te postanejo relevantne šele, ko povezava pride mimo faze zavrnitve.

Za večino primerov localhosta je najkrajša pot še vedno enaka: preizkusite 5432 z pg_isready, potrdite, da je namenjena instanca PostgreSQL zagnana, preverite poslušalca in šele nato spremenite konfiguracijo. Ta vrstni red ohranja osredotočenost pri odpravljanju težav in zmanjšuje možnost, da bi preprosto težavo z ustavljeno storitvijo spremenili v večjo omrežno ali varnostno težavo.