ORM w Pythonie bez pułapek - CRUD, relacje i transakcje

Gdy aplikacja ma zapisywać użytkowników, zamówienia albo produkty, szybko pojawia się pytanie, jak wykonywać operacje na bazie bez ręcznego składania każdego zapytania SQL. ORM pozwala pracować na modelach i obiektach Pythona, ale jego wygoda nie zwalnia z myślenia o transakcjach, relacjach i wydajności. Poniżej pokazuję najważniejsze operacje ORM na przykładach SQLAlchemy i Django oraz wyjaśniam, gdzie początkujący programiści najczęściej wpadają w pułapki.

Co naprawdę robi ORM w aplikacji

ORM, czyli Object-Relational Mapping, tłumaczy dane między dwoma światami. Z jednej strony mamy klasy i obiekty Pythona, z drugiej tabele, kolumny i klucze obce w relacyjnej bazie danych. Model User może odpowiadać tabeli users, a jego atrybut email konkretnej kolumnie.

Największa korzyść polega na tym, że programista opisuje operację na obiekcie, a biblioteka generuje odpowiednie zapytanie SQL. Nie oznacza to jednak, że SQL przestaje mieć znaczenie. ORM ukrywa składnię zapytania, ale nie ukrywa jego kosztu, liczby odczytanych rekordów ani blokad zakładanych w bazie.

Typowy zestaw operacji obejmuje cztery elementy CRUD:

• Create - dodawanie nowych rekordów,
• Read - pobieranie i filtrowanie danych,
• Update - zmiana istniejących wartości,
• Delete - usuwanie rekordów.

W Pythonie często spotkasz przede wszystkim SQLAlchemy, używane między innymi z Flaskiem i FastAPI, oraz ORM wbudowany w Django. Oba narzędzia rozwiązują podobne problemy, ale mają inną składnię i filozofię pracy.

CRUD w praktyce na przykładzie SQLAlchemy

Załóżmy, że aplikacja przechowuje produkty. W SQLAlchemy obiekt dodajemy do sesji, a zapis potwierdzamy przez commit(). Samo utworzenie obiektu w pamięci nie zapisuje jeszcze danych w bazie.

from sqlalchemy import String, Numeric
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, Session

class Base(DeclarativeBase):
    pass

class Product(Base):
    __tablename__ = "products"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(120))
    price: Mapped[float] = mapped_column(Numeric(10, 2))

with Session(engine) as session:
    product = Product(name="Klawiatura", price=199.99)
    session.add(product)
    session.commit()

Po zatwierdzeniu transakcji obiekt zwykle otrzymuje identyfikator nadany przez bazę. W praktyce często dodaję kilka obiektów naraz przez add_all(), ale przy bardzo dużych zbiorach lepsze są operacje wsadowe. Tworzenie 100 tysięcy obiektów ORM jeden po drugim może zużywać znacznie więcej pamięci niż bezpośredni insert zbiorczy.

Odczyt w stylu SQLAlchemy 2.x może wyglądać tak:

from sqlalchemy import select

with Session(engine) as session:
    statement = (
        select(Product)
        .where(Product.price >= 100)
        .order_by(Product.name)
    )

    products = session.scalars(statement).all()

Aktualizacja pojedynczego obiektu jest czytelna, bo przypomina zwykłą pracę z klasą:

with Session(engine) as session:
    product = session.get(Product, 1)

    if product is not None:
        product.price = 179.99
        session.commit()

Usuwanie wymaga podobnej ostrożności. Najpierw pobieram rekord, upewniam się, że jest właściwy, a dopiero potem wywołuję delete(). Przy usuwaniu masowym filtr powinien być możliwie precyzyjny, bo pomyłka w warunku może objąć tysiące wierszy.

with Session(engine) as session:
    product = session.get(Product, 1)

    if product is not None:
        session.delete(product)
        session.commit()

Filtrowanie, sortowanie i pobieranie tylko potrzebnych danych

Najczęstsza operacja odczytu nie polega na pobraniu całej tabeli, lecz na znalezieniu niewielkiego zestawu rekordów. Do tego służą warunki WHERE, sortowanie oraz paginacja. W SQLAlchemy odpowiadają im między innymi where(), order_by(), limit() i offset().

statement = (
    select(Product)
    .where(Product.name.ilike("%mysz%"))
    .order_by(Product.price.desc())
    .limit(20)
    .offset(40)
)

products = session.scalars(statement).all()

W Django podobną operację zapisuje się krócej:

products = (
    Product.objects
    .filter(name__icontains="mysz")
    .order_by("-price")[40:60]
)

Do pobrania dokładnie jednego rekordu można użyć get(), ale trzeba obsłużyć sytuację, w której rekord nie istnieje. Metody typu first() są łagodniejsze, ponieważ zwracają None, lecz nie zawsze sygnalizują błąd biznesowy. Dobór metody powinien wynikać z logiki aplikacji, a nie tylko z wygody składni.

Nie pobieraj pełnych obiektów, gdy potrzebujesz dwóch kolumn do raportu. Projekcja ogranicza ilość danych przesyłanych z bazy:

statement = select(Product.name, Product.price).where(Product.price > 500)
rows = session.execute(statement).all()

Przy większych tabelach paginacja oparta wyłącznie na offset może z czasem zwalniać, ponieważ baza musi pominąć wcześniejsze wiersze. Dla list sortowanych po stabilnym, indeksowanym kluczu lepiej sprawdza się paginacja kursorowa, na przykład pobieranie rekordów z identyfikatorem większym od ostatniego widocznego.

Relacje między modelami i problem N+1

Relacja jeden do wielu, na przykład użytkownik i jego zamówienia, wygląda naturalnie w kodzie, ale może generować zaskakująco dużo zapytań. Jeśli pobierzesz 100 użytkowników, a potem osobno odczytasz zamówienia każdego z nich, powstanie 101 zapytań zamiast kilku. To klasyczny problem N+1.

W SQLAlchemy można jawnie określić sposób ładowania relacji. selectinload() pobiera dane powiązane w dodatkowym zapytaniu z klauzulą IN, a joinedload() wykorzystuje połączenie tabel. Wybór zależy od rozmiaru danych i rodzaju relacji.

from sqlalchemy.orm import selectinload

statement = (
    select(User)
    .options(selectinload(User.orders))
)

users = session.scalars(statement).all()

W Django podobną rolę pełnią select_related() dla relacji opartych na kluczu obcym oraz prefetch_related() dla bardziej złożonych lub wielowartościowych relacji.

orders = Order.objects.select_related("customer").all()
customers = Customer.objects.prefetch_related("orders").all()

Nie ma jednej strategii dobrej dla każdego przypadku. Join może zwielokrotnić liczbę wierszy przy relacji jeden do wielu, a osobne pobranie może być czytelniejsze i tańsze pamięciowo. Ja zaczynam od danych, które rzeczywiście są potrzebne na danym ekranie, a potem sprawdzam log zapytań. Testowanie liczby zapytań jest ważniejsze niż zgadywanie, który loader będzie najlepszy.

Transakcje, flush i bezpieczne usuwanie danych

Transakcja grupuje kilka zmian w jedną logiczną całość. Przykładowo utworzenie zamówienia i pomniejszenie stanu magazynowego powinno zakończyć się albo pełnym sukcesem, albo wycofaniem obu zmian. Inaczej aplikacja może zapisać zamówienie bez rezerwacji produktu.

W SQLAlchemy flush() wysyła oczekujące zmiany do bazy, ale nie zatwierdza jeszcze transakcji. commit() zatwierdza całość, a rollback() cofa niezapisane zmiany po błędzie.

try:
    with Session(engine) as session:
        order = Order(customer_id=7)
        session.add(order)
        session.flush()

        stock_item = session.get(Product, 3)
        stock_item.quantity -= 1

        session.commit()
except Exception:
    # Transakcja zostanie wycofana lub obsłużona przez warstwę aplikacji
    raise

W Django podobny blok można objąć dekoratorem lub kontekstem transaction.atomic(). To dobry wybór, gdy jedna akcja biznesowa zmienia kilka tabel.

Usuwanie rekordów wymaga dodatkowego namysłu nad kluczami obcymi i kaskadami. Usunięcie użytkownika może usunąć jego adresy, zamówienia albo komentarze, ale nie zawsze jest to właściwe. Czasem lepszy będzie soft delete, czyli oznaczenie rekordu jako nieaktywnego bez fizycznego kasowania danych.

Nie warto też zakładać, że każda operacja masowa zachowa się tak samo jak usuwanie pojedynczych obiektów. Metody wsadowe mogą ominąć część logiki modelu, sygnały lub własne metody zapisu. To świetne narzędzie do prostych zmian, lecz ryzykowne, gdy model ma dodatkowe reguły biznesowe.

Wydajność i błędy, które kosztują najwięcej

Najczęstszy błąd polega na utożsamianiu wygodnego kodu z szybkim kodem. ORM może wygenerować poprawne SQL, które będzie jednak nieefektywne. Dlatego przy wolnym endpointcie sprawdzam przede wszystkim liczbę zapytań, czas ich wykonania i użycie indeksów.

• Dodaj indeksy dla kolumn często używanych w filtrach, sortowaniu i kluczach obcych.
• Nie pobieraj całej tabeli, jeśli potrzebujesz jednej strony wyników.
• W relacjach wybieraj jawne ładowanie danych zamiast liczyć na przypadek.
• Do masowych zmian rozważ update() lub insert zbiorczy.
• Włącz logowanie SQL w środowisku testowym i analizuj plan wykonania.

W Django metoda update() wykonuje zmianę bez pobierania każdego obiektu do pamięci. W SQLAlchemy można użyć konstrukcji update() wykonywanej przez sesję. Zyskujemy szybkość, ale tracimy część zachowania związanego z pojedynczymi instancjami, dlatego przed użyciem trzeba sprawdzić, czy zmiana nie omija walidacji lub zdarzeń modelu.

Ważne są również ograniczenia po stronie bazy. Walidacja w aplikacji nie zastępuje constraintów, takich jak UNIQUE, NOT NULL czy klucze obce. Dwie równoległe żądania mogą przejść przez walidację w tym samym momencie, ale tylko baza zagwarantuje, że unikalność zostanie faktycznie zachowana.

W projektach produkcyjnych schemat bazy powinien być zmieniany przez migracje, a nie przez przypadkowe ręczne modyfikacje. Migracja opisuje zmianę struktury, ułatwia wdrożenie i pozwala odtworzyć środowisko testowe. ORM upraszcza pracę z danymi, lecz nie zastępuje projektowania bazy danych.

Jak ułożyć bezpieczny schemat pracy

Przy nowej operacji zaczynam od odpowiedzi na trzy pytania. Jakie dane naprawdę muszę odczytać lub zmienić? Czy działanie obejmuje jedną tabelę, czy kilka zależnych rekordów? Co ma się stać, gdy zapis nie powiedzie się w połowie?

1. Zdefiniuj model, relacje i ograniczenia w bazie.
2. Zbuduj zapytanie ograniczające wynik do potrzebnego zakresu.
3. Umieść powiązane zmiany w jednej transakcji.
4. Dodaj test dla przypadku poprawnego i błędnego.
5. Sprawdź wygenerowany SQL oraz liczbę zapytań.

Na początku nie komplikowałbym projektu własną warstwą abstrakcji nad ORM. Najpierw trzeba dobrze poznać sesje, QuerySety, relacje i transakcje. Dopiero gdy powtarzalny kod faktycznie utrudnia rozwój, sens ma wydzielenie repozytoriów albo serwisów aplikacyjnych.

Najpraktyczniejsze podejście jest proste. ORM wykorzystuj do codziennej pracy z modelami, ale zachowaj świadomość tego, jaki SQL powstaje pod spodem. Gdy operacja jest masowa, krytyczna dla spójności albo nietypowa dla modelu, jawnie sprawdź jej plan, transakcję i wpływ na relacje. Dzięki temu wygoda Pythona pracuje na rzecz aplikacji, zamiast ukrywać problemy, które ujawnią się dopiero na produkcji.