🔖 Справочник: SQLAlchemy — движок, сессия, логирование

⚡ Шпаргалка

# Установка
pip install SQLAlchemy
pip install pymysql   # если нужен MySQL

# Строки подключения
'postgresql://user:password@localhost:5432/mydatabase'
'mysql+pymysql://user:password@localhost:3306/mydatabase'
'sqlite:///path/to/database.db'
'sqlite:///:memory:'

# Движок
from sqlalchemy import create_engine
engine = create_engine('sqlite:///:memory:')

# Создание сессии (современный стиль 2.x)
from sqlalchemy.orm import Session
with Session(engine) as session:
    session.add(obj)
    session.commit()

# Создание таблиц
Base.metadata.create_all(engine)

# Логирование
import logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger('sqlalchemy.engine')
logger.setLevel(logging.INFO)

Установка

pip install SQLAlchemy

# Для MySQL дополнительно нужна библиотека-драйвер
pip install pymysql

Строки подключения (Connection String)

Шаблон: '<DBMS>+<library>://<user>:<password>@<host>:<port>/<database>'

СУБДПример строки подключения
PostgreSQL 'postgresql://user:password@localhost:5432/mydatabase'
MySQL 'mysql+pymysql://user:password@localhost:3306/mydatabase'
SQLite (файл) 'sqlite:///path/to/database.db'
SQLite (память) 'sqlite:///:memory:'
Часть строкиОписаниеПример
<DBMS>+<library>СУБД и библиотека-драйверmysql+pymysql
<user>Имя пользователяroot
<password>Пароль пользователяsecret
<host>Адрес сервераlocalhost
<port>Порт СУБД (MySQL — 3306)3306
<database>Название базы данныхmydatabase

create_engine — создание движка

from sqlalchemy import create_engine

engine = create_engine('sqlite:///:memory:')
ПараметрТипОписание
первый аргумент (url)strСтрока подключения
echoboolВыводить SQL-запросы в консоль (для отладки)

sessionmaker — фабрика сессий (стиль лекции 1.x)

from sqlalchemy.orm import sessionmaker

# Создать фабрику сессий
Session = sessionmaker(bind=engine)

# Создать экземпляр сессии
session = Session()

Session — операции с данными (2.x)

from sqlalchemy.orm import Session

with Session(engine) as session:
    session.add(obj)        # добавить объект
    session.commit()        # зафиксировать в БД
МетодОписание
session.add(obj)Добавить объект в сессию (Transient → Pending)
session.commit()Зафиксировать изменения в БД (Pending → Persistent)
session.rollback()Откатить незафиксированные изменения
session.close()Закрыть сессию (объекты → Detached)
session.delete(obj)Пометить объект для удаления (→ Deleted)

Base.metadata.create_all — создание таблиц

# Создать все таблицы, описанные в подклассах Base
Base.metadata.create_all(engine)

Вызывается после объявления всех моделей, до начала работы с сессией. Если таблица уже существует — ничего не происходит.

Состояния объекта в сессии

СостояниеОписание
TransientОбъект создан, но не связан с сессией
PendingОбъект добавлен в сессию через add(), но ещё не сохранён в БД
PersistentОбъект сохранён в БД и находится под управлением сессии
DetachedОбъект был в сессии, но сейчас отсоединён от неё (после close)
DeletedОбъект удалён из БД в рамках текущей сессии

Логирование (модуль logging)

import logging

# Настройка базового логирования
logging.basicConfig(level=logging.INFO)

# Логгер для SQL-запросов SQLAlchemy
logger = logging.getLogger('sqlalchemy.engine')

# Включить логирование SQL-запросов
logger.setLevel(logging.INFO)

Declarative ORM 2.x — объявление моделей

Современный стиль (рекомендуется в новых проектах):

from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import String, Integer

class Base(DeclarativeBase):
    pass

class User(Base):
    __tablename__ = 'users'
    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str] = mapped_column(String(30))
    age: Mapped[int] = mapped_column(Integer)
Тип SQLAlchemyPython типSQL тип
IntegerintINTEGER
String(N)strVARCHAR(N)
FloatfloatREAL
BooleanboolBOOLEAN
Numeric(p,s)DecimalNUMERIC