sqlalchemy-alembic-expert-best-practices-code-review
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.
Install
Use with your agent
Install the sqlalchemy-alembic-expert-best-practices-code-review skill, then use it as build context. Run: npx skills add https://github.com/wispbit-ai/skills --skill sqlalchemy-alembic-expert-best-practices-code-review. Then read the installed skill.md and follow its guidance to build or refactor my project.
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 usepostgresql_concurrently=Truewith autocommit blocks for index operationsverify-query-patterns-are-indexed- Ensure SQLAlchemy queries have appropriate indexes definedunique-constraint- Split unique constraint creation into concurrent index + constraint stepssplit-foreign-key- Add foreign keys withNOT VALIDfirst, then validate separatelychange-column-type- Use multi-step approach for column type changes to avoid table lockssplit-check-constraint- Add check constraints withNOT VALIDfirst, then validate separatelylimit-non-unique-index- Limit non-unique indexes to maximum three columns for efficiencyensure-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