pgvector czy PostGIS: pierwsza decyzja architektoniczna której nie ma w ADR

To był piątek. Rano postawiłem cały fundament stacku — 8915 linii konfiguracji, stack gotowy. Ucieszyłem się, zamknąłem laptop. Wieczorem wróciłem, rzuciłem okiem na konfigurację bazy danych i zadałem sobie pytanie, które powinienem zadać od razu:

Właściwie dlaczego tu jest pgvector?

Domyślny wybór

pgvector trafiło tu instynktownie. Rok 2025, AI wszędzie, wektory to sposób na przechowywanie „znaczenia” tekstu — żeby potem szukać podobnych treści, robić rekomendacje, zasilać asystenta. Brzmi jak coś, czego każda nowoczesna aplikacja powinna chcieć.

Ale chwilę. Co naprawdę robi juz-ide?

Platforma sąsiedzka dla małego polskiego miasta. Ktoś w Starachowicach szuka hydraulika w promieniu 2 km. Ktoś inny wystawia rower do wymiany — ważne, że na tym samym osiedlu. Główny problem to nie semantyczne podobieństwo ofert. Główny problem to gdzie.

pgvector świetnie odpowiada na pytanie „co jest podobne?”. PostGISPostGISRozszerzenie PostgreSQL o dane geograficzne — odległości, obszary, „kto jest w pobliżu”. czytaj więcej → odpowiada na pytanie „co jest blisko?” — i rozumie przy tym polskie podziały administracyjne, granice dzielnic, punkty na mapie.

Jedna linia, jedna decyzja

Kilka godzin po postawieniu fundamentu zmieniłem jeden wiersz w konfiguracji bazy: pgvector zastąpił PostGISPostGISRozszerzenie PostgreSQL o dane geograficzne — odległości, obszary, „kto jest w pobliżu”. czytaj więcej → . To wszystko. Żaden ADR, żaden dokument decyzji. Czemu?

Bo w tamtym momencie nie było czego dokumentować. Nie było alternatyw do porównania, nie było ryzyk do opisania. Był jeden zły domyślny wybór i jeden oczywisty właściwy — oczywisty jak tylko zadałem właściwe pytanie.

Czego ta zmiana nie widać w commicie

PostGIS to nie tylko inny obraz Dockera. To inne myślenie o danych.

pgvector przechowuje wektory — tablice liczb zmiennoprzecinkowych reprezentujące „znaczenie” zdania w przestrzeni wielowymiarowej. PostGIS przechowuje geometrię — punkty, linie, wielokąty, i umie liczyć odległości między nimi, sprawdzać czy punkt leży wewnątrz obszaru, znajdować wszystko w zadanym promieniu.

Dla juz-ide to oznacza: każda oferta, każdy użytkownik, każdy punkt usługowy ma współrzędne. Zapytanie „pokaż hydraulików w odległości 2 km od centrum Starachowic” to jedno zapytanie SQL. Bez PostGIS to seria pętli i przybliżeń.

Pgvector nie zniknął z projektu na zawsze. Wrócił — dziś baza ma oba rozszerzenia naraz, bo geografia i wyszukiwanie semantyczne nie wykluczają się nawzajem. Po prostu w maju 2025 to geografia była fundamentem, a wektory dodatkiem na kiedyś. Kolejność miała znaczenie.

Lekcja o dokumentowaniu decyzji

Dziś wiem, że warto było zrobić ADR nawet dla tak prostej zmiany. Nie dlatego, że decyzja była skomplikowana — właśnie dlatego, że nie była. Ja wiem, że wybór PostGIS był świadomy. Ale ktoś nowy w projekcie — albo ja za dwa lata — zobaczy tylko lakoniczny commit message. Kontekst zniknie.

Nie każda decyzja potrzebuje dokumentu. Ale każda decyzja, która zmienia kierunek — nawet ta, która zajęła godzinę — powinna zostawić po sobie ślad z „dlaczego”, nie tylko z „co”.

I jest w tym ironia. Trzy miesiące później, gdy porządkowałem decyzje architektoniczne, w końcu napisałem ADR o wyborze PostGIS. Brzmi w nim, jakbym to wszystko przemyślał z góry — chłodna analiza, wektory kontra geometria. Prawda jest taka, że była to godzina w piątkowy wieczór i jedno dobre pytanie. ADR pisany po fakcie zawsze wygląda mądrzej, niż było naprawdę.