Kurs Python · Moduł 4: Dane, API i bazy danych

SQLAlchemy - ORM dla Python

10 min czytania ·
W tej lekcji9

Witaj! Ostatnio pisałeś/aś surowe SQL - cursor.execute("SELECT * FROM species"). Działa, ale każde zapytanie to napis, a literówka w nazwie kolumny wychodzi dopiero przy uruchomieniu. Poznaj ORM (Object-Relational Mapping) - pracę z bazą przez pythonowe klasy zamiast SQL!

Analogia Safari: Surowe SQL to jak wypełnianie formularzy papierowych ręcznie. SQLAlchemy ORM to cyfrowy system - obiekty Python automatycznie mapowane na tabele bazy danych!

Czym jest ORM?

ORM mapuje obiekty na tabele bazy: klasa to tabela, obiekt to wiersz, atrybut to kolumna. W surowym SQL zapis lwa to napis ze znakami zapytania zamiast wartości:

cursor.execute("INSERT INTO species (name, population) VALUES (?, ?)", ("Lew", 120))

W ORM tworzysz zwykły obiekt Pythona, a gotowe polecenie INSERT przygotuje za Ciebie sesja:

lion = Species(name="Lew", population=120)
session.add(lion)
session.commit()

Oba dodają ten sam wiersz, ale w drugim SQL pisze SQLAlchemy.

Zalety ORM:

  • Pythonowe klasy zamiast SQL stringów
  • Type hints i autocomplete
  • Mniej podatne na SQL injection
  • Łatwiejsze relacje między tabelami
  • Migracje i ewolucja schematu
  • Niezależność od bazy (PostgreSQL, MySQL, SQLite...)

SQLAlchemy - najpopularniejszy ORM w Pythonie

SQLAlchemy to potężny ORM + narzędzie do pracy z bazami SQL. Używamy aktualnej serii 2.0.

Instalacja

Nie ma jej w standardowym Pythonie, więc instalujemy ją raz z terminala:

pip install sqlalchemy

Dla SQLite to wszystko - sterownik sqlite3 jest wbudowany w Pythona.

Podstawy SQLAlchemy - Modele

Model to klasa opisująca tabelę: nazwa trafia do __tablename__, a kolumny to atrybuty Column z typami i ograniczeniami. Pięć kroków prowadzi do gotowej sesji:

from sqlalchemy import create_engine, Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base, sessionmaker

# 1. Utwórz Base - klasa bazowa dla modeli
Base = declarative_base()

# 2. Zdefiniuj model - klasa Python = tabela SQL
class Species(Base):
    __tablename__ = 'species'  # Nazwa tabeli

    # Kolumny
    id = Column(Integer, primary_key=True, autoincrement=True)
    scientific_name = Column(String, nullable=False, unique=True)
    common_name = Column(String, nullable=False)
    population = Column(Integer, default=0)
    habitat = Column(String)
    endangered = Column(Boolean, default=False)

    def __repr__(self):
        return f"<Species('{self.common_name}', pop={self.population})>"


# 3. Połącz się z bazą danych
engine = create_engine('sqlite:///safari_orm.db', echo=True)  # echo=True wyświetla SQL

# 4. Utwórz tabele
Base.metadata.create_all(engine)

# 5. Utwórz sesję (zarządza operacjami na bazie)
Session = sessionmaker(bind=engine)
session = Session()

primary_key=True to unikalny numer wiersza, nullable=False zakazuje pustych wartości, unique=True duplikatów. Podczas nauki włącz echo=True, by widzieć generowany SQL. Uwaga: Base.metadata.create_all() tworzy tabele tylko jeśli nie istnieją (jak IF NOT EXISTS).

Typy kolumn

SQLAlchemySQLPython
IntegerINTEGERint
StringVARCHARstr
TextTEXTstr (dłuższy)
FloatFLOATfloat
BooleanBOOLEANbool
DateTimeDATETIME / TIMESTAMPdatetime
DateDATEdate
JSONJSONdict/list (SQLite 3.9+)

MySQL wymaga długości tekstu, np. String(100).

CRUD z SQLAlchemy

CREATE - dodawanie rekordów

Nowy rekord to nowy obiekt modelu. Trafia do sesji, a do bazy dopiero przy zatwierdzeniu:

# Utwórz obiekt
lion = Species(
    scientific_name="Panthera leo",
    common_name="Lew",
    population=120,
    habitat="sawanna",
    endangered=True
)

# Dodaj do sesji
session.add(lion)

# Zatwierdź
session.commit()

print(f"Dodano lwa ID: {lion.id}")  # ID automatycznie przypisane!

# Dodaj wiele naraz
species_list = [
    Species(scientific_name="Loxodonta africana", common_name="Słoń", population=450, endangered=True),
    Species(scientific_name="Gorilla gorilla", common_name="Goryl", population=230, endangered=True),
]

session.add_all(species_list)
session.commit()

Przed commit() lew żyje tylko w sesji, a jego id to None.

READ - pobieranie danych

Zapytanie zaczyna się od session.query(Species), a metody doklejasz jak ogniwa łańcucha, kończąc tą, która pobiera wyniki:

# Wszystkie gatunki
all_species = session.query(Species).all()
for species in all_species:
    print(species.common_name, species.population)

# Pierwszy wynik
first = session.query(Species).first()

# Pobierz po ID
lion = session.query(Species).get(1)  # ID = 1 (styl legacy - ostrzeżenie w 2.0)
# lub (SQLAlchemy 1.4+, zalecane)
lion = session.get(Species, 1)

# Filtrowanie - WHERE
endangered = session.query(Species).filter(Species.endangered == True).all()
savanna = session.query(Species).filter(Species.habitat == "sawanna").all()

# Wiele warunków (AND)
results = session.query(Species).filter(
    Species.endangered == True,
    Species.population > 100
).all()

# OR
from sqlalchemy import or_
results = session.query(Species).filter(
    or_(Species.habitat == "sawanna", Species.habitat == "las")
).all()

# LIKE
results = session.query(Species).filter(Species.scientific_name.like("Panthera%")).all()

# ORDER BY
sorted_species = session.query(Species).order_by(Species.population.desc()).all()

# LIMIT i OFFSET
top_5 = session.query(Species).limit(5).all()
page_2 = session.query(Species).limit(10).offset(10).all()

# COUNT
count = session.query(Species).count()
endangered_count = session.query(Species).filter(Species.endangered == True).count()

filter() przyjmuje operatory Pythona, a SQLAlchemy zamienia je na WHERE. Styl session.query() ma w 2.0 etykietę "legacy" - nowszy select() poznasz w module o FastAPI.

UPDATE - aktualizacja

Aktualizacja w ORM to po prostu zmiana atrybutu. Sesja ją zauważa i przy commit() wysyła polecenie UPDATE:

# Metoda 1: Pobierz obiekt, zmień, commit
lion = session.query(Species).filter(Species.common_name == "Lew").first()
lion.population = 125
session.commit()

# Metoda 2: Bulk update
session.query(Species).filter(Species.habitat == "sawanna").update({
    "endangered": True
})
session.commit()

Metoda 1 wczytuje obiekt, metoda 2 zmienia wiele wierszy jednym poleceniem bez ich ładowania.

DELETE - usuwanie

Pojedynczy obiekt przekazujesz do session.delete(), a wiele wierszy usuwa filtr zakończony metodą delete():

# Metoda 1: Pobierz obiekt, usuń
species_to_delete = session.get(Species, 10)
if species_to_delete:
    session.delete(species_to_delete)
    session.commit()

# Metoda 2: Bulk delete
session.query(Species).filter(Species.population == 0).delete()
session.commit()

session.get() zwraca None, gdy rekordu nie ma, stąd if. Bez commit() zmiana przepadnie.

Relacje - One-to-Many

Jeden gatunek ma wiele obserwacji z terenu: w bazie łączy je klucz obcy, a w Pythonie relationship() (osobny, uproszczony przykład):

from sqlalchemy import ForeignKey
from sqlalchemy.orm import relationship

class Species(Base):
    __tablename__ = 'species'

    id = Column(Integer, primary_key=True)
    common_name = Column(String, nullable=False)
    population = Column(Integer, default=0)

    # Relacja: jeden gatunek -> wiele obserwacji
    observations = relationship("Observation", back_populates="species", cascade="all, delete-orphan")


class Observation(Base):
    __tablename__ = 'observations'

    id = Column(Integer, primary_key=True)
    species_id = Column(Integer, ForeignKey('species.id'), nullable=False)
    observation_date = Column(String, nullable=False)
    location = Column(String, nullable=False)
    count = Column(Integer, default=0)

    # Relacja: wiele obserwacji -> jeden gatunek
    species = relationship("Species", back_populates="observations")

ForeignKey('species.id') wskazuje kolumnę gatunków, back_populates spina oba końce, a ustawienie cascade usuwa obserwacje razem z gatunkiem.

Teraz dopisujemy obserwacje lwa do jego listy i zapisujemy wszystko w bazie jednym commit():

# Użycie
lion = Species(common_name="Lew", population=120)

# Dodaj obserwacje do lwa
lion.observations.append(Observation(observation_date="2024-01-15", location="Serengeti", count=12))
lion.observations.append(Observation(observation_date="2024-01-20", location="Masai Mara", count=8))

session.add(lion)
session.commit()

# Pobierz obserwacje
lion = session.query(Species).filter(Species.common_name == "Lew").first()
for obs in lion.observations:
    print(f"{obs.observation_date}: {obs.count}x w {obs.location}")

Pola species_id nie ustawialiśmy - SQLAlchemy uzupełnił je sam dzięki relacji.

Safari przykład - kompletny system ORM

Zbierzmy wszystko w klasę-usługę, która ukrywa sesję. Najpierw modele ze znacznikami czasu:

from sqlalchemy import create_engine, Column, Integer, String, Boolean, ForeignKey, DateTime
from sqlalchemy.orm import declarative_base, sessionmaker, relationship
from datetime import datetime, timezone
from typing import List, Optional

Base = declarative_base()


def utc_now() -> datetime:
    return datetime.now(timezone.utc)


class Species(Base):
    """Model gatunku"""
    __tablename__ = 'species'

    id = Column(Integer, primary_key=True, autoincrement=True)
    scientific_name = Column(String, nullable=False, unique=True)
    common_name = Column(String, nullable=False)
    population = Column(Integer, default=0)
    habitat = Column(String)
    endangered = Column(Boolean, default=False)
    created_at = Column(DateTime, default=utc_now)
    updated_at = Column(DateTime, default=utc_now, onupdate=utc_now)

    # Relacje
    observations = relationship("Observation", back_populates="species", cascade="all, delete-orphan")

    def __repr__(self):
        return f"<Species('{self.common_name}', pop={self.population})>"


class Observation(Base):
    """Model obserwacji"""
    __tablename__ = 'observations'

    id = Column(Integer, primary_key=True, autoincrement=True)
    species_id = Column(Integer, ForeignKey('species.id'), nullable=False)
    observation_date = Column(String, nullable=False)
    location = Column(String, nullable=False)
    count = Column(Integer, default=0)
    notes = Column(String)
    created_at = Column(DateTime, default=utc_now)

    # Relacje
    species = relationship("Species", back_populates="observations")

    def __repr__(self):
        return f"<Observation({self.species.common_name if self.species else 'N/A'}, {self.count}x @ {self.location})>"

default i onupdate dostają funkcję utc_now, a nie jej wynik, więc czas liczy się przy każdym zapisie. datetime.utcnow() jest od Pythona 3.12 przestarzałe.

Klasa SafariORM tworzy silnik i sesję w konstruktorze, a każda jej metoda wykonuje jedną operację CRUD:

class SafariORM:
    """Zarządzanie bazą danych Safari przez ORM"""

    def __init__(self, db_url: str = "sqlite:///safari_orm.db"):
        self.engine = create_engine(db_url, echo=False)
        Base.metadata.create_all(self.engine)
        Session = sessionmaker(bind=self.engine)
        self.session = Session()

    # === SPECIES ===

    def create_species(self, scientific_name: str, common_name: str,
                      population: int = 0, habitat: str = "",
                      endangered: bool = False) -> Species:
        """Dodaj gatunek"""
        species = Species(
            scientific_name=scientific_name,
            common_name=common_name,
            population=population,
            habitat=habitat,
            endangered=endangered
        )
        self.session.add(species)
        self.session.commit()
        return species

    def get_species(self, species_id: int) -> Optional[Species]:
        """Pobierz gatunek"""
        return self.session.get(Species, species_id)

    def list_species(self, endangered: Optional[bool] = None,
                    habitat: Optional[str] = None) -> List[Species]:
        """Lista gatunków"""
        query = self.session.query(Species)

        if endangered is not None:
            query = query.filter(Species.endangered == endangered)
        if habitat:
            query = query.filter(Species.habitat == habitat)

        return query.order_by(Species.common_name).all()

    def update_species(self, species_id: int, **kwargs) -> Optional[Species]:
        """Zaktualizuj gatunek"""
        species = self.session.get(Species, species_id)
        if not species:
            return None

        for key, value in kwargs.items():
            if hasattr(species, key):
                setattr(species, key, value)

        species.updated_at = utc_now()
        self.session.commit()
        return species

    def delete_species(self, species_id: int) -> bool:
        """Usuń gatunek"""
        species = self.session.get(Species, species_id)
        if not species:
            return False

        self.session.delete(species)
        self.session.commit()
        return True

    # === OBSERVATIONS ===

    def create_observation(self, species_id: int, observation_date: str,
                          location: str, count: int, notes: str = "") -> Optional[Observation]:
        """Dodaj obserwację"""
        species = self.session.get(Species, species_id)
        if not species:
            return None

        observation = Observation(
            species_id=species_id,
            observation_date=observation_date,
            location=location,
            count=count,
            notes=notes
        )
        self.session.add(observation)
        self.session.commit()
        return observation

    def get_observations_for_species(self, species_id: int) -> List[Observation]:
        """Obserwacje gatunku"""
        return self.session.query(Observation).filter(
            Observation.species_id == species_id
        ).order_by(Observation.observation_date.desc()).all()

    def close(self):
        """Zamknij sesję"""
        self.session.close()

Metody zwracają modele albo None, więc reszta programu nie dotyka SQL ani sesji.

Demonstracja używa bazy w pamięci, więc kolejne uruchomienia nie kłócą się o unikalne nazwy:

# === DEMONSTRACJA ===

print("=== SAFARI ORM SYSTEM ===\n")

db = SafariORM("sqlite:///:memory:")

# 1. Dodaj gatunki
print("1. Dodawanie gatunków (ORM)...")
lion = db.create_species("Panthera leo", "Lew", 120, "sawanna", True)
elephant = db.create_species("Loxodonta africana", "Słoń", 450, "sawanna", True)
gorilla = db.create_species("Gorilla gorilla", "Goryl", 230, "las", True)

print(f"   Dodano: {lion}, {elephant}, {gorilla}")

# 2. Pobierz gatunek
print("\n2. Pobieranie gatunku...")
retrieved_lion = db.get_species(lion.id)
print(f"   {retrieved_lion.common_name}: {retrieved_lion.population} osobników")

# 3. Lista zagrożonych
print("\n3. Lista zagrożonych gatunków...")
endangered = db.list_species(endangered=True)
for species in endangered:
    print(f"   - {species.common_name}: {species.population}")

# 4. Aktualizacja
print("\n4. Aktualizacja populacji...")
db.update_species(lion.id, population=125)
lion = db.get_species(lion.id)
print(f"   Nowa populacja lwa: {lion.population}")

# 5. Dodaj obserwacje
print("\n5. Dodawanie obserwacji...")
db.create_observation(lion.id, "2024-01-15", "Serengeti", 12, "Pride with cubs")
db.create_observation(lion.id, "2024-01-20", "Masai Mara", 8, "Male coalition")

# 6. Pobierz obserwacje
print("\n6. Obserwacje lwa...")
observations = db.get_observations_for_species(lion.id)
for obs in observations:
    print(f"   - {obs.observation_date}: {obs.count}x @ {obs.location}")

# 7. Relacje
print("\n7. Nawigacja przez relacje...")
lion = db.get_species(lion.id)
print(f"   Lew ma {len(lion.observations)} obserwacji:")
for obs in lion.observations:
    print(f"     {obs.location}: {obs.count}x")

db.close()
print("\nDemonstracja zakończona")

Adres bazy to zawsze URL, np. sqlite:///plik.db - sama nazwa pliku skończy się błędem ArgumentError.

Zajrzyjmy do następnego obozu

Za chwilę Darwin pokaże Ci NoSQL MongoDB - bazę dokumentową bez sztywnego schematu. Te same kroki wyglądają tam tak (wymaga serwera MongoDB):

from pymongo import MongoClient

client = MongoClient()      # połączenie z serwerem MongoDB
db = client["safari"]       # wybór bazy
db.animals.insert_one({"name": "Lew", "population": 120})
results = db.animals.find() # kursor z dokumentami

Nie ma tu modelu ani create_all() - kolekcja animals powstaje przy pierwszym zapisie.

Podsumowanie

W tej lekcji nauczyłeś/aś się:

  • Czym jest ORM i po co służy
  • SQLAlchemy: Base, modele, kolumny
  • CRUD z ORM: add, query, update, delete
  • Filtrowanie: filter(), order_by(), limit()
  • Relacje: One-to-Many, relationship, ForeignKey
  • Kompletny system Safari z ORM

Pamiętaj: ORM to cyfrowy katalog - oddajesz mu pythonowe obiekty, a formularze SQL wypełniają się za Ciebie.

Hasła z dokumentacji w tej lekcji

Widzisz błąd w tej lekcji?

Sprawdź się

Odpowiedz na pytania z tej lekcji. Wybierz odpowiedź, a od razu zobaczysz, czy jest poprawna.

  1. 1. ORM (Object-Relational Mapping) pozwala:

  2. 2. W SQLAlchemy model to:

Zadania praktyczne w grze

  • Edytor kodu

    Stwórz model Animal z polami: id, name, species, weight

  • Edytor kodu

    Pobierz wszystkie zwierzęta gatunku 'Tygrys' używając session.query()

  • Układanie w poziomie

    Ułóż elementy w prawidłowej kolejności:

  • Klikanie w kolejności

    Kliknij elementy w prawidłowej kolejności:

  • Układanie w pionie

    Uporządkuj operacje MongoDB:

  1. PytanieORM
  2. PytanieSQLAlchemy Model
  3. Zadanie z kodemSQLAlchemy Model
  4. Zadanie z kodemQuery w SQLAlchemy
  5. Ułóż w kolejnościSQL INSERT
  6. Kliknij w kolejnościBudowanie response.json()
  7. Ułóż w kolejnościMongoDB CRUD

Przydatne artykuły