sqlalchemy-code-review
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.
- Installs
- 221
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/existential-birds/beagle --skill sqlalchemy-code-review- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads sqlalchemy-code-review automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
SQLAlchemy Code Review
Quick Reference
| Issue Type | Reference |
|---|---|
| Session lifecycle, context managers, async sessions | references/sessions.md |
| relationship(), lazy loading, N+1, joinedload | references/relationships.md |
| select() vs query(), ORM overhead, bulk ops | references/queries.md |
| Alembic patterns, reversible migrations, data migrations | references/migrations.md |
Review Checklist
- Sessions use context managers (
with,async with) - No session sharing across requests or threads
- Sessions closed/cleaned up properly
-
relationship()uses appropriatelazystrategy - Explicit
joinedload/selectinloadto avoid N+1 - No lazy loading in loops (N+1 queries)
- Using SQLAlchemy 2.0
select()syntax, not legacyquery() - Bulk operations use bulk_insert/bulk_update, not ORM loops
- Async sessions use proper async context managers
- Migrations are reversible with
downgrade() - Data migrations use
op.execute()not ORM models - Migration dependencies properly ordered
Gates (SQLAlchemy-specific)
Run once per SQLAlchemy-related finding, after you can anchor file:line (see review-verification-protocol) 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.
Gate 1 — Session scope and lifecycle
| Step | Action | Pass condition |
|---|---|---|
| 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. |
| 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. |
Gate 2 — N+1, lazy loading, eager loads
| Step | Action | Pass condition |
|---|---|---|
| 2a | Identify the loop or repeated call site (ORM attribute access, execute in a loop). | file:line for the loop or hot path. |
| 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. |
Gate 3 — Migrations (Alembic)
| Step | Action | Pass condition |
|---|---|---|
| 3a | Open the revision file (e.g. under versions/, or the project’s Alembic layout). | Repo-relative path + file:line for revision / upgrade / downgrade. |
| 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. |
When to Load References
- Reviewing session creation/cleanup → sessions.md
- Reviewing model relationships → relationships.md
- Reviewing database queries → queries.md
- Reviewing Alembic migration files → migrations.md
Review Questions
- Are all sessions properly managed with context managers?
- Are relationships configured to avoid N+1 queries?
- Are queries using SQLAlchemy 2.0
select()syntax? - Are all migrations reversible and properly tested?
FAQ
What does the sqlalchemy-code-review skill do?
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.
How do I install sqlalchemy-code-review?
Run npx skills add https://github.com/existential-birds/beagle --skill sqlalchemy-code-review in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sqlalchemy-code-review/ (personal) or .claude/skills/sqlalchemy-code-review/ (project).
Which AI agents can use sqlalchemy-code-review?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is sqlalchemy-code-review safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains sqlalchemy-code-review?
It is published by existential-birds in existential-birds/beagle. It has 221 recorded installs.
More from existential-birds/beagle
react-flow
existential-birds/beagle
React Flow (@xyflow/react) for workflow visualization with custom nodes and edges. Use when building graph visualizations, creating custom workflow nodes, implementing edge labels, or controlling viewport. Triggers on ReactFlow, @xyflow/react, Handle, NodeProps, EdgeProps, useReactFlow, fitView.
python-code-review
existential-birds/beagle
Reviews Python code for type safety, async patterns, error handling, and common mistakes. Use when reviewing .py files, checking type hints, async/await usage, or exception handling.
langgraph-code-review
existential-birds/beagle
Reviews LangGraph code for bugs, anti-patterns, and improvements. Use when reviewing code that uses StateGraph, nodes, edges, checkpointing, or other LangGraph features. Catches common mistakes in state management, graph structure, and async patterns.
tailwind-v4
existential-birds/beagle
Tailwind CSS v4 with CSS-first configuration and design tokens. Use when setting up Tailwind v4, defining theme variables, using OKLCH colors, or configuring dark mode. Triggers on @theme, @tailwindcss/vite, oklch, CSS variables, --color-, tailwind v4.
react-flow-advanced
existential-birds/beagle
Advanced React Flow patterns for complex use cases. Use when implementing sub-flows, custom connection lines, programmatic layouts, drag-and-drop, undo/redo, or complex state synchronization.
react-router-v7
existential-birds/beagle
React Router v7 best practices for data-driven routing. Use when implementing routes, loaders, actions, Form components, fetchers, navigation guards, protected routes, or URL search params. Triggers on createBrowserRouter, RouterProvider, useLoaderData, useActionData, useFetcher, NavLink, Outlet.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.