PostgreSQL w Dockerze potrzebuje trwałego miejsca na dane i sprawdzonej drogi odtworzenia. Samo uruchomienie kontenera to dopiero początek. Poniżej zbudujesz małe laboratorium: zapiszesz rekordy, odtworzysz kontener bez utraty danych, wykonasz eksport i przywrócisz go do osobnej bazy.
Przykład używa obrazu postgres:16-alpine. Ta jawna wersja ma znaczenie dla ścieżki danych i późniejszych aktualizacji. Dlatego przed użyciem innej głównej wersji sprawdź ścieżki w jej dokumentacji. W szczególności układ katalogów nowszych obrazów może się różnić.
Co dokładnie uruchamiamy
To lokalne laboratorium bez opublikowanego portu i bez sieci kontenera. Polecenia administracyjne wykonujemy przez docker compose exec. Nie jest to gotowa architektura bazy dla publicznej aplikacji.
Potrzebujesz działającego Dockera i Compose, terminala Bash oraz OpenSSL do utworzenia hasła. Jeżeli dopiero zaczynasz, najpierw przejdź instalację Dockera na VPS.
Utwórz osobny katalog projektu i pracuj w nim podczas wszystkich kolejnych kroków. Nie uruchamiaj ćwiczenia w katalogu produkcyjnego Compose.
mkdir postgres-lab
cd postgres-lab
umask 077
openssl rand -hex 24 > db_password.txt
Hasła nie dodawaj do repozytorium. Plik .gitignore może zawierać:
db_password.txt
*.dump
Konfiguracja Compose i wolumen
Zapisz jako compose.yaml:
services:
db:
image: postgres:16-alpine
environment:
POSTGRES_DB: app
POSTGRES_USER: app
POSTGRES_PASSWORD_FILE: /run/secrets/db_password
secrets: [db_password]
volumes:
- pgdata:/var/lib/postgresql/data
healthcheck:
test: ["CMD-SHELL", "pg_isready -U app -d app"]
interval: 5s
timeout: 3s
retries: 10
mem_limit: 256m
cpus: 0.5
network_mode: none
secrets:
db_password:
file: ./db_password.txt
volumes:
pgdata:
Wolumen zachowuje pliki bazy niezależnie od życia pojedynczego kontenera. Dla użytej wersji montujemy go pod /var/lib/postgresql/data. Mechanizm opisuje osobny poradnik o wolumenach Dockera.
POSTGRES_PASSWORD_FILE pozwala obrazowi odczytać hasło z pliku sekretu. W zwykłym Compose nie oznacza to automatycznie szyfrowanego magazynu sekretów. Plik na hoście nadal wymaga ochrony.
Użytkownik utworzony przez POSTGRES_USER podczas inicjalizacji ma szerokie uprawnienia. W tym laboratorium używamy go do ćwiczeń administracyjnych. Dla aplikacji utwórz osobną rolę z uprawnieniami ograniczonymi do jej bazy i operacji.
Zmienne inicjalizacyjne działają przy tworzeniu pustego katalogu danych. Zmiana hasła w pliku po pierwszym starcie nie jest procedurą zmiany hasła istniejącej roli SQL.
Start i pierwsze rekordy
docker compose up -d
docker compose ps
docker compose logs --tail=50 db
Poczekaj na gotowość usługi. Healthcheck sprawdza, czy PostgreSQL przyjmuje połączenia, ale nie potwierdza poprawności wszystkich tabel i uprawnień aplikacji. Różnicę między tymi kontrolami pokazuje poradnik Docker healthcheck.
Utwórz małą tabelę:
docker compose exec -T db psql -U app -d app -v ON_ERROR_STOP=1 <<'SQL'
CREATE TABLE notes (id integer PRIMARY KEY, body text NOT NULL);
INSERT INTO notes VALUES (1, 'pierwszy wpis'), (2, 'drugi wpis');
SELECT count(*) FROM notes;
SQL
W świeżej bazie otrzymasz dwa rekordy. Ponowne wykonanie całego fragmentu zgłosi istnienie tabeli, dlatego nie traktuj go jako skryptu migracji do wielokrotnego uruchamiania.
Teraz sprawdź trwałość:
docker compose down
docker compose up -d
Po gotowości kontenera odczytaj dane:
docker compose exec -T db psql -U app -d app -c 'SELECT count(*) FROM notes;'
Nie dodawaj do down opcji -v: usuwa ona także wolumeny objęte tą operacją. Zwykłe zatrzymanie kontenera i celowe usunięcie magazynu danych to inne czynności.
Eksport bazy do pliku
Wykonaj archiwum formatu custom:
umask 077
docker compose exec -T db pg_dump -U app -d app -Fc > app.dump
test -s app.dump
Przekierowanie zapisuje plik na hoście. Opcja -T wyłącza pseudoterminal, co jest istotne przy strumieniu danych archiwum. Sprawdź również kod wyjścia polecenia, a nie tylko obecność pliku.
Taki eksport obejmuje wskazaną bazę. Role globalne, konfiguracja hosta i pliki aplikacji wymagają osobnego planu. Ponadto kopia na tym samym dysku nie zabezpiecza przed awarią całego serwera.
Automatyzację z blokadą, plikiem tymczasowym i sumą kontrolną opisuje backup bazy skryptem Bash. Nie dodawaj automatycznego kasowania starszych kopii przed sprawdzeniem odtwarzania.
Odtworzenie do osobnej bazy
Przygotuj nowy cel, zamiast nadpisywać bazę źródłową:
docker compose exec -T db createdb -U app restored
docker compose exec -T db pg_restore -U app -d restored --exit-on-error < app.dump
docker compose exec -T db psql -U app -d restored -c 'SELECT count(*) FROM notes;'
Wynik powinien ponownie wynosić dwa. Jeśli odtwarzanie zgłasza błąd, zachowaj komunikat i sprawdź wersję narzędzia oraz uprawnienia. Sam plik o niezerowym rozmiarze nie dowodzi, że procedura odzyskiwania działa.
W teście przygotowanym do artykułu PostgreSQL 16 zachował dwa rekordy po zatrzymaniu i ponownym uruchomieniu kontenera. Eksport custom odtworzono do drugiej bazy, gdzie sprawdzono tę samą liczbę rekordów. To test poprawności prostego scenariusza, a nie benchmark wydajności ani pełna symulacja awarii dysku.
Jak połączyć prawdziwą aplikację
network_mode: none jest celowe tylko w tym ćwiczeniu. Aplikacja w drugim kontenerze potrzebuje wspólnej sieci i połączenia do nazwy usługi, na przykład db:5432.
W wariancie aplikacyjnym usuń network_mode: none, dodaj wspólną sieć Compose oraz osobną rolę SQL. Nie publikuj portu bazy na wszystkich interfejsach tylko po to, żeby kontenery mogły się komunikować. Wspólną sieć omawia Docker network.
Zdalna administracja może korzystać z tunelu SSH, a reguły połączeń PostgreSQL powinny odpowiadać rzeczywistym klientom. Nie przenoś ustawień laboratoryjnych bez przeglądu do środowiska przechowującego ważne dane.
Aktualizacja wymaga planu
Przed zmianą obrazu wykonaj kopię i próbę odtworzenia. Aktualizacja w obrębie głównej wersji oraz przejście między głównymi wersjami to różne operacje. Nie zakładaj, że wystarczy podmienić 16 na inną liczbę przy tym samym wolumenie.
Zapisz wersję źródła i celu, procedurę migracji, czas niedostępności oraz sposób powrotu. Gotową bazę do dalszego dopracowania znajdziesz w konfiguracji kopii PostgreSQL.
Najczęstsze pytania
Czy usunięcie kontenera usuwa dane?
Nie, jeśli dane są w zachowanym wolumenie. Usunięcie samego wolumenu jest osobną operacją i może zniszczyć bazę.
Czy muszę wystawić port 5432 na VPS?
Nie do komunikacji kontenerów we wspólnej sieci. Dostęp zewnętrzny powinien wynikać z konkretnej potrzeby i konfiguracji.
Czy zmiana POSTGRES_PASSWORD zmieni istniejące hasło?
Nie jest to sposób aktualizacji hasła już utworzonej roli. Zmienne inicjalizacyjne służą do przygotowania pustego katalogu danych.
Czy healthcheck zastępuje test aplikacji?
Nie. Gotowość serwera do przyjmowania połączeń nie potwierdza poprawności zapytań biznesowych.
Źródła
- Oficjalny obraz PostgreSQL, Docker Official Images.
- pg_dump, PostgreSQL Documentation.
- pg_restore, PostgreSQL Documentation.
- Eksport i odtwarzanie, PostgreSQL Documentation.
- Wolumeny, Docker Docs.
- Kontrola gotowości pg_isready, PostgreSQL Documentation.
Data publikacji: 11.11.2026.

Dyskusja