Skip to content

amiable-dev/alembic-sqlalchemy

v0.1.0MIT

Claude Code skill for Alembic migrations and SQLAlchemy 2.x: ten rules for safe, zero-downtime schema changes, an env.py / pyproject template, a static revision linter and a compact status script.

GitHubOpen Website

alembic-sqlalchemy

A Claude Code skill that makes Claude handle Alembic migrations and SQLAlchemy 2.x the way an experienced database engineer would: safe schema changes, a clean revision history, and far less reading of your versions/ directory.

Install

In Claude Code:

/plugin marketplace add amiable-dev/alembic-sqlalchemy
/plugin install alembic-sqlalchemy@amiable-alembic-sqlalchemy

Check with /plugin list. Other ways to install, updating and removing: docs/install.md.

Use

Nothing to configure. Ask Claude for anything that touches your schema and the skill takes over:

  • "Add a nullable note column to invoices and write the migration."
  • "We have two heads after the merge. Fix it."
  • "Review this migration before it goes to production."
  • "Why does this endpoint run 200 queries?"

Claude runs the skill's status script instead of reading every migration file, autogenerates and reviews the revision, lints it, and ends with a short report: what changed, what is risky, and in which order to deploy.

The two scripts also work on their own, from a project root:

bash skills/alembic-sqlalchemy/scripts/migration_status.sh
python skills/alembic-sqlalchemy/scripts/lint_revision.py migrations/versions/<file>.py

What Claude does step by step, the scripts' options, and the linter's codes: docs/usage.md.

What it enforces

Ten rules, each backed by a reference that Claude loads only when needed. In short: revisions come from alembic revision and are never hand-numbered; autogenerate output is checked against its blind spots; applied revisions are immutable; revision files never import your models; every constraint has a name; live tables change by expand and contract; migrations are tested on the real database; SQLAlchemy code uses 2.x idioms with lazy loads made loud; one session per unit of work; env.py is hardened once.

The rules with their reasons: docs/rules.md. Rolling the skill out to a project that already has migrations, hand-numbered ones included: docs/adopting-in-an-existing-project.md.

Documentation

PageFor
docs/install.mdevery install option, updating, removing
docs/usage.mdwhat Claude does, the scripts, linter codes, CI snippets
docs/rules.mdthe ten rules and why they exist
docs/adopting-in-an-existing-project.mdteams with existing migrations
docs/development.mdrepo layout, tests, cutting a release

Targets Alembic 1.19 and SQLAlchemy 2.0 / 2.1. MIT licensed, see LICENSE.