# Postgres — lustro baz w SQL (DAN-28) Runbook krok po kroku. Zakłada, że nie pamiętasz nic z rozmowy, w której to powstało. --- ## Co to jest — i czego to NIE jest Postgres trzyma **lustro** plików Excela, żeby wyszukiwanie było szybsze i mądrzejsze. > **ŹRÓDŁEM PRAWDY SĄ PLIKI EXCELA NA NFS.** Utrata tej bazy **nie jest utratą > danych** — odbudowuje się z plików. Dlatego kopie zapasowe Postgresa są tu > **opcjonalne**, a wolumen stoi na `local-path` zamiast na NFS. Po co w ogóle Postgres, skoro danych jest mało (~54 tys. wierszy)? Nie dla skali — przy takim rozmiarze SQLite bywa szybszy. Dla **wyszukiwania w polskim, nieznormalizowanym tekście**: `pg_trgm` (dopasowanie mimo literówek) i `unaccent` (ogonki) nie mają w SQLite taniego zamiennika. --- ## Część 1 — co zrobiłem za Ciebie (w repo) Nic z tego nie wymaga Twojej ręki, ale wiedz, co jest gdzie: | plik | co w nim jest | |---|---| | `astrololo/postgres.yaml` | PVC (5 Gi, `local-path`), ConfigMap z SQL-em inicjalizującym, Deployment (`Recreate`), Service `ClusterIP` | | `astrololo/kustomization.yaml` | `postgres.yaml` dopisany **przed** `data.yaml` | | `astrololo/data.yaml` | `SQL_URL` z sekretu; `DATA_PROVIDER` **zostaje `excel`** | | repo aplikacji: `services/data/requirements.txt` | sterownik `psycopg[binary]` | Decyzje, które w tych plikach zapadły — żeby nie trzeba było ich odtwarzać z głowy: * **`local-path`, nie NFS.** Postgres zakłada semantykę blokad i `fsync`, której NFS nie gwarantuje — to klasyczne źródło uszkodzenia bazy przy nagłym restarcie. Ceną jest przywiązanie do węzła; przy luście odtwarzalnym z Excela to nie boli. * **`strategy: Recreate`.** Wolumen jest `ReadWriteOnce`, a dwa procesy Postgresa na jednym katalogu danych to uszkodzona baza. Rolling próbowałby wstać z nowym podem, zanim stary zejdzie. * **`PGDATA` w podkatalogu** (`…/data/pgdata`). Katalog główny wolumenu potrafi zawierać wpisy systemu plików, a `initdb` odmawia pracy w niepustym katalogu. * **Wersja przypięta (`postgres:17`) i POZA image-updaterem.** Podbicie majora wymaga migracji katalogu danych — nie może się zdarzyć samo, w nocy, przy okazji builda aplikacji. * **`DATA_PROVIDER` zostaje na `excel`.** Postgres można wdrożyć i obejrzeć **bez żadnego ryzyka** dla działającego wyszukiwania. Przełączenie na `sql` to osobna, późniejsza decyzja — po wdrożeniu lustra. --- ## Część 2 — co musisz zrobić Ty ### Krok 0. Sprawdź, że klaster ma `local-path` ```bash kubectl get storageclass ``` Oczekiwany wynik: linia z `local-path` i dopiskiem `(default)`. W k3s jest domyślnie. **Jeśli jej nie ma — zatrzymaj się tutaj** i daj znać; bez niej PVC zawiśnie w `Pending`. ### Krok 1. Utwórz sekret `astrololo-postgres` Ta sama konwencja co `astrololo-auth`: **sekretu nie ma w repo**, bo to repo GitOps i cokolwiek by tu wpadło, zostałoby w historii gita na zawsze. ```bash PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)" kubectl -n astrololo create secret generic astrololo-postgres \ --from-literal=POSTGRES_PASSWORD="$PGPASS" \ --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo" unset PGPASS ``` Hasła **nie musisz nigdzie zapisywać ani nigdy oglądać** — używają go tylko usługi między sobą. Gdybyś kiedyś go potrzebował: ```bash kubectl -n astrololo get secret astrololo-postgres \ -o jsonpath='{.data.POSTGRES_PASSWORD}' | base64 -d; echo ``` > **Dlaczego dwa klucze, skoro hasło jest w obu?** `POSTGRES_PASSWORD` czyta sam > Postgres przy inicjalizacji, `SQL_URL` czyta warstwa danych. Rozdzielone, bo to > dwa różne formaty i dwóch różnych odbiorców — sklejanie DSN-a w manifeście > wymagałoby wstawienia tam hasła. ### Krok 2. Wdróż Jeśli ArgoCD pilnuje katalogu `astrololo`, wystarczy **zmergować PR** — reszta zrobi się sama. Ręcznie: ```bash kubectl apply -k astrololo ``` ### Krok 3. Sprawdź, że wstało ```bash kubectl -n astrololo rollout status deploy/postgres kubectl -n astrololo get pvc postgres-data ``` Oczekiwane: `deployment "postgres" successfully rolled out` i PVC w stanie `Bound`. ### Krok 4. Sprawdź, że rozszerzenia się założyły To jest **najważniejszy sprawdzian tego wdrożenia** — bez tych rozszerzeń cały sens stawiania Postgresa znika. ```bash kubectl -n astrololo exec deploy/postgres -- \ psql -U astrololo -d astrololo -c "\dx" ``` Na liście muszą być **`pg_trgm`** i **`unaccent`**. Sprawdź też, że działają: ```bash kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \ "SELECT unaccent('różdżka') AS bez_ogonkow, similarity(unaccent('różdżka'), 'rozdzka') AS po_zdjeciu_ogonkow, similarity('kowalski', 'kowlaski') > 0.3 AS literowka_lapana;" ``` Oczekiwane **dokładnie**: ``` bez_ogonkow | po_zdjeciu_ogonkow | literowka_lapana -------------+--------------------+------------------ rozdzka | 1 | t ``` Pierwsza kolumna pokazuje, że `unaccent` zna polskie znaki; druga, że po zdjęciu ogonków słowa są **identyczne** (stąd równo `1`); trzecia, że `pg_trgm` łapie przestawione litery. Jeśli druga kolumna nie jest równa `1`, rozszerzenia są, ale reguły `unaccent` nie obsługują polskich znaków — daj znać, bo to zmienia sposób budowania indeksów. ### Krok 5. Sprawdź, że warstwa danych ma połączenie ```bash kubectl -n astrololo rollout restart deploy/data kubectl -n astrololo rollout status deploy/data kubectl -n astrololo logs deploy/data --tail=30 | grep -i -E "sql|postgres|error" || echo "brak wzmianek — OK" ``` Na tym etapie warstwa danych **nadal czyta Excela** (`DATA_PROVIDER=excel`). Postgres tylko stoi i czeka. Aplikacja ma działać dokładnie jak przedtem — i to jest oczekiwany wynik tego wdrożenia. --- ## Część 3 — obsługa na co dzień ### Zajrzeć do bazy ```bash kubectl -n astrololo exec -it deploy/postgres -- psql -U astrololo -d astrololo ``` Przydatne w środku: `\dt mirror.*` (tabele lustra), `\dx` (rozszerzenia), `\l` (bazy), `\q` (wyjście). ### Podłączyć narzędzie graficzne z laptopa Baza **celowo nie jest wystawiona poza klaster**. Na czas jednej sesji: ```bash kubectl -n astrololo port-forward deploy/postgres 5432:5432 ``` i łączysz się na `localhost:5432`, użytkownik `astrololo`, baza `astrololo`, hasło jak w kroku 1. Po zamknięciu terminala tunel znika. ### Dodanie rozszerzenia do ISTNIEJĄCEJ bazy > ⚠️ **Pułapka.** Skrypty z `/docker-entrypoint-initdb.d/` uruchamiają się > **wyłącznie przy pierwszej inicjalizacji**, na pustym katalogu danych. Dopisanie > rozszerzenia do ConfigMapy **nie zrobi nic**, jeśli baza już istnieje. ```bash kubectl -n astrololo exec deploy/postgres -- \ psql -U astrololo -d astrololo -c "CREATE EXTENSION IF NOT EXISTS nazwa;" ``` ### Kopia zapasowa (opcjonalna — patrz nagłówek) ```bash kubectl -n astrololo exec deploy/postgres -- \ pg_dump -U astrololo -d astrololo -Fc > astrololo-$(date +%F).dump ``` Odtworzenie: ```bash kubectl -n astrololo exec -i deploy/postgres -- \ pg_restore -U astrololo -d astrololo --clean --if-exists < astrololo-2026-08-06.dump ``` ### Wyczyścić lustro i wczytać od nowa ```bash kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c \ "DROP SCHEMA mirror CASCADE; CREATE SCHEMA mirror;" ``` Po tym warstwa danych odbuduje lustro z plików Excela (gdy lustro będzie już zaimplementowane — dziś ta komenda tylko czyści pusty schemat). ### Podbicie wersji Postgresa **Nie robi się tego przez zmianę tagu w manifeście.** Major wymaga migracji katalogu danych. Ponieważ to lustro: 1. `kubectl -n astrololo scale deploy/data --replicas=0` 2. skasuj Deployment i **PVC** (`kubectl -n astrololo delete deploy/postgres pvc/postgres-data`) 3. zmień tag obrazu w `postgres.yaml`, wdróż ponownie 4. `kubectl -n astrololo scale deploy/data --replicas=1` — lustro odbuduje się z Excela To jest właśnie ta sytuacja, w której „lustro, nie źródło prawdy" oszczędza dzień pracy. --- ## Co zostało sprawdzone przed oddaniem, a co nie **Sprawdzone:** `kubectl kustomize astrololo` składa komplet 21 zasobów bez błędu; YAML wszystkich manifestów parsuje się poprawnie; audyt odwołań do sekretów potwierdza, że jedyne brakujące to `astrololo-postgres` (oba klucze); DSN `postgresql+psycopg://…` jest poprawnie rozpoznawany przez SQLAlchemy 2.0 z zainstalowanym `psycopg` 3. **NIE sprawdzone, bo nie było na czym:** skrypt inicjalizujący nie został uruchomiony przeciwko prawdziwemu Postgresowi (na maszynie, na której to powstawało, nie ma Dockera). Składnia jest prosta i przejrzana, ale **krok 4 jest tu prawdziwym testem** — jeśli coś ma nie zadziałać, to właśnie tam. --- ## Część 4 — typowe problemy | objaw | przyczyna | co zrobić | |---|---|---| | PVC wisi w `Pending` | brak `local-path` albo brak miejsca na węźle | `kubectl get storageclass`, `kubectl describe pvc postgres-data` | | pod w `CrashLoopBackOff`, w logach `directory not empty` | `PGDATA` wskazuje katalog główny wolumenu | sprawdź, czy `PGDATA` to `…/data/pgdata` (jest w manifeście) | | pod nie startuje, `secret not found` | nie wykonany krok 1 | utwórz sekret i `kubectl -n astrololo rollout restart deploy/postgres` | | `\dx` nie pokazuje `pg_trgm` | baza założona przed dodaniem ConfigMapy | patrz „Dodanie rozszerzenia do istniejącej bazy" | | warstwa danych: `ModuleNotFoundError: psycopg` | obraz zbudowany przed dodaniem sterownika | poczekaj na build z CI albo `kubectl -n astrololo rollout restart deploy/data` po nowym obrazie | | `password authentication failed` | `SQL_URL` w sekrecie nie zgadza się z `POSTGRES_PASSWORD` | odtwórz sekret krokiem 1 (oba klucze naraz) i zrestartuj **oba** deploymenty | Gdy nic nie pasuje — pierwsze dwie komendy do wklejenia: ```bash kubectl -n astrololo describe pod -l app=postgres | tail -30 kubectl -n astrololo logs deploy/postgres --tail=50 ``` --- ## Część 5 — pełne odtworzenie ręczne, bez ArgoCD i bez repo Gdyby trzeba było postawić to od zera na czystym klastrze: ```bash kubectl create namespace astrololo PGPASS="$(openssl rand -base64 24 | tr -d '/+=' | head -c 32)" kubectl -n astrololo create secret generic astrololo-postgres \ --from-literal=POSTGRES_PASSWORD="$PGPASS" \ --from-literal=SQL_URL="postgresql+psycopg://astrololo:${PGPASS}@postgres:5432/astrololo" unset PGPASS kubectl apply -f astrololo/postgres.yaml kubectl -n astrololo rollout status deploy/postgres kubectl -n astrololo exec deploy/postgres -- psql -U astrololo -d astrololo -c "\dx" ``` Reszta aplikacji wymaga jeszcze sekretów `astrololo-auth` i `astrololo-link` — patrz [README.md](README.md).