Часть 1. Введение в ORM и SQLAlchemy

1.1 Что такое ORM?

Представьте, что у вас есть база данных (таблицы, строки, внешние ключи) и код на Python (классы, объекты, списки). Они говорят на разных языках. Чтобы сохранить объект Python в БД, вам пришлось бы вручную разбирать его на переменные и писать SQL-запрос `INSERT INTO...`.

ORM (Object-Relational Mapping) — это «переводчик», который делает это за вас. Она позволяет работать с таблицами базы данных так, будто это обычные объекты Python:

• Строка в таблице превращается в экземпляр класса.
• Столбец таблицы становится атрибутом этого класса.
• SQL-запросы заменяются на вызов методов (например, session.add()).

1.2 Почему именно SQLAlchemy?

В экосистеме Python много ORM (например, встроенная в Django или Peewee), но SQLAlchemy — стандарт де-факто для серьезных проектов. Её главная особенность — гибкость. Она предлагает два уровня работы:

Часть 3. SQLAlchemy Core: создание таблиц «вручную»

Этот раздел важен для понимания того, как SQLAlchemy работает "под капотом". В реальной жизни вы чаще будете использовать подход из Части 4.

3.1 Описание схемы данных

В подходе Core мы явно создаем объекты Table, описывая каждую колонку. Все таблицы должны быть зарегистрированы в специальном каталоге — объекте MetaData. Это позволяет SQLAlchemy знать всё о структуре нашей БД.

from sqlalchemy import MetaData, Table, Column, Integer, String

# 1. Создаем каталог метаданных
metadata = MetaData()

# 2. Описываем таблицу "authors"
authors_table = Table(
    "authors", metadata,                     # Имя таблицы и привязка к метаданным
    Column("id", Integer, primary_key=True), # Первичный ключ
    Column("username", String(32), nullable=False, unique=True),
    Column("email", String, nullable=True, unique=True)
)

3.2 Создание таблиц в базе

Теперь, когда мы описали структуру в Python, нужно отправить команду в базу данных, чтобы она создала физические таблицы. Для этого создается Engine (Движок) — это точка входа для любого взаимодействия с БД.

from sqlalchemy import create_engine

# Строка подключения: драйвер://пользователь:пароль@хост:порт/база
db_url = "postgresql+pg8000://user:example@localhost:5432/blog"

# echo=True выводит все SQL-запросы в консоль (полезно для обучения)
engine = create_engine(db_url, echo=True)

# Команда create_all смотрит в metadata и создает таблицы, которых еще нет
metadata.create_all(bind=engine)

Часть 5. Работа с данными через Session

5.1 Что такое Сессия?

Session — это "рабочая область" для ваших объектов. Вы не пишете данные в базу мгновенно. Сначала вы добавляете объекты в сессию (как товары в корзину), а затем выполняете commit (оплата на кассе), чтобы отправить все изменения в базу одной транзакцией.

from sqlalchemy.orm import sessionmaker, Session

# Фабрика для создания сессий
SessionLocal = sessionmaker(bind=engine)

# Использование через контекстный менеджер (рекомендуется)
# Это гарантирует, что сессия закроется даже при ошибках
with SessionLocal() as session:
    pass

5.2 Добавление данных (Create)

Чтобы создать запись, мы просто создаем экземпляр класса User и передаем его сессии. Обратите внимание: пока не вызван commit(), данные существуют только в памяти Python и транзакции БД, но не зафиксированы.

def create_user(session: Session, username: str, email: str = None):
    # 1. Создаем объект Python
    new_user = User(username=username, email=email)

    # 2. Добавляем в сессию ("в корзину")
    session.add(new_user)

    # 3. Фиксируем изменения (генерирует INSERT и выполняет COMMIT)
    session.commit()

    print(f"Пользователь сохранен с ID: {new_user.id}")
    return new_user

5.3 Массовая вставка

Если нужно добавить много объектов, используйте add_all(). SQLAlchemy оптимизирует это в один эффективный запрос.

users_list = [
    User(username="alice"),
    User(username="bob"),
    User(username="charlie")
]
session.add_all(users_list)
session.commit()

Часть 7. Обновление данных (Update)

7.1 "Pythonic" способ (объектный)

Это классический способ ORM. Мы загружаем объект в память, меняем его свойства (как у обычного объекта Python), а затем делаем коммит. SQLAlchemy автоматически отследит изменения (Dirty checking) и сгенерирует нужный UPDATE.

user = session.get(User, 1)  # 1. Загрузили
if user:
    user.email = "Адрес электронной почты защищен от спам-ботов. Для просмотра адреса в браузере должен быть включен Javascript."  # 2. Изменили
    session.commit()  # 3. Сохранили (SQL генерируется здесь)

7.2 Массовое обновление (SQL style)

Если нужно обновить тысячи записей, загружать их все в память объектов неэффективно. Лучше отправить один SQL-запрос UPDATE. Это делается через функцию update().

from sqlalchemy import update

stmt = (
    update(User)
    .where(User.username.ilike("%test%"))  # Кого обновляем?
    .values(email=None)                    # Что устанавливаем?
)
session.execute(stmt)
session.commit()