Skip to main content
skill CX Codex

sqlalchemy-code-review — Claude Code skill: install

sqlalchemy-code-review reviews SQLAlchemy code for session, relationship, query, and migration issues. Use it when checking SQLAlchemy 2.0 or Alembic changes.

Apache-2.0 228 installs ★ 89 updated 2026-09-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add existential-birds/beagle --skill sqlalchemy-code-review -a claude-code
Open on GitHub

What sqlalchemy-code-review does

This skill reviews Session and async-session lifetime, relationship() settings, lazy loading, and N+1 query risks. It also checks SQLAlchemy 2.0 select() usage, bulk operations, and Alembic revisions with both upgrade and downgrade paths.

The package combines a review checklist with reference material for sessions, relationships, queries, and migrations. Each SQLAlchemy finding must be tied to file:line; an N+1 claim needs the loop and relationship or repeated SQL pattern, while a migration claim needs the relevant op.* or op.execute() call.

A finding without file:line evidence cannot ship as written. The skill’s gates require more evidence, a lower severity, or a question instead.

What it helps with

  • check session cleanup across request and thread boundaries
  • spot N+1 queries caused by relationship access
  • replace legacy query() calls with select()
  • review ORM bulk-operation patterns
  • verify reversible Alembic migrations

Example prompts for the agent

  • Review this module’s Session lifecycle and tie every finding to file:line.
  • Inspect the models and queries for N+1 behavior, then check relationship(), joinedload, and selectinload.
  • Audit the Alembic revisions for valid upgrade() and downgrade() functions and cite the relevant lines.

How to install sqlalchemy-code-review

1Skills CLI (Vercel)

npx skills add existential-birds/beagle --skill sqlalchemy-code-review -a claude-code

2Manually: put the files in place

~/.claude/skills/sqlalchemy-code-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/sqlalchemy-code-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about sqlalchemy-code-review

How do I install sqlalchemy-code-review in Claude Code?

Run npx skills add existential-birds/beagle --skill sqlalchemy-code-review -a claude-code, then check ~/.claude/skills/sqlalchemy-code-review/SKILL.md.

What does sqlalchemy-code-review do?

It reviews session scope, relationships, N+1 risks, SQLAlchemy 2.0 queries, bulk operations, and Alembic migrations. Findings are checked against concrete file and line evidence.

What evidence is required for an N+1 finding?

The review must identify the loop or repeated call and name the relationship or SQL pattern run per iteration. Both parts need a file:line reference.

Source text

SKILL.md · Apache-2.0
---
name: sqlalchemy-code-review
description: 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.
---

# SQLAlchemy Code Review

## Quick Reference

| Issue Type | Reference |
|------------|-----------|
| Session lifecycle, context managers, async sessions | [references/sessions.md](references/sessions.md) |
| relationship(), lazy loading, N+1, joinedload | [references/relationships.md](references/relationships.md) |
| select() vs query(), ORM overhead, bulk ops | [references/queries.md](references/queries.md) |
| Alembic patterns, reversible migrations, data migrations | [references/migrations.md](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 appropriate `lazy` strategy
- [ ] Explicit `joinedload`/`selectinload` to avoid N+1
- [ ] No lazy loading in loops (N+1 queries)
- [ ] Using SQLAlchemy 2.0 `select()` syntax, not legacy `query()`
- [ ] 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](../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.

### 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

1. Are all sessions properly managed with context managers?
2. Are relationships configured to avoid N+1 queries?
3. Are queries using SQLAlchemy 2.0 `select()` syntax?
4. Are all migrations reversible and properly tested?

© existential-birds · Apache-2.0 · existential-birds/beagle

Similar skills

All skills for Code review and refactoring →

From the same set68

The whole set →
adr-writing adr-writing is a Claude Code skill that turns decisions into MADR-formatted ADRs and checks them against E.C.A.D.R. criteria. It also runs in Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. CX Codex +1 254installs swift-code-review swift-code-review is a Claude Code skill that checks Swift code for concurrency, error-handling, and memory issues. It activates for .swift reviews involving async/await, actors, or Sendable. CX Codex +1 253installs review-verification-protocol review-verification-protocol — a skill that enforces verification before any code review finding enters the report: read the source freshly, search for context, distinguish bugs from style. Cuts false positives. CX Codex +1 252installs pytest-code-review pytest-code-review reviews pytest test files for async patterns, fixture scopes, parametrization, and mock targets. Catches unawaited coroutines and broken patch paths before CI runs. CX Codex +1 239installs pydantic-ai-common-pitfalls pydantic-ai-common-pitfalls walks through the mistakes that break PydanticAI agents and gives a fixed order for debugging: tool decorators, deps, output schemas, streaming. CX Codex +1 221installs agent-architecture-analysis agent-architecture-analysis audits an LLM agent codebase against the 12-Factor Agents rubric, then scores each factor and points at the files behind the score. CX Codex +1 220installs pydantic-ai-agent-creation The pydantic-ai-agent-creation skill guides PydanticAI agent setup with typed dependencies, validated outputs, and model configuration. Use it when building agents or chat systems. CX Codex +1 219installs ai-elements A skill for Claude Code, Codex, Cursor, Copilot, Gemini CLI and OpenCode: helps build chat interfaces, job queues, tool execution displays and approval workflows. Triggers on ai-elements, Queue, Tool, Confirmation, Message, PromptInput. CX Codex +1 211installs

Project sponsors

Companies that keep this analytics open