How do I install the Alembic skill?

Run npx skillmds add majiayu000/alembic in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Alembic safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: docs only. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Alembic?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Alembic free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Alembic?

majiayu000 (@majiayu000) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Alembic by majiayu000 — Agent Skill

Name: Alembic
Rating: 4.2 (5 reviews)
Author: majiayu000

Alembic

Generates and manages database migrations with Alembic for the Bookkeep backend. Use when: creating database migrations, modifying models, adding columns, creating tables, or running schema changes.

majiayu000 d5aa153 2 files · 3.4 KB Updated Sep 9, 2026 567 repo stars

File contents

Alembic Skill

Alembic manages schema migrations for Bookkeep's SQLAlchemy models. Migrations live in backend/alembic/versions/ with numeric prefixes (001, 002, etc.). The project supports both PostgreSQL (production) and SQLite (development) with idempotent migrations using existence checks.

Quick Start

Generate Migration

cd backend
alembic revision --autogenerate -m "add_column_to_table"

Apply Migrations

cd backend
alembic upgrade head     # Apply all pending
alembic upgrade +1       # Apply next migration only
alembic downgrade -1     # Roll back one migration

Check Status

cd backend
alembic current          # Show current revision
alembic history          # List all migrations

Key Concepts

Concept	Usage	Example
Numeric prefix	Sequential ordering	`022_add_download_system.py`
Idempotent checks	Safe reruns	`if not table_exists('download_tasks'):`
batch_alter_table	SQLite compatibility	`with op.batch_alter_table('books'):`
Data migrations	Transform existing data	`op.execute("UPDATE books SET ...")`

Project Configuration

alembic.ini: backend/alembic.ini
env.py: backend/alembic/env.py (loads DATABASE_URL from app.database)
versions: backend/alembic/versions/ (30 migrations)
Models: backend/app/models.py

Common Patterns

Add Column with Default

if not column_exists('users', 'can_download'):
    op.add_column('users', sa.Column(
        'can_download', 
        sa.Boolean(), 
        nullable=True, 
        server_default='true'
    ))

Create Table with Indexes

if not table_exists('download_tasks'):
    op.create_table('download_tasks',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('book_id', sa.Integer(), nullable=False),
        sa.ForeignKeyConstraint(['book_id'], ['books.id']),
    )
if not index_exists('download_tasks', 'ix_download_tasks_book_id'):
    op.create_index('ix_download_tasks_book_id', 'download_tasks', ['book_id'])

Related Skills

See the sqlalchemy skill for model definitions
See the python skill for Python backend conventions
See the fastapi skill for API integration after migrations

---name: alembicdescription: Generates and manages database migrations with Alembic for the Bookkeep backend. Use when: creating database migrations, modifying models, adding columns, creating tables, or running schema changes.--- # Alembic Skill Alembic manages schema migrations for Bookkeep's SQLAlchemy models. Migrations live in `backend/alembic/versions/` with numeric prefixes (001, 002, etc.). The project supports both PostgreSQL (production) and SQLite (development) with idempotent migrations using existence checks. ## Quick Start ### Generate Migration ```bash cd backend alembic revision --autogenerate -m "add_column_to_table" ``` ### Apply Migrations ```bash cd backend alembic upgrade head # Apply all pending alembic upgrade +1 # Apply next migration only alembic downgrade -1 # Roll back one migration ``` ### Check Status ```bash cd backend alembic current # Show current revision alembic history # List all migrations ``` ## Key Concepts | Concept | Usage | Example | |---------|-------|---------| | Numeric prefix | Sequential ordering | `022_add_download_system.py` | | Idempotent checks | Safe reruns | `if not table_exists('download_tasks'):` | | batch_alter_table | SQLite compatibility | `with op.batch_alter_table('books'):` | | Data migrations | Transform existing data | `op.execute("UPDATE books SET ...")` | ## Project Configuration - **alembic.ini**: `backend/alembic.ini` - **env.py**: `backend/alembic/env.py` (loads `DATABASE_URL` from `app.database`) - **versions**: `backend/alembic/versions/` (30 migrations) - **Models**: `backend/app/models.py` ## Common Patterns ### Add Column with Default ```python if not column_exists('users', 'can_download'): op.add_column('users', sa.Column( 'can_download', sa.Boolean(), nullable=True, server_default='true' )) ``` ### Create Table with Indexes ```python if not table_exists('download_tasks'): op.create_table('download_tasks', sa.Column('id', sa.Integer(), primary_key=True), sa.Column('book_id', sa.Integer(), nullable=False), sa.ForeignKeyConstraint(['book_id'], ['books.id']), ) if not index_exists('download_tasks', 'ix_download_tasks_book_id'): op.create_index('ix_download_tasks_book_id', 'download_tasks', ['book_id']) ``` ## See Also - [patterns](references/patterns.md) - Migration patterns and helper functions - [workflows](references/workflows.md) - Common migration workflows ## Related Skills - See the **sqlalchemy** skill for model definitions - See the **python** skill for Python backend conventions - See the **fastapi** skill for API integration after migrations

Frequently asked questions