Każdy, kto zarządzał schematem bazy danych dłużej niż tydzień, zna ten ból: pisanie setnego pliku migracyjnego V101__Add_user_preference_column.sql, a potem debugowanie, dlaczego na produkcji poszło coś nie tak. Flyway i Liquibase zaprowadziły w tym porządek, ale nie zdjęły z nas najgorszej harówki: ręcznego pisania każdego ALTER TABLE.
Obietnica końca tej udręki jest kusząca. I tu na scenę wchodzi pgschema, który przenosi do PostgreSQL deklaratywny workflow w stylu Terraforma: zamiast pisać kolejne skrypty, utrzymujesz jeden plik schema.sql jako jedyne źródło prawdy, a narzędzie porównuje go z bazą i generuje potrzebne ALTERy.
Liczby pokazują, że ludzie zwracają na to uwagę. W chwili pisania projekt ma 948 gwiazdek na GitHubie, wydanie 1.11.0 (z 9 czerwca 2026) i wsparcie dla PostgreSQL 14-18. Jest w pełni darmowy na licencji Apache-2.0, bez płatnych haczyków ani modelu open-core, a rachunki płaci komercyjna platforma Bytebase jako sponsor.
Zainstalowałem i sprawdziłem ten workflow. Pętla dump, edycja, plan, apply jest faktycznie prosta. Aż za prosta. Zamiast żonglować plikami, edytujesz jeden plik definiujący cały schemat, a przy dodawaniu tabel czy kolumn wszystko działa bezbłędnie.
Autorzy odrobili pracę domową, jeśli chodzi o specyfikę Postgresa. Policzyłem typy obiektów wprost z tabeli wsparcia w README: 16 kategorii, od polityk RLS, przez tabele partycjonowane, aż po częściowe indeksy i funkcje SECURITY DEFINER. To rzeczy, o które potykają się generyczne narzędzia próbujące obsłużyć wszystko od MySQL po Oracle.
Comparison data
| pgschema | Flyway/Liquibase | Atlas | |
|---|---|---|---|
| Workflow | Oparty na stanie | Oparty na plikach migracji | Oparty na stanie |
| Wsparcie dla baz danych | Tylko PostgreSQL | Wiele baz danych | Wiele baz danych |
| Shadow Database | Niewymagana | Niewymagana | Wymagana domyślnie |
| Tabela historii migracji | No | Yes | No |
| Obiekty specyficzne dla PG | Wykrywane automatycznie | Ręczne pisanie SQL | Wykrywane automatycznie |
Jeden z użytkowników na GitHubie, który oceniał pgschema jako zamiennik dla Atlasa, chwalił to lekkie podejście. Zauważył, że brak konieczności używania "shadow database" usuwa poważny problem w jego złożonym środowisku.
Gdzie jest haczyk? Jak to często bywa w naszym fachu, w eleganckiej filozofii, która w zderzeniu z rzeczywistością okazuje się pułapką. pgschema szczyci się "brakiem stanu zewnętrznego": nie ma tabeli historii migracji, nie ma śledzenia operacji. Narzędzie nie wie, co chciałeś zrobić. Wie tylko, jak wygląda stan A i stan B.
I tu zaczyna się dramat. Załóżmy, że w ramach refaktoryzacji zmieniasz w pliku schema.sql nazwę kolumny username na email. Dla Ciebie to kosmetyka, dla pgschema to sygnał do egzekucji. Plan, który wygeneruje, będzie prosty: DROP COLUMN username; ADD COLUMN email;. Wszystkie loginy Twoich użytkowników właśnie wyparowały.
Bezstanowy projekt generuje taki plan z założenia, a autor otwarcie się do tego przyznaje.
However, one of the design goal of pgschema is not leveraging external state such as refactor_log table mentioned here
Inny użytkownik podzielił to zdanie, argumentując przeciwko dodawaniu pliku YAML do obsługi zmian nazw, ponieważ zniweczyłoby to sens używania pgschema zamiast innych narzędzi.
+1 really do not want to introduce (more) yaml to our workflows, if we started doing something with a log file + table there isn't a reason to use something like pgschema over other declarative (but non sql!) db management systems.
To nie jest też zapomniany kąt backlogu. W maju 2026 jeden z kontrybutorów otworzył pull request #435, dodający automatyczne wykrywanie zmiany nazwy kolumny, czyli dokładnie tę siatkę bezpieczeństwa, której byś oczekiwał. Autor projektu zamknął go bez scalenia 30 maja, uznając tę funkcję za zbyt ciężką w utrzymaniu. Wątek #49 wciąż jest otwarty i nierozwiązany. Prześledziłem całą dyskusję: w wersji 1.11.0 zmiana nazwy to nadal DROP i ADD.
Myślisz, że to koniec problemów? Ależ skąd. Narzędzie obsługuje tylko DDL, czyli zmiany schematu, i nie ma żadnego pojęcia o DML, czyli o migracjach danych. Autor potwierdził w wątku z opiniami, że zarządzanie danymi jest poza zakresem projektu.
Potrzebujesz dodać kolumnę NOT NULL i wypełnić ją danymi? Przygotuj się na kruchą, ręcznie koordynowaną akrobatykę:
- Dodajesz kolumnę bez ograniczenia
NOT NULLwschema.sqli robiszapply. - Ręcznie, poza
pgschema, odpalasz własny skrypt wypełniający dane. - Zmieniasz kolumnę na
NOT NULLwschema.sqli robisz drugieapply.
Obietnica "edytuj tylko jeden plik" legła w gruzach.
A co z rollbackiem? Zapomnij. Nie ma czegoś takiego jak rollback w stylu Flyway, a bez tabeli historii migracji nie ma też ścieżki audytu. "Deklaratywnym" sposobem naprawy złej migracji jest przywrócenie starej wersji schema.sql i ponowne apply. To jednak tylko "roll-forward", który nie przywróci danych usuniętych przed chwilą przez pomyłkę. Dla każdego, kto potrzebuje historii zmian, to absolutny bloker.
Więc komu można polecić pgschema? Projektom greenfield i prostym aplikacjom wewnętrznym, gdzie schemat głównie rośnie, a refaktoring to odległa przyszłość. Dla każdej dojrzałej aplikacji, która wymaga refaktoryzacji, transformacji danych albo ścieżki audytu, elegancki projekt pgschema staje się obciążeniem. To bardzo ostry nóż, który nie odróżnia schematu od danych.