Näin korjaat PostgreSQL-yhteyden hylkäämisen virheen paikallisella portilla 5432

Jos PostgreSQL ilmoittaa "connection refused" (yhteys hylätty) osoitteessa localhost:5432, ensimmäinen asia korjata on saavutettavuus, ei salasana. Suorita pg_isready -h localhost -p 5432. Jos se ilmoittaa no response (ei vastausta), PostgreSQL on yleensä pysäytetty, kuuntelee eri portissa tai osoitteessa, toimii eri ympäristössä kuten Dockerissa, tai epäonnistuu käynnistyksen aikana. Jos se ilmoittaa accepting connections (hyväksyy yhteydet), palvelin on saavutettavissa, ja sinun tulee lopettaa ongelman käsittely portinhylkäysongelmana ja tutkia sen sijaan seuraavaa virheilmoitusta.

PostgreSQL käyttää oletuksena TCP-porttia 5432, ja nykyinen PostgreSQL 18 -dokumentaatio kertoo, että listen_addresses on oletusarvoisesti localhost. Tämän artikkelin kirjoitushetkellä (11. syyskuuta 2026) PostgreSQL 18 on nykyinen vakaa pääjulkaisu, ja PostgreSQL 18.6 julkaistiin 13. elokuuta 2026; PostgreSQL 19 Beta 3 on edelleen kehitysversio. Seuraavat vianmääritysvaiheet pätevät laajasti tuettuihin PostgreSQL-versioihin, mutta pakettien nimet, palvelun nimet ja tiedostosijainnit vaihtelevat käyttöjärjestelmän ja asennusohjelman mukaan. Katso virallinen PostgreSQL 18.6 -julkaisuilmoitus ja nykyinen yhteysasetusten dokumentaatio.

1. Varmista, että virhe on todella "Connection Refused"

Aloita tarkasta virhetekstistä. Useat PostgreSQL-yhteysvirheet kuulostavat samankaltaisilta, mutta viittaavat eri kerroksiin pinossa.

Tämä erottelu estää yleisen harhaanjohtavan polun: salasanojen tai pg_hba.conf:n muokkaaminen, kun portissa 5432 ei kuuntele kukaan. Nämä asetukset ovat tärkeitä vasta, kun yhteys tavoittaa PostgreSQL-palvelimen.

2. Suorita pg_isready tarkkaa isäntäkone- ja porttiparia vasten

pg_isready on PostgreSQL:n oma yhteystilan apuohjelma. Suorita:

pg_isready -h localhost -p 5432

PostgreSQL dokumentoi neljä poistumistilaa: 0, kun palvelin hyväksyy yhteyksiä, 1, kun se hylkää yhteyksiä, 2, kun vastausta ei tule, ja 3, kun kelvollista yritystä ei tehty. Et tarvitse oikeaa tietokannan nimeä, käyttäjätunnusta tai salasanaa pelkän peruspalvelintilan saamiseksi. Katso virallinen pg_isready -viite.

Jos saat:

• localhost:5432 - accepting connections: portti 5432 on saavutettavissa. Kokeile todellista psql- tai sovellusyhteyttäsi ja vianmäärää uusi viesti, jos se epäonnistuu.
• localhost:5432 - rejecting connections: palvelin vastasi, mutta ei vielä hyväksy normaaleja yhteyksiä, mikä voi tapahtua käynnistyksen tai palautumisen aikana. Tarkista palvelinloki ja odota, jos käynnistys on aidosti käynnissä.
• localhost:5432 - no response: jatka alla olevilla palvelin- ja kuuntelijatarkistuksilla.

Testaa myös 127.0.0.1 eksplisiittisesti:

pg_isready -h 127.0.0.1 -p 5432

Jos 127.0.0.1 toimii mutta localhost ei, ongelma liittyy todennäköisemmin nimipalveluun tai IPv4/IPv6-sidontaan kuin siihen, että PostgreSQL olisi täysin alhaalla.

3. Varmista, että PostgreSQL-palvelin on käynnissä

Jos asensit PostgreSQL:n käyttöjärjestelmän paketin tai asennusohjelman kautta, käytä kyseisen paketin normaalia palvelunhallintamekanismia. PostgreSQL:n oma dokumentaatio suosittelee paketoitujen käynnistysinfrastruktuurien käyttöä, kun ne ovat saatavilla, sen sijaan että keksisi erillisen käynnistysmenetelmän.

Jos hallinnoit clusteria suoraan ja tiedät sen datahakemiston, PostgreSQL tarjoaa pg_ctl:n:

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

-D-arvon on osoitettava oikeaan PostgreSQL:n datahakemistoon, joka on kyseisen tietokantaklusterin hakemisto. Jos PGDATA on määritetty, pg_ctl voi käyttää sitä. Virallinen pg_ctl -dokumentaatio kuvaa komennot status, start, restart ja reload.

Windows

Avaa Palvelut (Services) ja etsi asennusohjelmasi luoma PostgreSQL-palvelu. Jos se on pysäytetty, käynnistä se. Jos useita PostgreSQL-versioita on asennettu, varmista, että käynnistät instanssin, joka liittyy datahakemistoon ja porttiin, jota sovelluksesi odottaa.

Linux

Pakettien nimet vaihtelevat jakelujen välillä. Paketoitu asennus voi tarjota järjestelmäpalvelun, kuten postgresql, tai versio/cluster-kohtaisen yksikön. Käytä paketin palvelumääritelmää olettamatta yhtä universaalia palvelun nimeä.

macOS

Oikea käynnistysmekanismi riippuu siitä, tuliko PostgreSQL sovelluspaketista, Homebrewista, MacPortsista, lähdekoodista vai toisesta paketista. Sama periaate pätee: käynnistä instanssi mekanismilla, joka loi sen, ja suorita pg_isready uudelleen.

Jos palvelin pysähtyy heti uudelleen, älä jatka sen uudelleenkäynnistämistä. Tutki sen käynnistysloki. Virheellinen konfiguraatioarvo, saavuttamaton datahakemisto, porttiristiriita, puuttuva tiedosto tai palautumisongelma voivat estää PostgreSQL:n pysymisen ylhäällä.

4. Varmista, että jokin todella kuuntelee porttia 5432

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Jos kuuntelijaa ei ole, joko PostgreSQL ei ole käynnissä, käyttää toista porttia, on sidottu jonnekin muualle tai epäonnistui käynnistyksessä. Jos toinen ohjelma omistaa portin 5432, PostgreSQL ei ehkä pysty sitomaan kyseistä porttia. Tarkista PostgreSQL:n käynnistysloki ennen kuin päätät, pysäytetäänkö toinen prosessi vai siirretäänkö PostgreSQL toiseen porttiin.

Jos olet tarkoituksella määrittänyt PostgreSQL:n porttiin 5433, esimerkiksi, asiakasohjelmasi on käytettävä porttia 5433:

psql -h localhost -p 5433 -U postgres

Älä "korjaa" tarkoituksellista ei-oletusporttia muuttamalla PostgreSQL takaisin porttiin 5432, ellei se todella ole haluamasi arkkitehtuuri.

5. Tarkista postgresql.conf: listen_addresses ja port

PostgreSQL:n listen_addresses-asetus ohjaa, mitkä TCP/IP-rajapinnat hyväksyvät yhteysyrityksiä. Dokumentoitu oletusarvo on localhost. port-asetus on oletusarvoisesti 5432. Molemmat asetukset otetaan käyttöön palvelimen käynnistyksessä, joten muutokset vaativat palvelimen uudelleenkäynnistyksen.

Tiukasti paikalliselle kehitystietokannalle relevantit asetukset näyttävät yleensä tältä:

listen_addresses = 'localhost'
port = 5432

Jos listen_addresses on tyhjä merkkijono, PostgreSQL ei kuuntele millään IP-rajapinnalla, ja vain Unix-domain-pistokkeita voidaan käyttää, jos ne ovat tuettuja. Päinvastoin, asetus listen_addresses = '*' pyytää PostgreSQL:tä kuuntelemaan kaikkia saatavilla olevia rajapintoja; se on yleensä tarpeetonta localhost-pohjaiselle kehitystietokannalle ja voi lisätä altistumista, jos todennus- ja palomuurisäännöt ei ole suunniteltu etäpääsyä varten.

Jos voit muodostaa yhteyden Unix-domain-pistokkeen kautta mutta TCP localhostissa epäonnistuu, kysy aktiiviselta palvelimelta löytääksesi aktiiviset tiedostot ja asetukset:

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

Tämä on turvallisempaa kuin ensimmäisen löytämäsi postgresql.conf-tiedoston muokkaaminen, erityisesti koneella, jossa on useita clusteria tai PostgreSQL-versioita. PostgreSQL tukee konfiguraatiotiedostoja datahakemiston ulkopuolella, joten tiedostopolut eivät ole universaaleja. Katso virallinen konfiguraatiotiedoston sijainnin dokumentaatio.

6. Jos PostgreSQL toimii Dockerissa, "localhost" riippuu siitä, missä asiakasohjelma toimii

Konttiverkko muuttaa isäntäkone-nimen merkitystä. Tämä on yksi yleisimmistä syistä, miksi tietokanta on kunnossa, mutta sovellus saa silti yhteyden hylkäyksen.

Sovellus toimii isäntäkoneella

PostgreSQL-kontti tarvitsee julkaistun isäntäkone-portin. Compose-palvelu voi sisältää:

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

Tällöin isäntäkoneellasi toimiva asiakasohjelma voi käyttää:

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

Sovellus toimii toisessa Compose-kontissa

Sovelluskontin sisällä localhost viittaa kyseiseen sovelluskonttiin itseensä, ei tietokantakonttiin. Docker Compose tarjoaa palvelunimen DNS-palvelun, joten jos tietokantapalvelu on nimeltään db, sovellus muodostaa yleensä yhteyden:

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

Dockerin virallinen Compose-verkkodokumentaatio erottaa nimenomaan konttien välisen palvelunimen isäntäkoneen julkaistusta portista. Esimerkiksi, jos kartoitat 8001:5432, kontit käyttävät edelleen db:5432, kun taas isäntäkone käyttää localhost:8001. Katso Dockerin virallinen Compose-verkko-opas.

Ennen kuin muokkaat PostgreSQL:tä itse, tarkista:

docker compose ps
docker compose logs db

Jos kontti käynnistyy uudelleen, loki on yleensä arvokkaampi kuin yhteysmerkkijonojen toistuva muuttaminen.

7. Käsittele palomuurisääntöjä myöhempänä tarkistuksena localhost-hylkäykselle

Asiakkaan ja palvelimen ollessa samalla koneella, älä aloita avaamalla porttia 5432 kaikille verkoille. Varmista ensin, että PostgreSQL kuuntelee paikallisesti. Laaja palomuurisääntö voi luoda tarpeetonta altistumista korjaamatta pysäytettyä palvelinta.

Palomuuritutkimus tulee relevantimmaksi, kun:

• PostgreSQL on VM:ssä, kontti-isäntäkoneessa, WSL-ympäristössä tai toisessa verkkonimiavaruudessa.
• Olet muuttanut listen_addresses-asetusta salliaksesi ei-loopback-yhteydet.
• Paikallinen tietoturvaohjelmisto soveltaa sääntöjä loopback- tai sovellusprosesseihin.
• Kuuntelija on olemassa ja toimii yhdestä ympäristöstä mutta ei toisesta.

Jos etäpääsy on tarkoituksellista, rajoita sallitut lähdeverkot ja todennussäännöt siihen, mitä todella tarvitaan. Portin 5432 olemassaolo kaikkialta saavutettavissa ei ole edellytys paikalliselle sovellukselle.

8. Älä muokkaa pg_hba.conf-tiedostoa ennen kuin palvelin on saavutettavissa

pg_hba.conf ohjaa PostgreSQL:n asiakastodennusta. host-tietue koskee TCP/IP-yhteyksiä. Se ei saa pysäytettyä palvelinta alkamaan kuunnella, joten se on yleensä väärä ensimmäinen korjaus connection refused-virheelle.

Kun pg_isready ilmoittaa palvelimen hyväksyvän yhteyksiä, todennusvirhe voi perustellusti johtaa sinut pg_hba.conf-tiedostoon. Localhost-TCP-yhteyksille säännöt on tyypillisesti rajattu loopback-osoitteisiin, kuten 127.0.0.1/32 ja ::1/128, ja tietokanta, rooli ja todennusmenetelmä valitaan ympäristöösi sopiviksi.

PostgreSQL 18 asettaa oletusarvoksi password_encryption-asetukselle scram-sha-256, ja sen dokumentaatio merkitsee MD5-salatut salasanat vanhentuneiksi. Vältä vanhojen todennusesimerkkien sokeaa kopiointia. Katso nykyinen pg_hba.conf-dokumentaatio ja nykyiset todennusasetukset.

Unix-pohjaisissa järjestelmissä pg_hba.conf-muutokset voidaan ladata uudelleen komennolla pg_ctl reload tai SELECT pg_reload_conf();. PostgreSQL dokumentoi Windows-kohtaisen eron: pg_hba.conf-muutokset otetaan käyttöön myöhemmissä uusissa yhteyksissä ilman samaa SIGHUP-vaatimusta.

9. Testaa psql:llä, kun kuuntelija on kunnossa

Kun pg_isready sanoo palvelimen hyväksyvän yhteyksiä, testaa sama reitti, jota sovelluksesi odottaa:

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

Onnistunut psql-kehote kertoo paljon enemmän kuin "palvelu on käynnissä": se vahvistaa, että todellinen PostgreSQL-asiakasohjelma tavoitti palvelimen ja läpäisi yhteyden ja todennuksen vaiheet näillä parametreilla.

Jos psql toimii mutta sovelluksesi ilmoittaa edelleen yhteyden hylkäyksestä, vertaa sovelluksen konfiguraatiota merkki merkiltä:

• Isäntäkoneen nimi
• Portti
• Tietokannan nimi
• Käyttäjätunnus
• Toimiiko sovellus isäntäkoneella, Dockerissa, VM:ssä vai toisessa ympäristössä
• Ympäristömuuttujat, jotka todellinen käynnissä oleva prosessi lataa
• Uudelleenkäynnistettiinkö sovellus sen yhteysmerkkijonon muuttamisen jälkeen

Yleinen esimerkki on paikallinen pääte, joka käyttää localhost:5432:ta onnistuneesti, kun taas Dockeristettu web-sovellus käyttää myös localhost:5432:ta. Web-sovellus kutsuu silloin itseään, ei tietokantapalvelua. Siinä tapauksessa kontin tietokantaisännän muuttaminen Compose-palvelun nimeksi on relevantti korjaus.

10. Lue palvelinloki, jos PostgreSQL ei pysy ylhäällä

Jos palvelu käynnistyy ja poistuu heti, verkkovirhe on vain oire. Käynnistysloki on paikka, jossa PostgreSQL selittää, miksi se ei voinut tulla valmiiksi.

Etsi viestejä, jotka koskevat:

• Osoite tai portti on jo käytössä
• Virheellinen postgresql.conf-syntaksi
• Puuttuva tai saavuttamaton datahakemisto
• Tiedoston omistajuus- tai käyttöoikeusongelmat
• Palautumis- tai WAL-ongelmat
• Yhteensopimaton datahakemisto ja palvelimen pääversio

Jos käynnistät suoraan hallitun clusterin pg_ctl:llä, PostgreSQL suosittelee palvelimen tulosteen kaappaamista, esimerkiksi käyttämällä -l logfile. Projektin palvelimen käynnistysdokumentaatio selittää, miksi käynnistystuloste on hyödyllinen diagnoosissa.

Nopea diagnoosi skenaarion mukaan

Yleiset korjaukset, jotka voivat pahentaa tilannetta

listen_addresses:n asettaminen '*' ilman syytä

Tämä voi tehdä PostgreSQL:stä saavutettavan lisärajapinnoista, mutta se ei ole tarpeen normaaliin saman koneen localhost-yhteyteen. Se voi myös laajentaa altistumista. Käytä kapeinta sidontaa, joka vastaa arkkitehtuuria.

Portin 5432 avaaminen koko verkolle

Palomuuripoikkeus ei saa pysäytettyä PostgreSQL-prosessia kuuntelemaan. Varmista kuuntelija ensin, lisää sitten vain se verkkopääsy, jota todella tarvitset.

Postgres-salasanan nollaaminen yhteyden hylkäystä varten

Salasanatodennus tapahtuu, kun asiakasohjelma tavoittaa PostgreSQL:n. Jos TCP-yhteys hylätään, salasanan muuttaminen käsittelee yleensä väärää kerrosta.

Väärän postgresql.conf-tiedoston muokkaaminen

Koneet, joissa on useita asennuksia, voivat sisältää useita konfiguraatiotiedostoja. Käytä aina kun mahdollista toimivaa paikallista pistokeliitäntää ja SHOW config_file;, tai tunnista sen palvelinprosessin datahakemisto, jonka todella aiot käynnistää.

Oletus, että 5432 on pakollinen

5432 on oletus, ei vaatimus. Jos tarkoitetun clusterin on määritetty porttiin 5433 ja kaikki asiakasohjelmat käyttävät porttia 5433, se on kelvollista. Yhtenäisyys on tärkeämpää kuin oletuksen pakottaminen.

Milloin sinun tulisi muuttaa vianmääritystapaasi

Sinun tulisi lopettaa "connection refused" -ongelman parissa työskentely erityisesti, kun pg_isready ilmoittaa hyväksyvänsä yhteyksiä tai psql saavuttaa todennus-/tietokantavirheen. Siihen mennessä verkkokuuntelija tekee tehtävänsä, ja porttien, palomuurisääntöjen tai listen_addresses-asetusten muuttaminen voi tuoda uusia ongelmia.

Samoin, jos PostgreSQL ei voi käynnistyä, siirry asiakaspuolen vianmäärityksestä palvelimen käynnistysdiagnostiikkaan. Jos kontti käynnistyy jatkuvasti uudelleen, siirry kontin lokiin. Jos isäntäkoneasiakas toimii mutta kontti-asiakas epäonnistuu, siirry kontin DNS:ään ja porttikartoitukseen. Hyödyllinen kysymys ei ole "Mitä PostgreSQL-asetusta minun tulisi vaihtaa?" vaan "Millä kerroksella yhteys lakkaa etenemästä?"

Miltä onnistunut korjaus näyttää

Voit pitää localhost-saavutettavuusongelman korjattuna, kun kaikki seuraavat ovat totta käyttämässäsi ympäristössä:

1. pg_isready -h localhost -p 5432 ilmoittaa accepting connections, tai se ilmoittaa vastaavan isäntäkoneen/portin, jonka olet tarkoituksella määrittänyt.
2. Käyttöjärjestelmä näyttää PostgreSQL:n kuuntelevan odotetussa osoitteessa ja portissa.
3. psql voi tavoittaa palvelimen käyttämällä samaa verkkoreittiä kuin sovellus.
4. Sovelluksesi ei enää saa connection refused-virhettä.
5. Jos eri PostgreSQL-virhe ilmenee, vianmäärität sen uuden virheen erikseen sen sijaan, että jatkat kuuntelijan muokkaamista.

Tämän menettelyn raja on tärkeä: se diagnosoi, voidaanko PostgreSQL-palvelinta tavoittaa odotetussa isäntäkoneessa ja portissa. Se ei yksinään voi korjata virheellistä salasanaa, puuttuvaa roolia, puuttuvaa tietokantaa, SQL-virhettä, skeemaongelmaa tai sovelluksen yhteyspool-virhettä. Nämä tulevat relevantteiksi vasta, kun yhteys pääsee hylkäysvaiheen ohi.

Useimmissa localhost-tapauksissa lyhyin polku on edelleen sama: testaa 5432 pg_isready:llä, varmista tarkoitetun PostgreSQL-instanssin olevan käynnissä, varmista kuuntelija ja vain sen jälkeen muuta konfiguraatiota. Tämä järjestys pitää vianmäärityksen keskittyneenä ja vähentää mahdollisuutta muuttaa yksinkertainen pysäytetty palvelu -ongelma suuremmaksi verkko- tai tietoturvaongelmaksi.