1---2name: sqlalchemy-code-review3description: Reviews SQLAlchemy code for session management, relationships, N+1 queries, and migration patterns. Use when reviewing SQLAlchemy 2.0 code, checking session lifecycle, relationship() usage, or Alembic migrations.4---5
6# SQLAlchemy Code Review
7
8## Quick Reference
9
10| Issue Type | Reference |
11|------------|-----------|
12| Session lifecycle, context managers, async sessions | [references/sessions.md](references/sessions.md) |
13| relationship(), lazy loading, N+1, joinedload | [references/relationships.md](references/relationships.md) |
14| select() vs query(), ORM overhead, bulk ops | [references/queries.md](references/queries.md) |
15| Alembic patterns, reversible migrations, data migrations | [references/migrations.md](references/migrations.md) |
16
17## Review Checklist
18
19- [ ] Sessions use context managers (`with`, `async with`)
20- [ ] No session sharing across requests or threads
21- [ ] Sessions closed/cleaned up properly
22- [ ] `relationship()` uses appropriate `lazy` strategy
23- [ ] Explicit `joinedload`/`selectinload` to avoid N+1
24- [ ] No lazy loading in loops (N+1 queries)
25- [ ] Using SQLAlchemy 2.0 `select()` syntax, not legacy `query()`
26- [ ] Bulk operations use bulk_insert/bulk_update, not ORM loops
27- [ ] Async sessions use proper async context managers
28- [ ] Migrations are reversible with `downgrade()`
29- [ ] Data migrations use `op.execute()` not ORM models
30- [ ] Migration dependencies properly ordered
31
32## Gates (SQLAlchemy-specific)
33
34Run **once per SQLAlchemy-related finding**, after you can anchor **`file:line`** (see [review-verification-protocol](../review-verification-protocol/SKILL.md)) and **before** the finding ships. If a step’s pass condition is not met, **do not** assert the finding as written—gather evidence, withdraw, downgrade severity, or rephrase as a question.
35
36### Gate 1 — Session scope and lifecycle
37
38| Step | Action | **Pass condition** |
39|------|--------|---------------------|
40| 1a | Open the module where the session is created or injected (not from memory). | **`file:line`** for `Session`, `sessionmaker`, `async_session`, or the factory/`Depends()` that yields a session. |
41| 1b | If claiming leak, cross-request sharing, or missing cleanup: trace the session’s scope (context manager, `try`/`finally`, middleware). | **Scoped region** cited with a **`file:line` range**, or withdraw if scope is correct after the read. |
42
43### Gate 2 — N+1, lazy loading, eager loads
44
45| Step | Action | **Pass condition** |
46|------|--------|---------------------|
47| 2a | Identify the loop or repeated call site (ORM attribute access, `execute` in a loop). | **`file:line`** for the loop or hot path. |
48| 2b | If claiming N+1: name the relationship or query pattern emitted per iteration. | **Relationship or per-iteration SQL pattern** with **`file:line`**, or rephrase as a question if unclear. |
49
50### Gate 3 — Migrations (Alembic)
51
52| Step | Action | **Pass condition** |
53|------|--------|---------------------|
54| 3a | Open the revision file (e.g. under `versions/`, or the project’s Alembic layout). | **Repo-relative path** + **`file:line`** for `revision` / `upgrade` / `downgrade`. |
55| 3b | If claiming broken `downgrade()` or risky data migration: point at the `op.*` / `op.execute()` involved. | **Snippet or line range** in that file for each claimed op, or withdraw. |
56
57## When to Load References
58
59- Reviewing session creation/cleanup → sessions.md
60- Reviewing model relationships → relationships.md
61- Reviewing database queries → queries.md
62- Reviewing Alembic migration files → migrations.md
63
64## Review Questions
65
661. Are all sessions properly managed with context managers?
672. Are relationships configured to avoid N+1 queries?
683. Are queries using SQLAlchemy 2.0 `select()` syntax?
694. Are all migrations reversible and properly tested?
majiayu000