Klaster PostgreSQL nie uruchamia się - jak czytać komunikat pg_ctl

PostgreSQL

Klaster PostgreSQL nie uruchamia się - jak czytać komunikat pg_ctl

W skrócie

pg_ctl to natywne narzędzie PostgreSQL do startu, zatrzymania i restartu klastra (grupy baz obsługiwanej przez jeden serwer). Gdy nie udaje mu się wstać, wypisuje bardzo lakoniczny komunikat - i tu wielu administratorów utyka. W tym wpisie pokazujemy, jak czytać to, co pg_ctl mówi, i skąd wziąć pełny powód. Dotyczy Cię to zwłaszcza wtedy, gdy zarządzasz bazą ręcznie, bez systemd, na przykład w kontenerze albo na starszym serwerze.

Jak to wygląda w praktyce

Klasyczny widok - komenda kończy się porażką, ale bez wyjaśnienia:

$ pg_ctl -D /var/lib/postgresql/16/main start
waiting for server to start....
pg_ctl: could not start server
Examine the log output.

Albo wariant z przekroczeniem czasu, gdy serwer wprawdzie startuje, ale wolno (np. odtwarza dane po awarii):

waiting for server to start.................... stopped waiting
pg_ctl: server did not start in time

Sam pg_ctl nie powie Ci więcej. Zdanie Examine the log output to nie ozdobnik - to dokładna instrukcja, gdzie szukać przyczyny.

Dlaczego tak się dzieje

pg_ctl jest cienką nakładką - jego zadaniem jest wystartować proces serwera postgres, poczekać określony czas i sprawdzić, czy klaster przyjmuje połączenia. Jeśli proces zakończy się błędem podczas inicjalizacji (na przykład uszkodzony plik konfiguracyjny, brak praw, zajęty port, niespójne pliki po twardym wyłączeniu maszyny), pg_ctl widzi tylko, że serwer nie wstał - konkretny komunikat FATAL trafia do logu. Przekroczenie czasu (did not start in time) jest inne - oznacza, że proces żyje, ale nie zdążył w domyślnym oknie czasu (parametr -t). Często tak wygląda odtwarzanie po niekontrolowanym wyłączeniu (crash recovery), gdy serwer przetwarza dziennik WAL, czyli log zmian zapisywanych przed samymi danymi.

Jak to rozwiązać krok po kroku

1. Uruchom start z jawnym plikiem logu, żeby od razu mieć gdzie zajrzeć: pg_ctl -D /var/lib/postgresql/16/main -l /tmp/pg.log start.
2. Zajrzyj do końca logu po powodzie: tail -n 30 /tmp/pg.log (lub do logu klastra w podkatalogu log/). Szukaj linii FATAL albo PANIC.
3. Jeśli to przekroczenie czasu przy odtwarzaniu po awarii - daj serwerowi więcej czasu: pg_ctl -D /var/lib/postgresql/16/main -t 300 -w start i obserwuj log, gdzie widać postęp fazy redo.
4. Jeśli log wskazuje na uszkodzoną konfigurację, sprawdź ją bez pełnego startu: postgres -D /var/lib/postgresql/16/main -C listen_addresses - błędny parametr zostanie wskazany.
5. Jeśli widzisz komunikat o istniejącym pliku postmaster.pid po nagłym wyłączeniu, upewnij się, że żaden proces serwera nie działa (ps -ef | grep postgres), i dopiero wtedy usuń osierocony plik postmaster.pid z katalogu danych.
6. Popraw znalezioną przyczynę i wystartuj ponownie tym samym poleceniem pg_ctl ... start.

Jak sprawdzić, że zadziałało

Po poprawnym starcie pg_ctl pokaże status uruchomionego serwera - sprawdź go wprost:

$ pg_ctl -D /var/lib/postgresql/16/main status
pg_ctl: server is running (PID: 12841)
/usr/lib/postgresql/16/bin/postgres "-D" "/var/lib/postgresql/16/main"

Potwierdź jeszcze, że klaster odpowiada na zapytania - pg_isready zwróci accepting connections, a psql -c "SELECT 1;" zwróci wynik.

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