SQLAlchemy - najważniejsze informacje i podstawowa konfiguracja

SQLAlchemy to popularne narzędzie służące do mapowania obiektowo-relacyjnego (ORM) w języku Python. Jest ono powszechnie używane w projektach mających do czynienia z bazami danych typu SQL. SQLAlchemy zapewnia intuicyjny interfejs do tworzenia i zarządzania tabelami, relacjami oraz zapytaniami do bazy danych. Dzięki temu programiści mogą skupić się na implementacji logiki biznesowej, zamiast na bezpośrednim korzystaniu z języka SQL. Podstawowa konfiguracja SQLAlchemy obejmuje określenie połączenia do bazy danych oraz zdefiniowanie modeli obiektów mapowanych na tabele. 

Instalacja i konfiguracja SQLAlchemy

Instalacja i konfiguracja SQLAlchemy to niezwykle prosta i szybka procedura. Aby rozpocząć, należy najpierw zainstalować SQLAlchemy za pomocą menadżera pakietów, takiego jak pip. 

pip install SQLAlchemy

Po zainstalowaniu, możemy go zaimportować do naszego projektu Pythona. Pakiet jest dostępny pod nazwą sqlalchemy. Następnie należy skonfigurować połączenie do bazy danych, wykorzystując odpowiednie dane takie jak nazwa bazy danych, użytkownik, hasło, host i port. Składnia to:

from sqlalchemy import create_engine

engine = create_engine(
	"<dialekt>+<driver>://<użytkownik>:<hasło>@<host>:<port>/<baza danych>"
)

Dostępne dialekty to mysql, postgresql, oracle, mssql i sqlite. Driver to API używane do komunikacji z bazą. Może być to na przykład mysqlconnector dla MySQL lub psycopg2 dla PostgreSQL. Do funkcji create_engine możemy przekazać też argument nazwany echo z wartością True, aby logować do konsoli wykonywane zapytania SQL.

Czy szukasz wykonawcy projektów IT ?

Sprawdź case studies

Deklarowanie modeli

Na początek powinniśmy zdefiniować modele. Zgodnie z dokumentacją SQLAlchemy powinniśmy utworzyć klasę bazową, a następnie klasy modeli, które po niej dziedziczą. Wygląda to w ten sposób:

from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
	pass

Klasę Base możemy rozwinąć o dodatkowe funkcjonalności, jak customowa metoda dict(), aby ułatwić konwertowanie obiektów bazy danych do słowników. SQLAlchemy posiada wsparcie dla modułu typing, dzięki czemu tworzenie modeli wygląda w ten sposób:

 from typing import Optional
 from sqlalchemy import String
 from sqlalchemy.orm import Mapped, mapped_column
 
 class User(Base):
 	__tablename__ = "users"
 	
 	id: Mapped[int] = mapped_column(primary_key=True)
 	email: Mapped[Optional[str]]
 	username: Mapped[str] = mapped_column(String(30))

Funkcja mapped_column służy do deklarowania kolumny w tabeli bazy danych. Jeśli używamy Mapped jako adnotacji typu, to mapped_column jest potrzebny tylko do doprecyzowania cech kolumny takich jak maksymalna długość, czy klucz główny. Tabele tworzymy za pomocą metody Base.metadata.create_all(), przekazując nasz utworzony engine jako argument.

Relacje

Relacje tworzymy dokładnie tak jak pola, tylko używamy funkcji relationship. Co ciekawe, jeśli chcemy, aby nasza relacja działała w obie strony, musimy ją zdefiniować również na dwóch obiektach (inaczej, niż na przykład w Django ORM). Wygląda to tak:

from typing import List
from sqlalchemy.orm import relationship, Mapped, mapped_column
from sqlalchemy import ForeignKey

class Article(Base):
	
	id: Mapped[int] = mapped_column(primary_key=True)
	author_id: Mapped[int] = mapped_column(ForeignKey("users.id"))
	author: Mapped["User"] = relationship("User", back_populates="articles")
	
class User(Base):
	...
	articles: Mapped[List["Article"]] = relationship(back_populates="author")

CRUD

Crud natomiast nie jest już tak intuicyjny. Trzeba zaimportować engine i utworzyć sesję. W tym snippecie kodu utworzymy User'a, zaktualizujemy go, wyciągniemy z bazy, a następnie usuniemy. 

from sqlalchemy.orm import Session
from sqlalchemy import select

with Session(engine) as session:
	# CREATE
	user1 = User(email="example@example.com", username="Example")
	session.add(user1)
	session.commit()
	# RETRIEVE and UPDATE
	selected_user1 = session.scalars(select(User)).where(User.email == "example@example.com").one()
	selected_user1.username = "Example updated"
	session.commit()
	# DELETE
	session.delete(selected_user1)
	session.commit()
	
	

SQLAlchemy to rozbudowana biblioteka, która oferuje o wiele więcej funkcjonalności, niż te opisane w artykule. W razie wątpliwości zawsze warto zerknąć do dokumentacji, dostępnej na oficjalnej stronie SQLAlchemy.

Źródło: https://docs.sqlalchemy.org

FAQ – najczęstsze pytania dotyczące SQLAlchemy

1. Czym jest SQLAlchemy?

SQLAlchemy to popularna biblioteka Pythona służąca do interakcji z bazami danych. Umożliwia korzystanie zarówno z ORM (Object-Relational Mapping), jak i z niskopoziomowych zapytań SQL.

2. Czy SQLAlchemy działa z każdą bazą danych?

SQLAlchemy obsługuje wiele popularnych systemów baz danych, takich jak PostgreSQL, MySQL, SQLite, Oracle czy MS SQL Server – o ile dostępny jest odpowiedni sterownik.

3. Czym się różni SQLAlchemy ORM od SQLAlchemy Core?

• ORM pozwala pracować z bazą danych w sposób obiektowy, np. poprzez klasy i instancje Pythona.
• Core to bardziej bezpośrednie podejście, pozwalające pisać zapytania SQL w sposób programistyczny, ale z zachowaniem elastyczności i wydajności.

4. Jakie są podstawowe kroki konfiguracji SQLAlchemy?

Typowa konfiguracja obejmuje:

• Zainstalowanie biblioteki (np. pip install sqlalchemy)
• Utworzenie silnika (engine)
• Zdefiniowanie modeli (przy ORM)
• Utworzenie sesji (session) do komunikacji z bazą

5. Czy potrzebuję ORM, jeśli już znam SQL?

Nie musisz używać ORM – SQLAlchemy Core może być lepszym wyborem, jeśli preferujesz pisanie zapytań SQL bezpośrednio. ORM może jednak przyspieszyć rozwój aplikacji i ułatwić zarządzanie kodem.

6. Jakie są zalety korzystania z SQLAlchemy w porównaniu do bezpośredniego użycia SQL?

• Abstrakcja kodu (np. brak zależności od konkretnego silnika bazy)
• Łatwiejsze utrzymanie i refaktoryzacja
• Bezpieczniejsze generowanie zapytań (zapobieganie SQL Injection)
• Integracja z frameworkami webowymi (np. Flask, FastAPI)

7. Czy SQLAlchemy można połączyć z Flaskiem lub FastAPI?

Tak, SQLAlchemy bardzo dobrze współpracuje z popularnymi frameworkami webowymi. Istnieją też dodatkowe biblioteki, takie jak Flask-SQLAlchemy czy SQLModel (dla FastAPI).

8. Jakie są alternatywy dla SQLAlchemy w Pythonie?

Do alternatywnych rozwiązań należą m.in.:

• Django ORM (część frameworka Django)
• Tortoise ORM
• Pony ORM
• Peewee