Skip to main content
skill CX Codex

sqlalchemy-alembic-expert-best-practices-code-review — skill

sqlalchemy-alembic-expert-best-practices-code-review is a Claude Code skill for writing and reviewing SQLAlchemy models, Alembic migrations, and database queries. It activates around schema changes and query tuning.

MIT 2,200 installs ★ 9 updated 2026-02-11

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add wispbit-ai/skills --skill sqlalchemy-alembic-expert-best-practices-code-review -a claude-code
Open on GitHub

What sqlalchemy-alembic-expert-best-practices-code-review does

The skill gives guidance for SQLAlchemy models, Alembic migrations, and database query patterns. Its rules cover index choices, constraints, foreign keys, and column type changes. They also address redundant indexes and whether query patterns have suitable index coverage.

Eight rule files include explanations and examples of incorrect and corrected implementations. For PostgreSQL index operations, the guidance calls for concurrent creation inside autocommit blocks. Foreign keys and CHECK constraints are added as NOT VALID first, then validated in a separate step.

What it helps with

  • review an Alembic migration before a schema change
  • spot SQLAlchemy queries without suitable indexes
  • stage a foreign key addition safely
  • remove an index already covered by a composite index

Example prompts for the agent

  • Review this Alembic migration for the new SQLAlchemy model.
  • Find queries that lack suitable indexes and suggest corrections.
  • Check the safe sequence for adding this foreign key.

How to install sqlalchemy-alembic-expert-best-practices-code-review

1Skills CLI (Vercel)

npx skills add wispbit-ai/skills --skill sqlalchemy-alembic-expert-best-practices-code-review -a claude-code

2Manually: put the files in place

~/.claude/skills/sqlalchemy-alembic-expert-best-practices-code-review/SKILL.md

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

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

Questions about sqlalchemy-alembic-expert-best-practices-code-review

How do I install sqlalchemy-alembic-expert-best-practices-code-review in Claude Code?

Run npx skills add wispbit-ai/skills --skill sqlalchemy-alembic-expert-best-practices-code-review -a claude-code.

What does sqlalchemy-alembic-expert-best-practices-code-review do?

It applies practical rules to SQLAlchemy models, Alembic migrations, and database query patterns. The rules cover indexes, constraints, and schema changes.

How does the skill handle foreign key additions?

It recommends adding the foreign key as NOT VALID first and validating it separately.

Source text

SKILL.md · MIT
---
name: sqlalchemy-alembic-expert-best-practices-code-review
description: SQLAlchemy ORM and Alembic migration best practices for building safe, performant database schemas. This skill should be used when writing, reviewing, or refactoring SQLAlchemy models, Alembic migrations, or database query patterns. Triggers on tasks involving SQLAlchemy ORM, Alembic migrations, database schema changes, or query optimization.
license: MIT
metadata:
  author: wispbit
  version: "1.0.0"
---

# SQLAlchemy & Alembic Expert Best Practices

Simple, pragmatic, opinionated. Only what matters for writing production-grade SQLAlchemy and Alembic code.

## When to Apply

Reference these guidelines when:
- Writing Alembic migrations for schema changes
- Creating or modifying SQLAlchemy models
- Adding indexes, constraints, or foreign keys via Alembic
- Reviewing database migration code for safety
- Refactoring existing database schemas
- Optimizing query patterns or database performance

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Index Management | CRITICAL-HIGH | `only-concurrent-indexes`, `verify-query-patterns-are-indexed` |
| 2 | Constraint Safety | HIGH | `unique-constraint`, `split-foreign-key`, `change-column-type` |
| 3 | Optimization | MEDIUM | `split-check-constraint`, `limit-non-unique-index` |
| 4 | Index Efficiency | LOW | `ensure-index-not-covered` |

## Quick Reference

- `only-concurrent-indexes` - Always use `postgresql_concurrently=True` with autocommit blocks for index operations
- `verify-query-patterns-are-indexed` - Ensure SQLAlchemy queries have appropriate indexes defined
- `unique-constraint` - Split unique constraint creation into concurrent index + constraint steps
- `split-foreign-key` - Add foreign keys with `NOT VALID` first, then validate separately
- `change-column-type` - Use multi-step approach for column type changes to avoid table locks
- `split-check-constraint` - Add check constraints with `NOT VALID` first, then validate separately
- `limit-non-unique-index` - Limit non-unique indexes to maximum three columns for efficiency
- `ensure-index-not-covered` - Prevent redundant indexes that are already covered by composite indexes

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/only-concurrent-indexes.md
rules/verify-query-patterns-are-indexed.md
rules/unique-constraint.md
rules/split-foreign-key.md
rules/change-column-type.md
rules/split-check-constraint.md
rules/limit-non-unique-index.md
rules/ensure-index-not-covered.md
```

Each rule file contains:
- Brief explanation of why it matters
- Impact level and description
- Incorrect SQLAlchemy/Alembic example with explanation
- Correct implementation with best practices
- Additional context for safe migrations

© wispbit · MIT · wispbit-ai/skills

Similar skills

All skills for Data and databases →

From the same set5

Project sponsors

Companies that keep this analytics open