Как понять, что проблема в приложении связана с SQLAlchemy, а не с индексами, схемой, isolation level или плохим SQL?

Шаг 1: увидеть реальный SQL

Первый шаг — включить логирование SQL и посмотреть, что именно уходит в базу.

import logging

# Вариант 1: стандартный логгер
logging.basicConfig()
logging.getLogger("sqlalchemy.engine").setLevel(logging.INFO)

# Вариант 2: echo при создании engine
from sqlalchemy import create_engine
engine = create_engine("postgresql+psycopg2://...", echo=True)

# Вариант 3: compile() для конкретного statement
from sqlalchemy.dialects import postgresql
stmt = select(User).where(User.age > 30)
print(stmt.compile(dialect=postgresql.dialect(), compile_kwargs={"literal_binds": True}))

Сравните полученный SQL с тем, что ожидали. Если ORM генерирует лишние JOIN, подзапросы или обращения к ненужным столбцам — проблема в SQLAlchemy.

Диагностика: откуда на самом деле проблема?

Медленный запрос или высокая latency могут объясняться четырьмя разными причинами: (1) плохой SQL, сгенерированный SQLAlchemy; (2) неэффективная стратегия загрузки (N+1, cartesian product); (3) отсутствие или неверные индексы; (4) неподходящий isolation level или блокировки. Разобраться поможет последовательная диагностика.

Шаг 2: замерить количество запросов

Для обнаружения N+1 используйте sqlalchemy-querycount или счётчик внутри теста:

from sqlalchemy import event

query_count = 0

@event.listens_for(engine, "before_cursor_execute")
def count_queries(conn, cursor, statement, parameters, context, executemany):
    global query_count
    query_count += 1

# ... выполните операцию ...
print(f"Queries executed: {query_count}")

Если при загрузке 100 пользователей выполняется 101 запрос — классический N+1, решается через selectinload() или joinedload().

Шаг 3: EXPLAIN ANALYZE в PostgreSQL

Скопируйте реальный SQL из логов и запустите EXPLAIN ANALYZE:

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT users.id, users.name, addresses.city
FROM users
JOIN addresses ON addresses.user_id = users.id
WHERE users.age > 30;

Обратите внимание на: Seq Scan (нет индекса), Hash Join vs Nested Loop (планировщик выбирает оптимальный тип), rows= (расхождение estimate и actual — устаревшая статистика, нужен ANALYZE), Buffers: shared hit/read (cache miss).

Если EXPLAIN показывает Sequential Scan на большой таблице — проблема в индексах, а не в SQLAlchemy.

Шаг 4: проверить isolation level и блокировки

-- Посмотреть активные блокировки
SELECT pid, query, state, wait_event_type, wait_event
FROM pg_stat_activity
WHERE wait_event IS NOT NULL;

-- Найти deadlocks в логах PostgreSQL
-- log_lock_waits = on в postgresql.conf

Если latency скачет под нагрузкой, но EXPLAIN ANALYZE быстрый — скорее всего, блокировки или contention на строках (SELECT FOR UPDATE без индекса, долгие транзакции).

Шаг 5: профилировать на уровне Python

import cProfile
import pstats

with cProfile.Profile() as pr:
    # вызов бизнес-логики
    result = my_service.load_dashboard(user_id=42)

stats = pstats.Stats(pr)
stats.sort_stats("cumulative")
stats.print_stats(20)  # топ-20 узких мест

Если большое время в sqlalchemy/orm/loading.py — проблема в ORM (инструментирование, identity map). Если в psycopg2/_psycopg.so — сетевой round-trip или большой объём данных.

Быстрая диагностическая схема

• Много запросов при небольших данных → N+1 в SQLAlchemy (lazy loading).
• Один медленный запрос → EXPLAIN ANALYZE: Seq Scan → добавить индекс; плохой план → pg_hint_plan или переписать запрос.
• Latency растёт под нагрузкой, но локально быстро → блокировки / isolation level SERIALIZABLE.
• ORM медленнее raw SQL на одинаковых данных → накладные расходы identity map → использовать Core или bulk операции.
• После добавления индекса EXPLAIN не использует его → несоответствие типов, OR-условие, функция на столбце.

Подводные камни

• EXPLAIN без ANALYZE врёт: показывает оценку планировщика, не реальное время. Всегда используйте EXPLAIN (ANALYZE, BUFFERS).
• echo=True в продакшне: логирует каждый запрос с параметрами, включая пароли и PII. Используйте только в dev.
• Тест с маленькими данными нерепрезентативен: планировщик PostgreSQL при 10 строках выбирает Seq Scan, при 1M — Index Scan. Диагностируйте на данных близких к продакшн-объёму.
• selectinload vs joinedload: joinedload при большом количестве связанных объектов генерирует декартово произведение строк — данных в сети больше, хотя запросов меньше.
• Isolation level REPEATABLE READ / SERIALIZABLE: может значительно снижать throughput из-за конфликтов; проверяйте pg_stat_activity.wait_event = 'relation'.
• ORM не использует индекс на функции: WHERE LOWER(email) = ... требует функционального индекса CREATE INDEX ON users (LOWER(email)), иначе Seq Scan.
• autoflush скрытые запросы: SQLAlchemy делает flush перед SELECT, что добавляет неожиданные INSERT/UPDATE в середину транзакции и искажает картину при профилировании.
• pg_stat_statements: обязательно включайте в продакшне — это единственный надёжный источник агрегированной статистики медленных запросов на стороне БД.

• Сразу обвинять SQLAlchemy, не проверив соседние слои системы
• Чинить симптом без минимального воспроизведения и evidence
• Не учитывать версии, конфигурацию, окружение и recent changes

• Умеет локализовать проблему вокруг SQLAlchemy
• Двигается от симптома к гипотезам и проверкам
• Отличает баг инструмента от ошибки использования или окружения