Jak zaprojektować bazę danych pod aplikację webową przykłady wzorców i antywzorców

Gdy aplikacja zaczyna „mielić”: typowe objawy, które zdradzają problem w bazie

Objawy po stronie UI/API, które najłatwiej przeoczyć

Najczęstszy scenariusz wygląda niewinnie: aplikacja webowa działa dobrze w MVP, a potem przybywa danych, filtrów i ról. Nagle te same endpointy, które „zawsze były szybkie”, zaczynają się dławić. Użytkownik widzi to jako długie ładowanie list, backend jako rosnące czasy odpowiedzi, a baza jako rosnące koszty I/O i blokady. To zwykle nie jest „wina serwera” ani „pecha”, tylko sygnał, że schemat i indeksy nie wspierają realnych zapytań.

Klasyka problemu: wolne listy z filtrami i sortowaniem. Endpoint typu GET /orders?status=paid&sort=-created_at jest logicznie prosty, ale jeśli tabela jest szeroka, brakuje indeksu złożonego, a dodatkowo dołączasz klienta, płatność i ostatni status, robi się ciężko. W UI dochodzi paginacja, w API dochodzi autoryzacja (np. tenant_id), a w bazie powstaje zapytanie, które bez dobrego indeksu kończy się skanem dużej części tabeli.

Drugi objaw: nagle wydłużające się wdrożenia przez migracje. Dodanie kolumny, zmiana typu, uzupełnienie nulli albo dołożenie constraintu zaczyna trwać tak długo, że blokuje aplikację (albo wymaga okna serwisowego). To wskazuje, że schemat nie był projektowany pod ewolucję: brakuje kompatybilności wstecznej, a zmiany robią „wszystko naraz” na tabelach, które są w ciągłym użyciu.

Trzeci objaw: zaskakujące błędy danych. Duplikaty, „niemożliwe” stany, rekordy osierocone, ujemne wartości, statusy, których nikt nie przewidział. Jeżeli spójność opiera się wyłącznie na kodzie aplikacji, prędzej czy później jakaś ścieżka (import, admin panel, skrypt, bug) wprowadzi dane, które rozbiją logikę. Baza danych ma potrafić powiedzieć „nie”.

Czwarty objaw: raporty i eksporty, które wymagają obejść. Kiedy biznes prosi o „zwykły raport”, a Ty kończysz z ręcznym ETL, skryptem nocnym i wstydliwym CSV, to często oznacza, że model danych miesza odpowiedzialności: operacyjne tabele są jednocześnie magazynem historii, agregacji i słowników, a do tego brakuje jasnych relacji i indeksów pod analitykę.

Jeśli rozpoznajesz te symptomy, zacznij od spisania 5–10 najważniejszych endpointów i tego, jakich zapytań wymagają — to najszybszy krok, który od razu ukierunkowuje projekt bazy.

Szybka mapa: problem w aplikacji → podejrzana przyczyna w schemacie

Poniższa mapa działa jak diagnostyka: nie daje jednej odpowiedzi, ale zawęża obszar poszukiwań. W projektowaniu bazy pod aplikację webową wygrywa podejście „objaw → przyczyna → poprawka”, bo pozwala podejmować decyzje szybko, bez akademickiego modelowania wszystkiego.

W praktyce webowej dominują: listy, filtrowanie, paginacja, autoryzacja (tenant/user) oraz „zmiana statusu” (workflow). Jeżeli schemat nie wspiera tych czterech rzeczy, reszta będzie gaszeniem pożarów. Zamiast zgadywać, wybierz 3 kluczowe listy w aplikacji i potraktuj je jako test dla modelu danych.

Mini-check: czy projekt już na starcie idzie w złą stronę?

Wiele problemów da się przewidzieć po samym schemacie, zanim napiszesz linijkę kodu. Oto szybkie sygnały ostrzegawcze:

• Większość tabel nie ma FK, bo „aplikacja pilnuje”.
• Występuje tabela typu users_data, app_data, dashboard z dziesiątkami kolumn.
• Statusy są stringami bez kontroli, np. „paid”, „PAID”, „Paid”.
• Wiele kolumn to JSON, bo „tak szybciej”, a potem filtrujesz po ich polach.
• Relacje many-to-many są upychane jako lista ID w jednej kolumnie.

Jeżeli widzisz u siebie 2–3 z tych punktów, decyzje projektowe warto skorygować natychmiast — później koszt rośnie wykładniczo.

Skąd to się bierze: najczęstsze przyczyny „długu schematu” w projektach webowych

Model danych tworzony „pod ekran”, a nie pod domenę i zapytania

Jedna z najdroższych pomyłek to modelowanie bazy jako odbicia UI: „mam ekran profilu, to zrobię tabelę profile_view”, „mam dashboard, to zrobię dashboard_data”. Problem polega na tym, że UI zmienia się często, a domena (np. zamówienia, płatności, członkostwa) zmienia się wolniej. Jeśli baza jest „pod ekran”, to każda zmiana w produkcie ciągnie migracje, a dane zaczynają się dublować.

Druga wersja tego błędu to brak jasnych granic odpowiedzialności tabel. Tabela ma być źródłem prawdy dla konkretnego bytu: orders przechowuje zamówienia, order_items pozycje, payments płatności. Jeżeli zamówienie ma „trochę płatności” jako pola w orders, a jednocześnie jest tabela payments, to szybko trafiasz na niespójność: co jest prawdą, co jest kopią, co aktualizuje co?

Trzecia rzecz: relacje ukryte w kodzie. Kolumna user_id bez FK wygląda jak relacja, ale nią nie jest — baza nie potrafi wymusić spójności, a Ty nie dostaniesz natychmiastowej informacji, że właśnie zapisałeś odwołanie do nieistniejącego użytkownika. Przy rosnącym systemie to kończy się „sprzątaniem danych” zamiast rozwoju.

Jeśli chcesz szybko poprawić kierunek, wybierz 3 kluczowe encje domenowe i dla każdej odpowiedz: gdzie jest źródło prawdy, a gdzie tylko projekcja pod odczyt.

ORM prowadzi za rękę… aż do pierwszych trudniejszych filtrów

ORM potrafi przyspieszyć development, ale łatwo też zamaskować problemy. Najbardziej znany symptom to N+1, jednak przyczyna często nie jest tylko „nieoptymalny eager loading”. To bywa sygnał, że granice agregatów są źle ustawione: pobierasz „za dużo naraz”, bo relacje są narysowane bez refleksji, a model obiektowy próbuje na siłę skleić świat, który w bazie powinien być bardziej rozdzielony.

Drugi kłopot: „naprawianie” N+1 przez agresywne eager loading kończy się zapytaniami z wieloma JOIN-ami, które dublują wiersze i pompą pamięć. Potem ktoś dodaje filtr, potem sortowanie, potem paginację i nagle query planner robi rzeczy, których nie przewidziałeś. Schema, który jest przyjazny ORM-owi, nie zawsze jest przyjazny realnym zapytaniom listującym.

Trzeci kłopot: brak kontroli nad selektywnością filtrów. Jeśli UI pozwala filtrować po 6 polach, a w bazie masz indeks tylko po jednym, ORM może wygenerować zapytanie, które „działa”, ale robi skan. W webówkach to zabija szczególnie listy administracyjne i panele operatorskie, bo one rosną w wymaganiach szybciej niż część użytkownika końcowego.

Dobry ruch: zanim „zaufasz ORM”, ustal, jakie zapytania muszą być szybkie, i sprawdź ich plan wykonania (np. EXPLAIN). To urealnia projekt od razu.

Strach przed migracjami = strach przed decyzją

Odkładanie decyzji „na później” to typowy generator długu schematu. Najpierw rezygnujesz z constraints, bo „niech API to waliduje”, potem rezygnujesz z indeksów, bo „jeszcze nie ma danych”, potem upychasz wszystko w JSON, bo „zmienia się specyfikacja”. Po kilku sprintach okazuje się, że masz już dane i klientów, więc każda poprawka boli bardziej.

Najbardziej zdradliwe są zmiany niekompatybilne wstecz: zmieniasz nazwę kolumny, usuwasz starą, aplikacja w jednej wersji oczekuje nowej, w drugiej starej, a wdrożenie przestaje być płynne. W mikroserwisach i w systemach z workerami (kolejki, cron, integracje) to wręcz gwarantowany downtime, jeśli nie projektujesz migracji w krokach.

Jeżeli boisz się migracji, to paradoksalnie potrzebujesz więcej dyscypliny schematu, nie mniej. Nawet prosta zasada „najpierw dodaj, potem przenieś, na końcu usuń” potrafi uratować wdrożenia. Zacznij od ustalenia, że schemat też ma wersje i review jak kod.

Rozwiązanie krok po kroku: od wymagań produktu do stabilnego modelu danych

Start od przypadków użycia i zapytań, nie od diagramu ERD

Najkrótsza droga do sensownego projektu bazy danych pod aplikację webową to spisanie operacji, które muszą działać szybko i poprawnie. Nie abstrakcyjnych „encja ma atrybuty”, tylko konkretów: logowanie, lista zasobów, szczegóły, tworzenie, zmiana statusu, eksport. Każda z tych operacji generuje zapytania — a zapytania narzucają indeksy, typy relacji i czasem nawet wybór bazy.

Weź 5–10 operacji i dla każdej dopisz:

• jakie są filtry (np. status, data, owner, tenant),
• jakie sortowanie (np. created_at desc, price asc),
• jak wygląda paginacja (offset/limit czy cursor),
• jakie są ograniczenia uprawnień (np. user widzi swoje, admin widzi wszystko, tenant izoluje dane),
• czy potrzebujesz licznika/aggregacji (np. liczba komentarzy, suma pozycji).

Jeśli w tym momencie czujesz, że „to dużo roboty”, potraktuj to jako test: projektowanie bazy bez tej listy to proszenie się o późniejsze przebudowy. Zrób to raz, a oszczędzisz dziesiątki godzin na tuningowaniu po omacku.

Jak odróżnić encję, atrybut, relację i zdarzenie (praktyczne kryteria)

Encja ma własną tożsamość i cykl życia. „Zamówienie” istnieje niezależnie od UI. „Użytkownik” też. Z kolei „kolor w UI” albo „czy tooltip był pokazany” to zwykle nie encja domenowa, tylko detal aplikacyjny (często lepiej jako konfiguracja, cache albo event telemetry).

Atrybut nie żyje samodzielnie: imię, email, kwota, waluta. Jeśli atrybut zaczyna mieć własne reguły, historię i relacje, to znak, że może być encją (np. adres: jeśli masz wiele adresów, walidacje, kraj/region, wybór domyślnego, historię zmian — osobna tabela ma sens).

Relacja jest wtedy, gdy ma znaczenie biznesowe i ograniczenia. „Użytkownik ma wiele zamówień” to relacja one-to-many. „Użytkownik należy do wielu projektów, a projekt ma wielu użytkowników” to many-to-many. Jeśli relacja ma atrybuty (rola, data dołączenia, status zaproszenia), to join table przestaje być „łącznikiem” i staje się pełnoprawną encją (membership).

Zdarzenie jest wtedy, gdy liczy się historia: „zmiana statusu zamówienia”, „wysłano email”, „pobrano płatność”. Jeśli próbujesz upchnąć historię do jednej tabeli przez nadpisywanie kolumn, tracisz audyt i możliwość debugowania. Lepiej rozdzielić bieżący stan od historii.

Szybki ruch decyzyjny: dla każdego „bytu” zapytaj, czy musi mieć swoją historię i czy istnieje bez kontekstu jednego ekranu. To wystarcza, by nie pomylić encji z widokiem.

Kardynalności bez zgadywania: one-to-many i many-to-many w webówkach

Relacje to miejsce, gdzie najłatwiej wpaść w antywzorce. Jeżeli „wiele do wielu” próbujesz załatwić polem typu role_ids: [1,2,3] w jednej tabeli, tracisz indeksowanie, spójność i możliwość dołożenia atrybutów relacji. Poprawny model w SQL to zwykle join table.

Przykład: użytkownicy i role w systemie z projektami.

• Jeśli role są globalne (admin, user): users + roles + user_roles.

Różnica jest praktyczna, nie akademicka. Globalne role to prostsze uprawnienia, ale gdy tylko pojawia się „ten sam użytkownik ma inne prawa w innym projekcie”, model z memberships wygrywa: filtrowanie po projekcie jest banalne, a audyt (kto kiedy dostał dostęp) przestaje być łamigłówką. Dorzuć unikalność UNIQUE(user_id, project_id) i od ręki utniesz duplikaty, które później robią „duchy” w UI.

W relacjach one-to-many najczęstsza pułapka to „to się kiedyś zmieni na many-to-many”. Jeśli podejrzewasz taki zwrot (np. produkt może należeć do wielu kategorii, a dziś jest jedna), lepiej zaprojektować join table od początku, ale bez przesady: nie każda relacja wymaga zapasu na przyszłość. Dobre kryterium: czy w wymaganiach już pojawiają się wyjątki typu „czasem”, „w specjalnych przypadkach”, „dla partnerów” — to zwykle zwiastun, że prosty FK szybko pęknie.

Praktyczny test jakości relacji: czy potrafisz napisać jedno krótkie zapytanie, które odpowiada na najczęstsze pytanie biznesowe. Jeśli musisz parsować listy ID, robić LIKE po CSV albo dopinać warunki z kodu aplikacji, schema prosi się o poprawkę. Zrób małą próbkę: „lista projektów użytkownika z rolą” albo „lista zamówień z ostatnią płatnością” — i zobacz, czy SQL wygląda jak normalna praca, czy jak sztuczki.

Ustal kardynalności na papierze, a potem sprawdź je w bazie constraintami. To jedna z tych decyzji, które naprawdę zdejmują ciężar z głowy.

Jeśli musisz wybrać tylko jedną rzecz na start: pilnuj źródeł prawdy, ustaw relacje tak, żeby baza wymuszała spójność, i projektuj pod zapytania, które będą klepane codziennie — to daje stabilny fundament, nawet gdy produkt zmienia kierunek.

Normalizacja, która pomaga, i denormalizacja, która nie robi bałaganu

Problem, który wraca jak bumerang: projekt startuje „ładnie znormalizowany”, a potem pojawiają się listy i filtry. I nagle każda lista to 6 JOIN-ów, a każde sortowanie robi się podejrzanie wolne. Druga skrajność jest równie bolesna: ktoś denormalizuje wszystko „dla szybkości” i po miesiącu nie wiesz, która kolumna jest źródłem prawdy.

Przyczyna jest prosta: normalizacja rozwiązuje spójność i redukcję duplikacji, ale nie gwarantuje dobrego UX dla zapytań listujących. Denormalizacja przyspiesza odczyt, ale bez reguł zamienia się w rozjechane dane i „ktoś zapomniał zaktualizować pole”.

Rozwiązanie decyzyjne: ustal źródła prawdy i trzymaj je w jednym miejscu, a denormalizuj tylko pola pochodne (łatwe do odtworzenia) albo snapshoty potrzebne do audytu.

• Normalizuj, gdy: dane mają wiele punktów zapisu, muszą być spójne, mają ograniczenia (FK/UNIQUE) i będą używane w wielu kontekstach.
• Denormalizuj kontrolowanie, gdy: masz ciężkie listy/raporty, które czytają dużo częściej niż zapisują, a pola są stabilne (np. order_total, last_status_at, customer_display_name jako snapshot).
• Nie denormalizuj przez kopiowanie „żywych” danych między tabelami bez mechanizmu aktualizacji. To jest proszenie się o rozjazd.

Jeśli musisz zrobić denormalizację, dopisz do niej regułę utrzymania: trigger, logika w transakcji, job rekoncyliacyjny albo materialized view. Najgorsza wersja to „będziemy pamiętać w kodzie” — nikt nie będzie.

Mały test: czy potrafisz wytłumaczyć nowej osobie w zespole, która kolumna jest prawdziwa, a która jest cache’em? Jeśli nie, schema jest zbyt sprytne. Zrób jeden ruch: nazwij pola pochodne tak, by to było czytelne (np. *_snapshot, *_cached) i trzymaj je w jednym miejscu.

Weź jedną kluczową listę w aplikacji i sprawdź, co naprawdę musi być szybkie: to najlepszy moment, żeby zdecydować, czy potrzebujesz odrobiny denormalizacji.

Klucze główne bez niespodzianek: INT, UUID i naturalne identyfikatory

W pewnym momencie przychodzi ból: integracja z zewnętrznym systemem, import danych, shardowanie, replikacja albo po prostu potrzeba „nie ujawniaj kolejnych ID w URL”. I wtedy wybór kluczy przestaje być detalem.

Najczęstsza przyczyna kłopotów to mieszanie dwóch światów: naturalne identyfikatory (email, NIP, numer zamówienia) próbują być jednocześnie kluczem technicznym, a UUID-y są wrzucane wszędzie bez zrozumienia kosztu na indeksach.

Rozwiązanie, które rzadko zawodzi:

• Użyj sztucznego PK jako stabilnego identyfikatora w relacjach (INT/BIGINT albo UUID — zależnie od potrzeb).
• Naturalne identyfikatory trzymaj jako kolumny z UNIQUE (i często z CHECK), bo one się zmieniają i mają reguły.
• Jeśli chcesz nieprzewidywalnych ID w URL, rozważ UUID/ULID jako public_id i osobny techniczny PK pod spodem. To daje bezpieczeństwo linków bez spowalniania wszystkich FK.

INT/BIGINT zwykle wygrywa wydajnością i prostotą indeksów. UUID daje wygodę generowania po stronie aplikacji i łatwiejsze merge danych z wielu źródeł, ale rośnie koszt indeksów i locality (szczególnie dla losowych UUID). Jeśli wybierasz UUID w Postgresie, rozważ warianty lepiej zachowujące porządek w czasie (ULID/UUIDv7), bo to realnie pomaga w B-tree.

Dwa szybkie antysygnały:

• PK = email, bo „przecież jest unikalny” — a potem dochodzi zmiana emaila, aliasy, logowanie SSO i migracja robi się trudniejsza niż cały feature.
• UUID wszędzie, bo „tak się teraz robi”, bez sprawdzenia wpływu na indeksy, FK i rozmiar tabel — zapis zaczyna siadać, a nikt nie wie dlaczego.

Ustal jedną konwencję kluczy na starcie projektu i trzymaj ją żelaznie. To daje spokój w migracjach i integracjach.

Constraints jako pas bezpieczeństwa: kiedy baza ma mówić „nie”

Problem: dane zaczynają „dziwnie wyglądać”. Duplikaty, rekordy osierocone, statusy spoza listy, daty w przyszłości, płatność przypięta do nieistniejącego zamówienia. UI niby waliduje, ale integracje, joby i edge case’y robią swoje.

Przyczyna jest prawie zawsze ta sama: brak constraints albo zbyt luźne typy. Walidacja w aplikacji jest potrzebna, ale to nie jest zabezpieczenie spójności — aplikacja ma wiele ścieżek zapisu (API, worker, import, admin panel), a baza jest jedna.

Rozwiązanie: podstawowy pakiet constraints dla każdej ważnej tabeli:

• PK (oczywiste, ale bez kombinacji typu „czasem NULL”).
• FK z sensowną polityką kasowania (RESTRICT, CASCADE, czasem SET NULL), zamiast „zrobimy ręcznie”.
• UNIQUE tam, gdzie biznes mówi „nie może być dwóch” (np. UNIQUE(tenant_id, slug), UNIQUE(user_id, project_id)).
• CHECK na proste reguły: zakresy, statusy, zależności (np. paid_at IS NULL OR status = 'paid').
• NOT NULL dla pól, bez których rekord nie ma sensu.

Jeśli boisz się, że constraints „utrudnią rozwój”, to zwykle znak, że model jest nieostry. Constraints nie spowalniają pracy — one wyłapują błędy wtedy, gdy naprawa jest najtańsza, czyli przy zapisie.

Jeden praktyczny trik: dla statusów zamiast „magicznych stringów” rozważ enum (tam, gdzie pasuje) albo tabelę słownikową + FK. To wymusza porządek i upraszcza raporty. Zrób to szczególnie tam, gdzie statusy sterują logiką biznesową.

Wybierz jedną tabelę, w której dziś brakuje FK/UNIQUE, i dodaj constraint z migracją naprawiającą dane. Taki ruch szybko podnosi jakość całego systemu.

Indeksy projektowane pod UI: filtry, sortowanie i paginacja

Problem z webówkami jest przewidywalny: najpierw działa „lista X”, potem dochodzi filtr po statusie, potem po ownerze, potem zakres dat, potem sortowanie po created_at, a na końcu paginacja. Bez indeksów dobranych pod realne zapytania dostajesz skany i losowe spadki czasu odpowiedzi.

Przyczyna: indeksy są dodawane „po kolumnach”, a nie pod konkretne WHERE + ORDER BY. Dodatkowo ORM-y potrafią generować zapytania, które wyglądają niewinnie, ale zabijają selektywność (np. funkcje na kolumnach, nieprzemyślane ILIKE, warunki opcjonalne sklejane w runtime).

Rozwiązanie: zrób indeksy tak, jak użytkownik klika w UI. Kilka praktycznych reguł, które robią różnicę:

• Indeks złożony układaj pod najczęstszy wzorzec: najpierw kolumny filtrowania, potem kolumna sortowania. Przykład: lista „moje zgłoszenia” filtrowana po tenant_id, assignee_id, status i sortowana po created_at DESC często potrzebuje indeksu w tym kierunku.
• Jeśli zawsze filtrujesz po tenant_id, to prawie zawsze powinien on być pierwszym składnikiem indeksów. Multi-tenant bez tego szybko boli.
• Unikaj OFFSET na dużych tabelach w krytycznych listach; cursor-based pagination (np. po (created_at, id)) stabilizuje czas odpowiedzi.
• Nie przesadzaj z liczbą indeksów: każdy indeks to koszt zapisu. Jeśli masz endpoint, który intensywnie zapisuje, indeksy trzeba dobierać ostrożniej niż w panelu raportowym.

Dobry rytuał: dla 3 najważniejszych list spisz docelowe zapytania (nawet w pseudo-SQL), odpal EXPLAIN i dopiero wtedy zdecyduj o indeksie. Wtedy indeks jest odpowiedzią na realny problem, a nie „bo tak”.

Weź jeden endpoint listujący, który jest ważny biznesowo, i dobierz do niego jeden indeks złożony. Jeden, ale trafiony — efekt czuć od razu.

Wzorce, które ratują projekt: konkretne rozwiązania z kryteriami „kiedy stosować”

Join table jako pełnoprawna encja: relacje z atrybutami i audytem

Problem: relacja many-to-many rośnie w wymaganiach. Najpierw „user jest w projekcie”, potem dochodzi rola, potem data dołączenia, potem status zaproszenia, a na końcu: „kto go dodał”. Jeśli join table jest traktowana jak techniczny łącznik, zaczynają się kombinacje w kodzie i kolumny upychane w złych miejscach.

Przyczyna: relacja ma własny cykl życia, ale schema udaje, że go nie ma.

Rozwiązanie: potraktuj tabelę relacyjną jak encję domenową. Przykład w praktyce to memberships:

• id jako PK (łatwiej referencjonować w logach, auditach i eventach),
• user_id, project_id jako FK,
• role / role_id, status, joined_at, invited_by,
• UNIQUE(user_id, project_id) jako twarda reguła.

Kiedy to ma sens? Gdy relacja ma atrybuty albo gdy chcesz audytować zmiany dostępu. Kiedy nie? Gdy to naprawdę czysty łącznik i nie przewidujesz rozbudowy (rzadziej niż się wydaje, ale czasem tak jest).

Jeżeli masz dziś prostą tabelę user_project bez kolumn dodatkowych, sprawdź backlog: jeśli widzisz „zaproszenia”, „role per projekt”, „historia dostępu” — zrób z niej encję, zanim zrobi to za Ciebie chaos.

Soft delete bez pułapek: jak nie zepsuć unikalności i zapytań

Problem: produkt chce „kosz” albo „odtwórz usunięte”. Naturalny odruch: dodajesz deleted_at. Po chwili okazuje się, że unikalne wartości nie mogą zostać ponownie użyte (bo rekord dalej istnieje), a zapytania raz filtrują usunięte, raz nie. I masz pół aplikacji z bugami typu „gdzie zniknęło?”

Przyczyna: soft delete to nie tylko kolumna. To zmiana semantyki całej tabeli i wszystkich indeksów/unikalności.

Rozwiązanie:

• Ustal zasadę: domyślnie w aplikacji nie pokazujesz usuniętych. W SQL oznacza to konsekwentny warunek deleted_at IS NULL (widoki lub scope w ORM pomagają, ale nie mogą być „opcjonalne”).
• Rozwiąż unikalność: często potrzebujesz unikalności warunkowej (np. unikalny email tylko dla aktywnych). W Postgresie robi się to partial indexem: UNIQUE (...) WHERE deleted_at IS NULL.
• Dodaj indeks wspierający typowe listy: jeśli filtrujesz po tenant_id i deleted_at, indeks powinien to odzwierciedlać.
• Określ politykę retencji: soft delete bez planu archiwizacji to rosnący koszt.

Kiedy soft delete jest dobry? Gdy musisz odzyskać dane, masz wymagania audytowe albo usunięcie ma konsekwencje prawne/biznesowe. Kiedy lepiej hard delete? Gdy to dane pomocnicze, bez wartości historycznej, a duży wolumen będzie Cię kosztował w indeksach i backupach.

Jeśli wprowadzisz soft delete, od razu dodaj do schematu partial UNIQUE (o ile dotyczy) i jeden widok/konwencję zapytań. To zamyka 80% typowych bugów.

Audit log i historia zmian: debugowanie, które przestaje być wróżeniem

Problem: „kto zmienił status?”, „czemu kwota jest inna?”, „dlaczego klient widzi coś innego niż wczoraj?”. Bez historii zmian zostaje Ci odtwarzanie zdarzeń z logów aplikacji, a te bywają niepełne, rotowane albo niezsynchronizowane.

Przyczyna: trzymasz tylko bieżący stan w tabeli głównej, a zmiany nadpisują się bez śladu.

Rozwiązanie zależy od wagi domeny:

• Prosty audit log: osobna tabela audit_log z entity_type, entity_id, action, actor_id, created_at, opcjonalnie diff (JSON). Dobre dla paneli admin i debugowania.
• History table: osobna tabela wersji (np. order_versions) z pełnym snapshotem rekordu i numerem wersji. Dobre, gdy musisz mieć pełną rekonstrukcję stanu.
• Event sourcing: rzadziej potrzebne na start; ma sens, gdy domena jest zdarzeniowa i chcesz budować projekcje. Jeśli nie masz jasnego powodu, to nie jest „domyślny wybór”.

Mini-kryterium: jeśli pytania „kto i kiedy” pojawiają się regularnie w utrzymaniu lub supportcie, audit przestaje być luksusem. Zaczynasz odzyskiwać czas już po pierwszych incydentach.

Żeby audit nie zamienił się w nowy problem, ustal od razu granice: co logujesz zawsze (np. zmiany statusów, kwoty, uprawnień), a co tylko w wybranych modułach. Jeśli zapisujesz diff jako JSON, trzymaj się jednej konwencji (np. {"field":"status","from":"open","to":"closed"}) — dzięki temu da się to później filtrować i pokazać w UI bez ręcznego parsowania dziesiątek formatów.

W praktyce najwięcej daje logowanie zdarzeń „biznesowo ciężkich”, a nie wszystkiego jak leci. Statusy, przejścia workflow, zmiany przypisania, edycja danych rozliczeniowych. To są rzeczy, które generują tickety i spory. Z kolei pełny snapshot co zapis bywa kuszący, ale szybko robi się kosztowny w storage i w backupach; częściej wygrywa kompromis: snapshot przy kluczowych zmianach + diff dla reszty.

Nie spychaj audytu wyłącznie do aplikacji, jeśli zależy Ci na spójności. Tam gdzie ma to znaczenie, trigger w bazie potrafi uratować skórę (np. admin zmienił coś „bokiem” albo wykonano poprawkę SQL na produkcji). A jeśli to trigger, to koniecznie z testem migracji i jasnym planem retencji: audit log też rośnie i też trzeba go archiwizować, inaczej za rok zacznie wpływać na wydajność.

Prosty test, czy idziesz w dobrą stronę: wybierz jeden problem z supportu typu „kto zmienił X?” i zrób tak, żeby odpowiedź była w bazie w 30 sekund. Zrób to raz, a potem dokładaj kolejne zdarzenia już bez bólu.

Jeśli masz wybrać tylko jedną rzecz do poprawy po przeczytaniu: dołóż jedną twardą regułę w schemacie (FK/UNIQUE lub partial UNIQUE przy soft delete) i dopasuj jeden indeks pod najważniejszą listę w UI. Ten duet najszybciej zamienia „działa jakoś” w system, który da się rozwijać bez nerwów.

Outbox pattern: gdy integracje zaczynają „gubić” zdarzenia

Problem: zapisujesz coś w bazie i „w tym samym czasie” wysyłasz event na kolejkę albo webhook do zewnętrznego systemu. W teorii proste. W praktyce: transakcja w DB się commituje, a publish do brokera się nie udaje (albo odwrotnie). Efekt: brak maila, brak faktury, brak synchronizacji — a Ty nie masz pewności, czy to „przepadło”, czy „dojdzie później”.

Przyczyna: dwa światy (DB i broker) nie są w jednej transakcji, więc przy awarii dostajesz klasyczne „half success”. Retries w aplikacji pomagają tylko częściowo, bo nie rozwiązują spójności.

Rozwiązanie: outbox, czyli tabelka w tej samej bazie, do której zapisujesz zdarzenie w tej samej transakcji co zmianę domeny. Potem osobny worker (lub job) publikuje zdarzenia z outboxa do brokera i oznacza je jako wysłane.

• Tabela outbox: id, event_type, aggregate_type, aggregate_id, payload (JSON), created_at, published_at, attempts, opcjonalnie error.
• Indeks pod pobieranie: (published_at, created_at) lub po prostu published_at IS NULL + created_at.
• Idempotencja po stronie konsumenta: eventy mogą zostać opublikowane ponownie; to cecha, nie wada.

Kiedy to ma sens? Gdy masz integracje, które muszą „nie gubić” zdarzeń (płatności, faktury, provisioning, powiadomienia, synchronizacja z CRM). Kiedy nie? Gdy wysyłasz „miękkie” notyfikacje i ewentualne braki nie są krytyczne — wtedy prostsza kolejka z retry w aplikacji może wystarczyć.

Jeśli masz dziś choć jeden incydent typu „rekord jest w DB, ale nie poszło dalej”, outbox to jeden z najszybszych sposobów, żeby odzyskać kontrolę. Zrób pierwszy event, uruchom worker i zobacz, jak spada liczba „dziwnych” ticketów.

Status jako model, nie jako magiczny string: spójny workflow bez ifologii

Problem: w tabelach lądują statusy typu "new", "in_progress", "done", a po pół roku dochodzi "done_with_notes", "archived", "blocked", "returned"… Każdy moduł interpretuje to trochę inaczej. Raporty przestają się zgadzać, a logika przejść robi się nie do ogarnięcia.

Przyczyna: status jest traktowany jako luźna etykieta, bez reguł przejść i bez ochrony w schemacie. Do tego dochodzi pokusa: „wrzućmy jeszcze jeden status, będzie szybciej”.

Rozwiązanie: wybierz jeden z dwóch kierunków (i bądź konsekwentny):

• Mały, stabilny enum + twarde reguły: kilka statusów, CHECK constraint albo enum w DB (tam, gdzie ma to sens), do tego walidacja przejść w kodzie. Dobre dla prostych workflow.
• Model workflow jako dane: tabela statuses + tabela status_transitions (co z czego może przejść dokąd), opcjonalnie role/uprawnienia do przejść. Dobre, gdy workflow rośnie i chcesz nim zarządzać bez deploya.

Jeżeli status wpływa na rozliczenia, dostęp lub integracje, nie zostawiaj go jako „dowolny string”. Dodaj przynajmniej CHECK albo słownik i prostą tablicę dozwolonych przejść. Zyskasz mniej błędów i mniej sporów „kto zmienił co i dlaczego”.

Mały ruch na start: spisz dozwolone przejścia dla jednej kluczowej encji (np. zamówienia) i wprowadź je jako regułę w kodzie + constraint w DB tam, gdzie się da.

Antywzorce, które cicho niszczą projekt: objawy, przyczyny i poprawki

EAV (Entity-Attribute-Value): elastyczność, która kończy się kosztem wszystkiego

Problem: produkt chce „dynamiczne pola”, więc powstaje model w stylu: entity_id, attr_name, attr_value. Początkowo wygląda to na sprytne. Potem pojawiają się raporty, walidacja typów, indeksy, sortowanie, filtry, a nawet proste „pokaż rekordy, gdzie X > Y” zaczyna boleć.

Przyczyna: EAV przenosi schemat do danych. Baza traci możliwość pilnowania typów, constraints, unikalności, a zapytania robią się ciężkie i kruche (joiny do tej samej tabeli wiele razy lub kosztowne pivoty).

Rozwiązania, które działają lepiej w webówkach:

• Normalne kolumny dla pól, które są core i często filtrowane/sortowane.
• JSONB jako dodatek na rzadkie, „miękkie” atrybuty — ale z ograniczeniem: nie buduj na tym krytycznych filtrów bez indeksów i jasnych kontraktów.
• Osobne tabele dla typów: jeśli masz kilka klas atrybutów, rozbij je na sensowne podmodele zamiast jednego worka.

Jeśli już masz EAV i cierpisz: zidentyfikuj 3–5 najczęściej używanych atrybutów i „wyciągnij” je do kolumn. Efekt bywa natychmiastowy: prostsze zapytania, lepsze indeksy, mniej błędów w typach.

„JSON jako wszystko”: gdy schemat przestaje istnieć

Problem: jedna tabela, a w niej data jako JSON i do tego może 2–3 pola techniczne. Szybkie MVP przechodzi. Potem dochodzą filtry, walidacja, migracje struktury JSON, spójność między rekordami i nagle każda zmiana wymaga grzebania w kodzie i backfilli bez gwarancji poprawności.

Przyczyna: zyskujesz elastyczność kosztem tego, co w SQL daje największą wartość: constraints, indeksów, czytelnego modelu. JSON w relacyjnej bazie jest świetny jako dodatek, ale jako fundament — często robi z systemu „schemaless w przebraniu”, bez zalet prawdziwego dokumentowego storage.

Rozwiązanie: trzymaj JSON tam, gdzie to ma sens biznesowy:

• payload zewnętrznej integracji, który chcesz przechować „jak przyszedł”,
• rzadkie pola rozszerzeń, które nie biorą udziału w kluczowych listach i raportach,
• audit diff (z jasną konwencją).

Jeśli jakikolwiek klucz z JSON trafia do WHERE i staje się częścią krytycznego endpointu — rozważ przeniesienie go do kolumny (albo przynajmniej daj indeks funkcyjny/GIN i ustandaryzuj typy). Jedna decyzja tu potrafi oszczędzić tygodnie dłubania w wydajności.

Brak FK i CHECK: „aplikacja pilnuje” aż przestaje

Problem: dane zaczynają się rozjeżdżać: osierocone rekordy, duplikaty „niemożliwe w teorii”, wartości spoza zakresu. Raporty nie zgadzają się z UI, a debug zamienia się w polowanie.

Przyczyna: zbyt duża wiara w to, że aplikacja zawsze zapisze poprawnie. Wystarczy jeden bug, jeden skrypt, jedna poprawka na produkcji, jeden import danych i masz śmieci. Constraints są jak pasy bezpieczeństwa: nie zastępują kierowcy, ale ratują projekt, gdy wydarzy się coś nieprzewidzianego.

Rozwiązanie: dokładaj constraints wprost pod problemy:

• FK na relacjach, które muszą istnieć (zwłaszcza w modułach uprawnień, płatności, faktur, członkostw).
• UNIQUE na naturalnych regułach (np. jeden aktywny membership per (user_id, project_id)).
• CHECK na zakresach i stanach (np. kwota >= 0, status w zbiorze, starts_at < ends_at).

Jeśli boisz się „zablokowania deploya” constraintami, zacznij od nowych tabel albo od miejsc, gdzie ból jest największy. Jedno UNIQUE dodane we właściwym miejscu potrafi wyciąć całą klasę bugów.

Migracje bez dramatu: jak zmieniać schemat, gdy system już działa

Zmiana schematu w dwóch krokach: kompatybilność wsteczna jako standard

Problem: dodajesz kolumnę, usuwasz starą, zmieniasz typ — i nagle część instancji aplikacji działa na nowym kodzie, część na starym. W środku deploya pojawiają się błędy, bo kod i baza na chwilę przestają do siebie pasować.

Przyczyna: migracje traktowane jak „jedno kliknięcie”, bez uwzględnienia, że rollout bywa stopniowy. Nawet jeśli masz jeden serwer, to nadal masz okno czasowe, w którym baza jest „pomiędzy”.

Rozwiązanie: standardem jest podejście expand → migrate → contract:

• Expand: dodaj nowe kolumny/tabele/indeksy tak, aby stary kod dalej działał (np. nowa kolumna nullable, nowa tabela obok).
• Migrate: uzupełnij dane (backfill), przełącz zapis/odczyt w aplikacji (feature flag pomaga), obserwuj.
• Contract: dopiero wtedy usuwasz stare pola, zaostrzasz NOT NULL, dokładasz docelowe constraints.

To wygląda na wolniejsze, ale w praktyce jest szybsze niż gaszenie pożarów po deployu. Weź jedną planowaną zmianę i rozbij ją na te trzy fazy — od razu poczujesz różnicę w stabilności.

„Ciężkie” operacje: indeksy, backfille i locki, które potrafią zatrzymać produkcję

Problem: migracja wchodzi na produkcję i nagle API zwalnia albo staje. Najczęściej winne są: tworzenie indeksu w trybie blokującym, masowy update bez batchowania, zmiana typu kolumny wymagająca przepisu całej tabeli.

Przyczyna: baza musi wykonać dużą pracę, a część operacji trzyma locki, przez co zapisy/odczyty zaczynają czekać. To nie jest „pech”, tylko przewidywalna konsekwencja.

Rozwiązanie (praktyczne, webowe):

• W Postgresie rozważ CREATE INDEX CONCURRENTLY dla dużych tabel (kosztuje dłużej, ale nie blokuje tak jak klasyczny indeks).
• Backfill rób partiami (batch) i z kontrolą tempa, zamiast jednego gigantycznego UPDATE.
• Zmiany typu/NOT NULL planuj jako proces: najpierw nowa kolumna, backfill, przełączenie kodu, dopiero potem constraint.
• Miej prosty „plan odwrotu”: jeśli migracja idzie za długo, chcesz umieć ją przerwać bez pół-bazy w stanie pośrednim.

Jeśli czujesz, że migracja „może być ciężka”, odpal ją na kopii produkcyjnej (nawet lokalnie na snapshotcie) i zmierz czas + zobacz locki. Taka próba zwykle ujawnia problemy, zanim zrobi to użytkownik.

Decyzje o kluczach i identyfikatorach: mały wybór, duże konsekwencje

INT czy UUID: wydajność, integracje i ergonomia

Problem: na starcie wybór klucza głównego wydaje się kosmetyczny. Po czasie okazuje się, że wpływa na indeksy, rozmiar danych, debugging, bezpieczeństwo linków, replikację i integracje.

Przyczyna: ID to nie tylko identyfikator. To też format, który „przecieka” do logów, URL-i, eventów, foreign key i czasem do klientów zewnętrznych.

Rozwiązanie: kieruj się scenariuszem, a nie modą:

• INT/BIGINT jest świetny, gdy liczysz na prostotę, mniejsze indeksy i topową wydajność joinów. Dobre domyślnie w monolicie lub w systemach bez potrzeby generowania ID poza DB.
• UUID ma sens, gdy generujesz ID po stronie aplikacji, łączysz dane z wielu źródeł, masz offline/edge, albo chcesz trudniej zgadywalne identyfikatory w URL. Kosztem są większe indeksy i czasem gorsza lokalność zapisu (da się to łagodzić, np. UUID v7).

Jeśli masz „klucz publiczny” (widoczny w URL), a jednocześnie chcesz zachować szybkie joiny: rozważ dwa identyfikatory — wewnętrzny bigint jako PK i osobny public_id (UUID/slug) z UNIQUE. To często najlepszy kompromis.

Wybierz jeden standard w projekcie i trzymaj się go konsekwentnie. Mieszanie „bo tu UUID, a tu jednak INT” bez powodu szybko robi bałagan w integracjach i migracjach.

Najczęściej zadawane pytania (FAQ)

Dlaczego endpointy z listami i filtrami nagle robią się wolne?

Najczęściej problem nie leży w „słabym serwerze”, tylko w tym, że schemat i indeksy nie wspierają realnych zapytań z UI: WHERE (filtry), ORDER BY (sortowanie), paginacja oraz warunek autoryzacji (np. tenant_id). Gdy danych przybywa, brak odpowiednich indeksów kończy się skanem dużej części tabeli.

Typowy przykład to lista zamówień z filtrem po statusie i sortowaniem po dacie. Jeśli masz szeroką tabelę, dociągasz kilka JOIN-ów i nie masz indeksu złożonego pod te warunki, baza zaczyna „mielić”. Weź 3 najważniejsze listy w aplikacji i sprawdź ich zapytania oraz plan wykonania.

Jakie indeksy dodać pod filtrowanie i sortowanie w aplikacji webowej?

Celuj w indeksy, które odpowiadają na najczęstsze kombinacje WHERE + ORDER BY, a nie w „indeks na każdą kolumnę”. W webówkach często wygrywają indeksy złożone, np. (tenant_id, status, created_at) dla listy typu: status=paid i sort=-created_at.

Praktyczny trik: spisz 5–10 kluczowych endpointów (z parametrami) i do każdego dopasuj indeks pod najczęstszy wariant filtra. Potem potwierdź decyzję w EXPLAIN, zanim indeksów zrobi się kilkadziesiąt.

Czy warto polegać na ORM, czy lepiej pisać SQL ręcznie?

ORM jest świetny do szybkiego developmentu, ale potrafi zamaskować problemy, dopóki nie wejdziesz w trudniejsze filtry, sortowanie i paginację. Klasyczny sygnał to N+1 albo próby „ratowania” sytuacji agresywnym eager loading, które kończą się ciężkimi JOIN-ami i duplikowaniem wierszy.

Dobra praktyka to ustalenie, które zapytania muszą być szybkie (zwykle listy administracyjne i operatorskie), a potem weryfikacja ich planu wykonania. Zyskujesz kontrolę: ORM zostaje narzędziem, a nie kierownikiem projektu.

Dlaczego migracje bazy blokują wdrożenia i jak to naprawić?

Migracje zaczynają boleć, gdy robisz niekompatybilne zmiany „na raz” na gorących tabelach: ALTER na dużej tabeli, uzupełnianie NULL-i, dokładanie constraintów bez planu, zmiany typów kolumn. Efekt to długie locki, okna serwisowe i napięcie w zespole.

Najczęściej pomaga podejście etapowe: najpierw dodaj nową kolumnę, potem zrób backfill asynchronicznie, dopiero na końcu ustaw NOT NULL/constraint i przełącz aplikację. Zacznij od rozpisania zmian w 2–3 krokach zamiast jednego „wielkiego” deploya.

Jak zabezpieczyć się przed duplikatami i „niemożliwymi” stanami w danych?

Jeśli spójność trzymasz tylko w kodzie aplikacji, prędzej czy później coś ją ominie: import, panel admina, skrypt, błąd w jednej ścieżce zapisu. Baza danych powinna umieć powiedzieć „nie” i zatrzymać zły zapis na wejściu.

Najczęściej wystarcza zestaw podstaw: klucze obce (FK), UNIQUE na identyfikatorach biznesowych, CHECK na zakresach i sensowny model statusów (zamiast luźnych stringów typu „Paid/PAID/paid”). Dorzuć transakcje tam, gdzie zmieniasz kilka tabel naraz (np. zmiana statusu + zapis płatności).

Kiedy JSON w kolumnach to antywzorzec w bazie pod webówkę?

JSON jest OK jako „dodatkowe atrybuty”, dopóki nie zaczynasz regularnie filtrować i sortować po polach w środku. Wtedy kończy się to słabą selektywnością, trudniejszym indeksowaniem i zapytaniami, które działają, ale nie skalują się z danymi.

Jeśli jakieś pole z JSON-a trafia do UI jako filtr (np. „typ klienta”, „kraj”, „metoda dostawy”), rozważ normalną kolumnę albo osobną tabelę. Zrób szybki przegląd: które filtry są „na stałe” w produkcie i wyciągnij je z JSON-a.

Jak rozpoznać, że schemat bazy jest projektowany „pod ekran”, a nie pod domenę?

Najczęściej widać to po tabelach typu users_data/app_data/dashboard z dziesiątkami kolumn oraz po mieszaniu odpowiedzialności: trochę płatności w orders i jednocześnie tabela payments, statusy jako luźny tekst, relacje trzymane „w kodzie” bez FK. UI zmienia się szybko, więc taki schemat wymusza częste migracje i dublowanie danych.

Prosty test: wybierz 3 kluczowe encje domenowe (np. orders, payments, users) i wskaż dla każdej jedno źródło prawdy. Potem dopasuj pod to relacje i constraints — zrobisz porządek, zanim problemy zaczną kosztować czas i nerwy.

Opracowano na podstawie

• Designing Data-Intensive Applications. O’Reilly Media (2017) – Wzorce projektowania danych, transakcje, spójność, skalowanie i modele odczytu/zapisu.
• SQL Antipatterns: Avoiding the Pitfalls of Database Programming. Pragmatic Bookshelf (2010) – Antywzorce SQL: EAV, przechowywanie list ID, nadużycia NULL, brak constraints.
• Database System Concepts. McGraw-Hill Education (2019) – Podstawy modelowania relacyjnego, normalizacja, indeksy, transakcje i blokady.
• PostgreSQL Documentation. PostgreSQL Global Development Group – Indeksy złożone, EXPLAIN, blokady, migracje/ALTER, constraints i typy danych.
• MySQL 8.0 Reference Manual. Oracle – Indeksy, optymalizator, transakcje InnoDB, blokady, klucze obce i ograniczenia.
• SQL Server Documentation. Microsoft – Indeksy, query plans, blokady, transakcje, zmiany schematu i dobre praktyki.
• Database Design for Mere Mortals. Addison-Wesley Professional (2013) – Projektowanie schematu, relacje, klucze, normalizacja i unikanie tabel „wszystko w jednym”.