Всем привет! Кто хоть раз писал на Python и сталкивался с базами данных, наверняка слышал про SQLAlchemy. Эта штука — не просто обёртка над SQL, а целый фреймворк для работы с БД, который делает жизнь проще (и иногда сложнее, если не читать доку). Давайте разберёмся, зачем вообще нужна интеграция Python и SQL, почему SQLAlchemy — это не только про ORM, и как быстро стартануть без боли.

Почему это важно

Когда проект вырастает из «скрипта на коленке», хочется хранить данные не в файле, а в нормальной базе. Но писать сырые SQL-запросы — больно, особенно когда надо поддерживать несколько СУБД или миграции. SQLAlchemy позволяет писать код, который будет работать и с SQLite, и с PostgreSQL, и с MySQL — и не бояться за переносимость или читаемость. Плюс, это стандарт де-факто в Python-экосистеме (Django ORM — другая история, не путайте).

Возможности SQLAlchemy

• Работа с разными СУБД: SQLite, PostgreSQL, MySQL, MSSQL и др.
• Два режима: Core (чистый SQL через Python-объекты) и ORM (объектно-реляционное отображение).
• Гибкая система миграций (через Alembic, если надо).
• Возможность писать как «сырые» SQL-запросы, так и работать через Python-классы.
• Поддержка асинхронности (с версии 1.4+).

Что требуется (требования, ос, железо)

• Python 3.7+ (официально поддерживается на момент написания поста)
• pip (стандартный пакетный менеджер Python)
• Любая ОС: Linux, MacOS, Windows — всё работает
• Для работы с конкретной БД — клиент/драйвер (например, psycopg2 для PostgreSQL, pymysql для MySQL, sqlite3 встроен в Python)
• Железо — любой современный ПК, SQLAlchemy не прожорливый

Установка — пошаговая инструкция

1. Создай виртуальное окружение (рекомендую, чтобы не засорять глобальные пакеты):

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   venv\Scripts\activate     # Windows

2. Установи SQLAlchemy:

   pip install sqlalchemy

3. Если работаешь с PostgreSQL:

   pip install psycopg2-binary

   Или с MySQL:

   pip install pymysql

   Для SQLite ничего ставить не надо, всё уже есть.

4. (Опционально) Для асинхронной работы:

   pip install asyncpg

5. (Опционально) Для миграций:

   pip install alembic

Всё! Теперь можно писать код.

Использование: полный список команд и вариантов

Создание подключения (engine)

from sqlalchemy import create_engine

# SQLite (файл)
engine = create_engine('sqlite:///mydb.sqlite3')

# PostgreSQL
engine = create_engine('postgresql+psycopg2://user:password@localhost/dbname')

# MySQL
engine = create_engine('mysql+pymysql://user:password@localhost/dbname')

Создание таблиц через ORM

from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Integer, String

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String)

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

Base.metadata.create_all(engine)

Работа с сессией

from sqlalchemy.orm import sessionmaker

Session = sessionmaker(bind=engine)
session = Session()

# Добавить пользователя
user = User(name='Vasya', email='vasya@example.com')
session.add(user)
session.commit()

# Получить пользователей
users = session.query(User).all()
for u in users:
    print(u.name, u.email)

# Фильтрация
vasya = session.query(User).filter_by(name='Vasya').first()
print(vasya.email)

Сырые SQL-запросы

with engine.connect() as conn:
    result = conn.execute("SELECT * FROM users")
    for row in result:
        print(row)

Асинхронная работа (пример для PostgreSQL)

import asyncio
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

async def main():
    engine = create_async_engine(
        'postgresql+asyncpg://user:password@localhost/dbname', echo=True)
    async_session = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)
    async with async_session() as session:
        result = await session.execute(select(User))
        users = result.scalars().all()
        print(users)

asyncio.run(main())

Больше примеров в официальной документации SQLAlchemy.

Ошибки и как делать не надо

• Не храните пароли в коде! Используйте переменные окружения или секреты.
• Не забывайте закрывать сессии (session.close() или используйте with).
• Не мешайте ORM и Core без явной необходимости — определитесь со стилем.
• Не забывайте про миграции: если меняете структуру таблицы — используйте Alembic.
• Не используйте sqlite:///:memory: в проде — это только для тестов.

Пример реального использования в окружении

Допустим, у вас есть микросервис на Flask, который хранит пользователей в PostgreSQL. Вы хотите быстро накатить миграции и не париться с SQL-скриптами. Вот как это обычно выглядит:

# models.py
from sqlalchemy.orm import declarative_base
from sqlalchemy import Column, Integer, String

Base = declarative_base()

class User(Base):
    __tablename__ = 'users'
    id = Column(Integer, primary_key=True)
    name = Column(String)
    email = Column(String)

# db.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

engine = create_engine('postgresql+psycopg2://user:pass@localhost/db')
Session = sessionmaker(bind=engine)

# main.py
from models import User, Base
from db import engine, Session

Base.metadata.create_all(engine)

session = Session()
session.add(User(name='Alice', email='alice@wonder.land'))
session.commit()
session.close()

Всё, теперь у вас есть рабочая связка Python + PostgreSQL через SQLAlchemy. Если нужно миграции — подключаете Alembic (https://alembic.sqlalchemy.org/) и забываете про ручные ALTER TABLE.

Заключение

SQLAlchemy — реально мощный инструмент, если не лениться читать доку и не пытаться изобрести велосипед. Для старта достаточно пары минут, для продакшена — чуть больше времени и внимания к деталям. Не бойтесь экспериментировать и не забывайте про официальную документацию — там реально всё расписано.

Если остались вопросы — добро пожаловать в комменты или на Stack Overflow. Happy coding!