alembic-migration

Enforce ORM models and Alembic migrations as the schema source of truth.

5|1|Updated May 9, 2026
One-click install
npx skills add https://github.com/ql-link/LinkRag --skill alembic-migration
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: alembic-migration
Source: https://github.com/ql-link/LinkRag/tree/main/.ai/skills/alembic-migration
Command: npx skills add https://github.com/ql-link/LinkRag --skill alembic-migration

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

The Alembic-migration skill enforces that the source of truth for schema evolution is the combination of ORM models and Alembic migrations, preventing ad-hoc changes to the frozen migrations/db.sql baseline.

Core Features & Use Cases

  • Enforces a strict workflow: modify src/models/**.py, generate a new migration under migrations/versions, validate the upgrade/downgrade paths, and keep documentation in sync.
  • Prevents drift between ORM definitions, migrations, and database DDL by requiring doc synchronization in docs/api/schemas/mysql.md.
  • Use Case: When adding a field to a model, update the ORM, generate a matching Alembic migration, verify it, and update the docs to reflect the new schema, all through the defined pipeline.

Quick Start

Update the ORM model, generate and review the migration, then run the validation and doc synchronization steps.

Frequently Asked Questions about alembic-migration

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I generate Alembic migrations from ORM models without causing schema drift?

To prevent schema drift, modify your ORM models in src/models, generate a matching Alembic migration under migrations/versions, validate upgrade and downgrade paths, and synchronize documentation across the migration chain.

What is the correct workflow for schema evolution using ORM models and Alembic?

Schema evolution requires modifying ORM models as the source of truth, generating a new Alembic migration, validating the migration paths, and updating documentation in docs/api/schemas/mysql.md to prevent drift from the database DDL.

Can I use Alembic migrations to synchronize database documentation automatically?

Yes, the migration workflow enforces documentation synchronization by requiring updates to docs/api/schemas/mysql.md whenever a new Alembic migration is generated, ensuring the schema documentation reflects the latest ORM models and database DDL.

Does the Alembic migration workflow require validating both upgrade and downgrade paths?

Yes, validating both upgrade and downgrade paths is a mandatory step in the Alembic migration workflow, ensuring that schema changes applied to the ORM models can be safely rolled back if needed.

When do I need to generate a new Alembic migration for my Python ORM models?

You need to generate a new Alembic migration whenever you apply changes that modify src/models/**.py files, ensuring the database schema evolution is tracked through the ORM and migration pipeline rather than ad-hoc SQL edits.