Kā novērst PostgreSQL savienojuma atteikumu localhost portā 5432

Ja PostgreSQL norāda “connection refused” (savienojums atteikts) uz localhost:5432, pirmā lieta, kas jānovērš, ir sasniedzamība, nevis parole. Palaidiet pg_isready -h localhost -p 5432. Ja tas ziņo no response (nav atbildes), PostgreSQL parasti ir apstādināts, klausās citā portā vai adresē, darbojas citā vidē, piemēram, Docker, vai neizdodas sāknēšanas laikā. Ja tas ziņo accepting connections (pieņem savienojumus), serveris ir sasniedzams, un jums jāpārtrauc problēmas traktēšana kā porta atteikuma problēma un jāizmeklē nākamais kļūdas paziņojums.

PostgreSQL pēc noklusējuma izmanto TCP portu 5432, un pašreizējā PostgreSQL 18 dokumentācija norāda, ka listen_addresses noklusējuma vērtība ir localhost. Līdz 2026. gada 11. septembrim PostgreSQL 18 ir pašreizējais stabilais galvenais izlaidums, un PostgreSQL 18.6 tika izlaists 2026. gada 13. augustā; PostgreSQL 19 Beta 3 joprojām ir izstrādes izlaidums. Tālāk norādītās problēmu novēršanas darbības plaši attiecas uz atbalstītajām PostgreSQL versijām, taču pakotņu nosaukumi, servisu nosaukumi un failu atrašanās vietas atšķiras atkarībā no operētājsistēmas un instalētāja. Skatiet oficiālo PostgreSQL 18.6 izlaiduma paziņojumu un pašreizējo savienojuma iestatījumu dokumentāciju.

1. Pārliecinieties, ka kļūda tiešām ir “Connection Refused”

Sāciet ar precīzu kļūdas tekstu. Dažas PostgreSQL savienojuma kļūmes skan līdzīgi, taču norāda uz dažādiem steka slāņiem.

Šī atšķirība novērš bieži sastopamu novirzi: paroli vai pg_hba.conf rediģēšanu, kamēr nekas neklausās portā 5432. Šie iestatījumi ir svarīgi tikai tad, kad savienojums sasniedz PostgreSQL serveri.

2. Palaidiet pg_isready pret precīzo resursdatoru un portu

pg_isready ir PostgreSQL paša savienojuma statusa utilīta. Palaidiet:

pg_isready -h localhost -p 5432

PostgreSQL dokumentē četras izejas stāvokļus: 0, kad serveris pieņem savienojumus, 1, kad tas noraida savienojumus, 2, kad nav atbildes, un 3, kad netika veikts derīgs mēģinājums. Jums nav nepieciešams pareizs datubāzes nosaukums, lietotājvārds vai parole, lai iegūtu pamata servera statusu. Skatiet oficiālo pg_isready atsauces dokumentāciju.

Ja saņemat:

• localhost:5432 - accepting connections: ports 5432 ir sasniedzams. Mēģiniet savu īsto psql vai lietojumprogrammas savienojumu un, ja tas neizdodas, novērsiet jauno paziņojumu.
• localhost:5432 - rejecting connections: serveris atbildēja, bet vēl nepieņem normālus savienojumus, kas var notikt sāknēšanas vai atjaunošanas laikā. Pārbaudiet servera žurnālu un pagaidiet, ja sāknēšana ir leģitīmi procesā.
• localhost:5432 - no response: turpiniet ar tālāk norādītajām servera un klausītāja pārbaudēm.

Tāpat eksplicīti pārbaudiet 127.0.0.1:

pg_isready -h 127.0.0.1 -p 5432

Ja 127.0.0.1 darbojas, bet localhost nē, problēma, visticamāk, ir saistīta ar nosaukuma atrisināšanu vai IPv4/IPv6 piesaisti, nevis ar to, ka PostgreSQL ir pilnībā apstājies.

3. Pārliecinieties, ka PostgreSQL serveris darbojas

Ja instalējāt PostgreSQL, izmantojot operētājsistēmas pakotni vai instalētāju, izmantojiet šīs pakotnes parasto servisa pārvaldības mehānismu. PostgreSQL paša dokumentācija iesaka izmantot iepakoto sāknēšanas infrastruktūru, ja tā ir pieejama, nevis izgudrot atsevišķu sāknēšanas metodi.

Ja pārvaldāt klasteri tieši un zināt tā datu direktoriju, PostgreSQL nodrošina pg_ctl:

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

Vērtībai -D ir jānorāda uz pareizo PostgreSQL datu direktoriju, kas ir šīs datubāzes klastera direktorija. Ja PGDATA ir konfigurēts, pg_ctl var to izmantot tā vietā. Oficiālā pg_ctl dokumentācija apraksta status, start, restart un reload.

Windows

Atveriet Pakalpojumus (Services) un meklējiet jūsu instalētāja izveidoto PostgreSQL servisu. Ja tas ir apstādināts, palaidiet to. Ja ir instalētas vairākas PostgreSQL versijas, pārliecinieties, ka palaižat instanci, kas saistīta ar datu direktoriju un portu, ko jūsu lietojumprogramma sagaida.

Linux

Pakotņu nosaukumi atšķiras dažādās distribūcijās. Iepakota instalācija var izpaust sistēmas servisu, piemēram, postgresql, vai versijas/klastera specifisku vienību. Izmantojiet pakotnes servisa definīciju, nevis pieņemiet vienu universālu servisa nosaukumu.

macOS

Pareizais sāknēšanas mehānisms ir atkarīgs no tā, vai PostgreSQL nāk no lietotnes pakotnes, Homebrew, MacPorts, avota koda vai citas pakotnes. Tas pats princips attiecas: palaidiet instanci no mehānisma, kas to izveidoja, un pēc tam vēlreiz palaidiet pg_isready.

Ja serveris uzreiz atkal apstājas, nepārtrauciet to pārstartēt. Apskatiet tā sāknēšanas žurnālu. Nepareiza konfigurācijas vērtība, nepieejama datu direktorija, porta konflikts, trūkstošs fails vai atjaunošanas problēma var neļaut PostgreSQL palikt darbspējīgam.

4. Pārbaudiet, vai kaut kas tiešām klausās portā 5432

Darbojošs PostgreSQL process nav pietiekami, ja tas ir piesaistīts citam portam vai tikai Unix domēna ligzdai. Pārbaudiet operētājsistēmas klausītāju tabulu.

Linux

ss -ltnp | grep 5432

macOS

lsof -nP -iTCP:5432 -sTCP:LISTEN

Windows PowerShell

Get-NetTCPConnection -LocalPort 5432 -State Listen

Ja klausītāja nav, tad vai nu PostgreSQL nedarbojas, izmanto citu portu, ir piesaistīts citur, vai neizdevās sākt. Ja citai programmai pieder ports 5432, PostgreSQL var nespēt piesaistīt šo portu. Pirms izlemt, vai apturēt citu procesu, vai pārvietot PostgreSQL uz citu portu, pārbaudiet PostgreSQL sāknēšanas žurnālu.

Ja jūs apzināti konfigurējāt PostgreSQL portā 5433, piemēram, jūsu klientam ir jāizmanto 5433:

psql -h localhost -p 5433 -U postgres

Nenovērsiet “apzinātu nenoklusējuma portu”, mainot PostgreSQL atpakaļ uz 5432, ja tas nav jūsu faktiski vēlamā arhitektūra.

5. Pārbaudiet postgresql.conf: listen_addresses un port

PostgreSQL iestatījums listen_addresses kontrolē, kuri TCP/IP interfeisi pieņem savienojuma mēģinājumus. Dokumentētā noklusējuma vērtība ir localhost. Iestatījums port pēc noklusējuma ir 5432. Abi iestatījumi tiek piemēroti servera sāknēšanas laikā, tāpēc izmaiņām ir nepieciešama servera pārstartēšana.

Stingri lokālai izstrādes datubāzei attiecīgie iestatījumi parasti izskatās šādi:

listen_addresses = 'localhost'
port = 5432

Ja listen_addresses ir tukša virkne, PostgreSQL neklausās nevienā IP interfeisā, un tikai Unix domēna ligzdas var tikt izmantotas tur, kur tās ir atbalstītas. Pretēji tam, iestatījums listen_addresses = '*' liek PostgreSQL klausīties visos pieejamajos interfeisos; tas parasti nav nepieciešams tikai localhost izstrādes datubāzei un var palielināt iedarbību, ja autentifikācija un ugunsmūra noteikumi nav paredzēti attālinātai piekļuvei.

Ja varat izveidot savienojumu caur Unix domēna ligzdu, bet TCP uz localhost neizdodas, vaicājiet aktīvajam serverim, lai atrastu aktīvos failus un iestatījumus:

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

Tas ir drošāk nekā rediģēt pirmo atrasto postgresql.conf, īpaši mašīnā ar vairākiem klasteriem vai PostgreSQL versijām. PostgreSQL atbalsta konfigurācijas failus ārpus datu direktorijas, tāpēc failu ceļi nav universāli. Skatiet oficiālo konfigurācijas failu atrašanās vietu dokumentāciju.

6. Ja PostgreSQL darbojas Docker, “localhost” ir atkarīgs no tā, kur darbojas klients

Konteineru tīklojums maina resursdatora nosaukuma nozīmi. Tas ir viens no biežākajiem iemesliem, kāpēc datubāze ir vesela, bet lietojumprogramma joprojām saņem savienojuma atteikumu.

Lietojumprogramma darbojas resursdatora mašīnā

PostgreSQL konteineram ir nepieciešams publicēts resursdatora ports. Compose servisā var būt:

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

Tad klients, kas darbojas jūsu resursdatorā, var izmantot:

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

Lietojumprogramma darbojas citā Compose konteinerā

Lietojumprogrammas konteinera iekšienē localhost attiecas uz šo pašu lietojumprogrammas konteineru, nevis uz datubāzes konteineru. Docker Compose nodrošina servisa nosaukuma DNS, tāpēc, ja datubāzes serviss ir nosaukts db, lietojumprogramma parasti izveido savienojumu ar:

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

Docker oficiālā Compose tīklojuma dokumentācija skaidri atšķir konteinera savstarpējo servisa nosaukumu no resursdatora publicētā porta. Piemēram, ja kartējat 8001:5432, konteineri joprojām izmanto db:5432, bet resursdators izmanto localhost:8001. Skatiet Docker oficiālo Compose tīklojuma ceļvedi.

Pirms rediģēt pašu PostgreSQL, pārbaudiet:

docker compose ps
docker compose logs db

Ja konteiners tiek pārstartēts, žurnāls parasti ir vērtīgāks nekā atkārtota savienojuma virkņu mainīšana.

7. Ugunsmūra noteikumus uzskatiet par vēlāku pārbaudi localhost atteikumam

Klientam un serverim vienā un tajā pašā mašīnā nesāciet ar porta 5432 atvēršanu visiem tīkliem. Vispirms pārliecinieties, ka PostgreSQL klausās lokāli. Plašs ugunsmūra noteikums var radīt nevajadzīgu iedarbību, nenovēršot apstādinātu serveri.

Ugunsmūra izmeklēšana kļūst aktuālāka, kad:

• PostgreSQL atrodas VM, konteinera resursdatorā, WSL vidē vai citā tīkla nosaukumu telpā.
• Jūs mainījāt listen_addresses, lai atļautu ne-cilpas (non-loopback) savienojumus.
• Lokālā drošības programmatūra piemēro noteikumus cilpas (loopback) vai lietotņu procesiem.
• Klausītājs eksistē un darbojas no vienas vides, bet ne no citas.

Ja attālināta piekļuve ir apzināta, ierobežojiet atļautos avota tīklus un autentifikācijas noteikumus līdz tam, kas faktiski ir nepieciešams. Portam 5432 jābūt sasniedzamam no visurienes, lai tas būtu priekšnoteikums lokālai lietojumprogrammai.

8. Nerediģējiet pg_hba.conf, līdz serveris ir sasniedzams

pg_hba.conf kontrolē PostgreSQL klienta autentifikāciju. host ieraksts attiecas uz TCP/IP savienojumiem. Tas neizraisa apstādināta servera klausīšanos, tāpēc tas parasti ir nepareizs pirmais risinājums connection refused.

Kad pg_isready ziņo, ka serveris pieņem savienojumus, autentifikācijas kļūda var likumīgi novest pie pg_hba.conf. Lokālajiem TCP savienojumiem noteikumi parasti ir ierobežoti līdz cilpas adresēm, piemēram, 127.0.0.1/32 un ::1/128, izvēloties datubāzi, lomu un autentifikācijas metodi jūsu videi.

PostgreSQL 18 noklusējuma vērtība password_encryption ir scram-sha-256, un tās dokumentācija atzīmē MD5 šifrētas paroles kā novecojušas. Neakli kopējiet vecus autentifikācijas piemērus. Skatiet pašreizējo pg_hba.conf dokumentāciju un pašreizējos autentifikācijas iestatījumus.

Unix līdzīgās sistēmās izmaiņas pg_hba.conf var ielādēt ar pg_ctl reload vai SELECT pg_reload_conf();. PostgreSQL dokumentē Windows specifisku atšķirību: izmaiņas pg_hba.conf tiek piemērotas turpmākiem jauniem savienojumiem bez tā paša SIGHUP prasības.

9. Testējiet ar psql, kad klausītājs ir vesels

Kad pg_isready saka, ka serveris pieņem savienojumus, testējiet to pašu ceļu, ko jūsu lietojumprogramma sagaida:

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

Veiksmīgs psql aicinājums pasaka daudz vairāk nekā “serviss darbojas”: tas apstiprina, ka īsts PostgreSQL klients sasniedza serveri un izgāja savienojuma un autentifikācijas posmus šiem parametriem.

Ja psql darbojas, bet jūsu lietojumprogramma joprojām ziņo par savienojuma atteikumu, salīdziniet lietojumprogrammas konfigurāciju rakstzīmi pa rakstzīmi:

• Resursdatora nosaukums
• Ports
• Datubāzes nosaukums
• Lietotājvārds
• Vai lietotne darbojas resursdatorā, Docker, VM vai citā vidē
• Vides mainīgie, ko ielādē faktiskais darbojošais process
• Vai lietojumprogramma tika pārstartēta pēc tās savienojuma virknes maiņas

Bieži sastopams piemērs ir lokāls terminālis, kas veiksmīgi izmanto localhost:5432, kamēr Dockerizēta tīmekļa lietotne arī izmanto localhost:5432. Tīmekļa lietotne tad zvana sev, nevis datubāzes servisam. Šajā gadījumā konteinera datubāzes resursdatora maiņa uz Compose servisa nosaukumu ir attiecīgais risinājums.

10. Lasiet servera žurnālu, ja PostgreSQL nevēlas palikt darbspējīgs

Ja serviss sākas un uzreiz izbeidzas, tīkla kļūda ir tikai simptoms. Sāknēšanas žurnāls ir vieta, kur PostgreSQL paskaidro, kāpēc tas nevarēja kļūt gatavs.

Meklējiet paziņojumus par:

• Adrese vai ports jau tiek izmantots
• Nederīga postgresql.conf sintakse
• Trūkstoša vai nepieejama datu direktorija
• Failu īpašnieka vai atļauju problēmas
• Atjaunošanas vai WAL problēmas
• Nesaderīga datu direktorija un servera galvenā versija

Ja sākat tieši pārvaldītu klasteri ar pg_ctl, PostgreSQL iesaka sagrābt servera izvadi, piemēram, ar -l logfile. Projekta servera sāknēšanas dokumentācija paskaidro, kāpēc sāknēšanas izvade ir noderīga diagnostikai.

Ātra diagnostika pēc scenārija

Bieži risinājumi, kas var pasliktināt situāciju

Iestatīt listen_addresses uz '*' bez iemesla

Tas var padarīt PostgreSQL sasniedzamu no papildu interfeisiem, bet tas nav nepieciešams normālam vienā mašīnā esošam localhost savienojumam. Tas var arī paplašināt iedarbību. Izmantojiet šaurāko piesaisti, kas atbilst jūsu arhitektūrai.

Atvērt portu 5432 visam tīklam

Ugunsmūra izņēmums nevar likt apstādinātam PostgreSQL procesam klausīties. Vispirms apstipriniet klausītāju, pēc tam pievienojiet tikai to tīkla piekļuvi, kas jums faktiski ir nepieciešama.

Atiestatīt postgres paroli savienojuma atteikumam

Paroles autentifikācija notiek pēc tam, kad klients sasniedz PostgreSQL. Ja TCP savienojums tiek atteikts, paroles maiņa parasti risina nepareizo slāni.

Rediģēt nepareizo postgresql.conf

Mašīnās ar vairākām instalācijām var būt vairāki konfigurācijas faili. Kad vien iespējams, izmantojiet darbojošos lokālo ligzdas savienojumu un SHOW config_file;, vai identificējiet servera procesa datu direktoriju, kuru jūs faktiski domājat palaist.

Pieņemt, ka 5432 ir obligāts

5432 ir noklusējums, nevis prasība. Ja jūsu paredzētais klasteris ir konfigurēts portam 5433 un visi klienti izmanto 5433, tas ir derīgi. Konsekvence ir svarīgāka nekā noklusējuma uzspiešana.

Kad mainīt savu problēmu novēršanas pieeju

Jums jāpārtrauc darbs pie “connection refused” konkrēti, kad pg_isready ziņo par savienojumu pieņemšanu vai psql sasniedz autentifikācijas/datubāzes kļūdu. Šajā brīdī tīkla klausītājs dara savu darbu, un turpināt mainīt portus, ugunsmūra noteikumus vai listen_addresses var radīt jaunas problēmas.

Tāpat, ja PostgreSQL nevar sākties, pārejiet no klienta puses problēmu novēršanas uz servera sāknēšanas diagnostiku. Ja konteiners nepārtraukti pārstartējas, pārejiet uz konteinera žurnālu. Ja resursdatora klients strādā, bet konteinera klients neizdodas, pārejiet uz konteinera DNS un porta kartēšanu. Noderīgais jautājums nav “Kuru PostgreSQL iestatījumu man pārslēgt?”, bet gan “Kurā slānī savienojums pārstāj progresēt?”

Kā izskatās veiksmīgs risinājums

Jūs varat uzskatīt localhost sasniedzamības problēmu par novērstu, ja visi tālāk norādītie nosacījumi ir patiesi videi, kuru jūs faktiski izmantojat:

1. pg_isready -h localhost -p 5432 ziņo accepting connections, vai ziņo par ekvivalento resursdatoru/portu, kuru jūs apzināti konfigurējāt.
2. Operētājsistēma rāda, ka PostgreSQL klausās paredzētajā adresē un portā.
3. psql var sasniegt serveri, izmantojot to pašu tīkla ceļu kā lietojumprogramma.
4. Jūsu lietojumprogramma vairs nesaņem connection refused.
5. Ja parādās cita PostgreSQL kļūda, jūs novēršat šo jauno kļūdu atsevišķi, nevis turpināt modificēt klausītāju.

Šīs procedūras robeža ir svarīga: tā diagnosticē, vai PostgreSQL serveris ir sasniedzams paredzētajā resursdatorā un portā. Tā pati par sevi nevar novērst nederīgu paroli, trūkstošu lomu, trūkstošu datubāzi, SQL kļūdu, shēmas problēmu vai lietojumprogrammas savienojuma kopuma kļūdu. Tās kļūst aktuālas tikai tad, kad savienojums tiek pāri atteikuma posmam.

Vairumā localhost gadījumu īsākais ceļš joprojām ir tāds pats: testējiet 5432 ar pg_isready, apstipriniet, ka paredzētā PostgreSQL instance darbojas, pārbaudiet klausītāju un tikai tad mainiet konfigurāciju. Šī secība saglabā problēmu novēršanu fokusētu un samazina iespēju pārvērst vienkāršu apstādināta servisa problēmu par lielāku tīklojuma vai drošības problēmu.