Nie mogę połączyć się z PostgreSQL - connection refused

PostgreSQL

W skrócie

Problem: klient (na przykład psql, pgAdmin, aplikacja) zwraca connection refused przy próbie połączenia z bazą.
Dlaczego: connection refused to błąd warstwy sieci - na wskazanym adresie i porcie nikt nie nasłuchuje albo blokuje to zapora.
Rozwiązanie: sprawdzamy, czy serwer działa, na jakim adresie nasłuchuje (listen_addresses), czy port się zgadza i czy nie blokuje go zapora.

connection refused myli, bo brzmi jak odmowa logowania - a to błąd znacznie wcześniejszy, jeszcze przed jakimkolwiek sprawdzaniem hasła. Oznacza, że klient w ogóle nie znalazł serwera pod podanym adresem i portem. Ten problem dotyczy każdego, kto łączy się z PostgreSQL z innej maszyny albo z kontenera. Pokazujemy, jak w kilku krokach odróżnić problem sieciowy od problemu z uprawnieniami i jak go usunąć.

Jak to wygląda w praktyce

Z klienta wiersza poleceń wygląda to tak:

$ psql -h 192.168.1.50 -p 5432 -U app -d sklep
psql: error: connection to server at "192.168.1.50", port 5432 failed:
        Connection refused
        Is the server running on that host and accepting TCP/IP connections?

Kluczowe jest ostatnie pytanie z komunikatu - PostgreSQL sam podpowiada, że albo serwer nie działa, albo nie przyjmuje połączeń TCP/IP. To zupełnie inny problem niż password authentication failed (błąd hasła) czy no pg_hba.conf entry (brak reguły dostępu). Tam serwer już odpowiada, tu jeszcze nie odpowiedział wcale.

Dlaczego tak się dzieje

connection refused pochodzi z systemu operacyjnego - dostajesz go, gdy pod danym adresem i portem nic nie nasłuchuje albo pakiet został odrzucony. W kontekście PostgreSQL najczęstsze przyczyny to: serwer jest zatrzymany, serwer nasłuchuje tylko na localhost (domyślne listen_addresses = 'localhost'), więc z innej maszyny jest niewidoczny, łączysz się na zły port, albo między klientem a serwerem stoi zapora sieciowa blokująca port 5432. Ważne rozróżnienie - jeśli serwer odpowiada, ale odrzuca regułę dostępu lub hasło, dostaniesz zupełnie inny komunikat. Connection refused zawsze znaczy: do procesu bazy jeszcze nie dotarłeś.

Jak to rozwiązać krok po kroku

Na serwerze sprawdź, czy klaster w ogóle działa: sudo systemctl status postgresql lub pg_isready -h 127.0.0.1.
Sprawdź, na jakich adresach serwer nasłuchuje: sudo ss -ltnp | grep 5432. Jeśli widzisz tylko 127.0.0.1:5432, serwer nie przyjmie połączeń z sieci.
Jeśli potrzebujesz dostępu z sieci, ustaw w postgresql.conf nasłuch na właściwych interfejsach, na przykład listen_addresses = '*', i zrestartuj serwer (to zmiana wymagająca restartu, nie reload).
Upewnij się, że łączysz się na właściwy port - domyślnie 5432, ale drugi klaster często siedzi na 5433. Sprawdź parametr port w postgresql.conf.
Sprawdź zaporę po stronie serwera: sudo ufw status albo sudo firewall-cmd --list-ports. Otwórz port, na przykład sudo ufw allow 5432/tcp, jeśli dostęp ma być z sieci.
Z maszyny klienta zweryfikuj samo połączenie TCP przed użyciem psql: nc -vz 192.168.1.50 5432 - jeśli i to zawodzi, problem jest czysto sieciowy.

Jak sprawdzić, że zadziałało

Najpierw potwierdź samą drogę sieciową z maszyny klienta - jeśli port jest osiągalny, zobaczysz succeeded:

$ nc -vz 192.168.1.50 5432
Connection to 192.168.1.50 5432 port [tcp/postgresql] succeeded!

Potem spróbuj właściwego połączenia. Gdy zamiast connection refused pojawi się prośba o hasło albo błąd dostępu, warstwa sieci działa - dalsze błędy są już z obszaru uprawnień:

$ psql -h 192.168.1.50 -p 5432 -U app -d sklep

Poczytaj więcej
Lekcja z kursu PostgreSQL na ten temat
Cały bezpłatny kurs administracji PostgreSQL

Wróć do listy: 100 najczęstszych pytań i problemów z PostgreSQL

Sprawdź szkolenie: Administracja, replikacja i tuning baz danych PostgreSQL

To szkolenie może być dofinansowane z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5

Sprawdź szkolenie: Zaawansowana administracja PostgreSQL (HA, DR, monitoring, skalowanie)

To szkolenie może być dofinansowane z KFS lub BUR.

★★★★★Średnia ocena naszych szkoleń w Google: 5/5

Autorzy

Tekst: Redakcja JSystems

Najczęściej zadawane pytania

Czym różni się connection refused od password authentication failed?

Connection refused to błąd sieciowy - klient nie dotarł do procesu bazy, bo nikt nie nasłuchuje na danym adresie i porcie albo blokuje to zapora. Password authentication failed pojawia się później, gdy serwer już odpowiedział, przyjął połączenie, ale odrzucił hasło. Pierwszy naprawiamy w sieci i w listen_addresses, drugi w haśle i w pliku pg_hba.conf.

Dlaczego z innej maszyny dostaję connection refused, a lokalnie działa?

Najczęściej dlatego, że serwer ma domyślne listen_addresses ustawione na localhost i nasłuchuje tylko na pętli zwrotnej 127.0.0.1. Lokalnie widać go bez problemu, ale z sieci jest niewidoczny. Trzeba ustawić listen_addresses na konkretny adres lub gwiazdkę i zrestartować serwer, a także upewnić się, że zapora nie blokuje portu 5432.

Jak sprawdzić, czy problem jest w sieci, czy w samej bazie?

Użyj narzędzia sieciowego bez udziału bazy, na przykład nc -vz host 5432 z maszyny klienta. Jeśli połączenie TCP nie przechodzi, problem jest sieciowy - serwer nie działa, nasłuchuje na złym adresie albo blokuje go zapora. Jeśli port jest osiągalny, a mimo to psql zwraca błąd, przyczyna leży już w uprawnieniach albo w haśle.

Czy zmiana listen_addresses wystarczy przez reload, czy trzeba restart?

Parametr listen_addresses wymaga restartu serwera - nie wystarczy pg_ctl reload ani SELECT pg_reload_conf(). Dopiero przy pełnym starcie serwer otwiera gniazda nasłuchu na nowych adresach. Po zmianie w postgresql.conf wykonaj sudo systemctl restart postgresql lub pg_ctl restart i dopiero wtedy nowy nasłuch będzie aktywny.