Comment débuter SQLAlchemy Python 2026 (Tutoriel)

Introduction

SQLAlchemy est l'ORM (Object-Relational Mapping) de référence pour Python, utilisé par des millions de développeurs pour interagir avec des bases de données relationnelles sans écrire de SQL brut. En 2026, sa version 2.x offre une syntaxe moderne, performante et type-safe, parfaite pour les applications web (FastAPI, Django) ou scripts data.

Pourquoi l'adopter ? Contrairement au SQL natif, SQLAlchemy abstrait les dialectes DB (SQLite, PostgreSQL, MySQL), gère les migrations et prévient les injections SQL. Imaginez vos objets Python mappés directement à des tables : un User devient une ligne en DB sans boilerplate.

Ce tutoriel beginner vous emmène des bases (installation, engine) aux opérations CRUD avancées avec SQLite (idéal pour tester sans serveur). À la fin, vous aurez un script complet exécutable, prêt pour la prod. Durée : 15 min. Prêt à transformer vos données en objets ? (128 mots)

Prérequis

Python 3.10 ou supérieur installé
pip (gestionnaire de paquets Python)
Connaissances basiques de Python (classes, fonctions)
Un éditeur comme VS Code
Pas de base de données externe requise (on utilise SQLite embarqué)

Installation de SQLAlchemy

terminal

pip install sqlalchemy

Cette commande installe SQLAlchemy 2.x via pip. Elle inclut tout pour ORM, engine et dialectes DB. Vérifiez avec pip show sqlalchemy : version >=2.0 requise pour cette syntaxe moderne. Évitez pip install --user en prod pour des environnements virtuels (venv recommandé).

Comprendre l'Engine et la Base

L'engine est le cœur de SQLAlchemy : il gère les connexions DB. La base déclarative définit vos modèles. On utilise create_engine avec SQLite (sqlite:///monapp.db) pour un fichier local. Les sessions encapsulent les transactions, comme un "contexte" temporaire pour vos ops DB.

Configuration de l'Engine et Session

database.py

from sqlalchemy import create_engine
from sqlalchemy.orm import declarative_base, sessionmaker

# Engine SQLite (fichier local)
engine = create_engine("sqlite:///users.db", echo=True)

# Base pour modèles
Base = declarative_base()

# Factory de sessions
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

# Fonction helper pour obtenir une session
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

print("Engine et session configurés !")

Ce code crée un engine SQLite persistant dans users.db, une base ORM et une factory de sessions. echo=True logue les SQL pour debug (désactivez en prod). get_db() est un générateur pour FastAPI-like. Piège : oubliez finally.close() et vos connexions fuient.

Définir votre premier Modèle

Un modèle est une classe Python héritant de Base. Utilisez Column pour les champs : Integer(primary_key=True) pour ID auto-incrémenté. SQLAlchemy infère les types et contraintes. Appelons-le User avec nom, email et âge.

Définition du Modèle User

models.py

from sqlalchemy import Column, Integer, String
from database import Base

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    email = Column(String, unique=True, index=True)
    age = Column(Integer, default=18)

print(User.__tablename__)  # Vérification

Ce modèle mappe à une table users avec index pour perf queries. unique=True sur email prévient doublons. default=18 pour âge. Exécutez pour voir __tablename__. Piège : sans index=True sur champs filtrés souvent, vos queries ralentissent.

Création des Tables en DB

create_tables.py

from database import engine, Base
from models import User

# Créer toutes les tables des modèles
Base.metadata.create_all(bind=engine)
print("Tables créées avec succès !")

metadata.create_all() inspecte les modèles et crée les tables si absentes. Idéal pour dev ; en prod, utilisez Alembic pour migrations. Exécutez une fois. Piège : relancez et rien ne crash, mais drop_all() pour reset (attention données !).

Opérations CRUD de Base

CREATE : ajoutez objets à session puis commit(). READ : query.filter(). UPDATE : modifiez et commit. DELETE : delete() puis commit. Toujours dans une session transactionnelle.

CREATE et READ (Insérer et Lister)

crud_create_read.py

from database import SessionLocal, get_db
from models import User

db = SessionLocal()

# CREATE
user1 = User(name="Alice", email="alice@example.com", age=25)
user2 = User(name="Bob", email="bob@example.com", age=30)
db.add(user1)
db.add(user2)
db.commit()
db.refresh(user1)  # Recharge ID généré

# READ
users = db.query(User).all()
for user in users:
    print(f"ID: {user.id}, Nom: {user.name}, Email: {user.email}")

db.close()

Ajout batch avec add(), commit persiste. query.all() liste tout ; refresh() sync l'objet. Exécutable après tables. Piège : sans commit(), rien n'est sauvé ! Fermez toujours la session.

UPDATE et DELETE

crud_update_delete.py

from database import SessionLocal
from models import User

db = SessionLocal()

# UPDATE : trouver par ID, modifier, commit
user = db.query(User).filter(User.id == 1).first()
if user:
    user.age = 26
    db.commit()
    print(f"User {user.name} mis à jour.")

# DELETE
user_to_del = db.query(User).filter(User.email == "bob@example.com").first()
if user_to_del:
    db.delete(user_to_del)
    db.commit()
    print("User supprimé.")

# Vérif remaining
db.refresh(user)
print(f"Users restants: {db.query(User).count()}")

db.close()

Filtrez avec filter() et first(). Update direct sur objet, delete pareil. count() pour stats. Piège : filter() retourne query, pas objet ; utilisez one() pour unique ou gérez None.

Bonnes pratiques

Utilisez toujours des sessions avec context managers (with db:) pour auto-close.
Migrations avec Alembic : pip install alembic, init et autogénèrez pour prod.
Validation : intégrez Pydantic pour inputs avant DB.
Index et relations : ajoutez relationship() pour foreign keys.
Async : passez à create_async_engine pour apps async (FastAPI).
Environnements : stockez URL DB en vars d'env (python-dotenv).

Erreurs courantes à éviter

Oubli commit() : données en mémoire seulement, perdues au close.
Sessions non fermées : fuites de connexions, crash pool (limite ~5 par défaut).
Pas d'index sur champs query : perf dégradée sur gros volumes (>10k lignes).
SQL injection : toujours utiliser ORM queries, jamais f-strings en raw SQL.

Pour aller plus loin

Docs officielles : SQLAlchemy 2.0
Alembic migrations : Guide Alembic
Intégrez avec FastAPI : tutoriel Learni bientôt !
Formations expertes : Découvrez nos formations Learni sur Python avancé et bases de données.

Comment débuter avec SQLAlchemy en Python en 2026