Czego szukasz?

Wpisz temat, narzędzie lub problem do rozwiązania.

← Wszystkie artykuły

PostgreSQL w Dockerze: konfiguracja, dane i backup krok po kroku

Koralowa obudowa uniesiona ponad jasnym stosem dysków na bordowej podstawie

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

Data publikacji: 11.11.2026.

KP
O AUTORZE

Krystian Proć

Tworzę narzędzia do pracy z danymi, systemy backendowe i automatyzacje. Pracuję z SQL, PHP, TypeScriptem i Dockerem; rozwijam m.in. dragon-island.com. AI pomaga mi przyspieszać pracę, a architekturę, weryfikację i decyzje techniczne biorę na siebie. Na Trybie Technicznym dzielę się doświadczeniami z budowania i utrzymywania własnych projektów.

Dyskusja

Dodaj komentarz

Twój adres email nie zostanie opublikowany. Wymagane pola są oznaczone *