Barmaid

Visualize your Alembic migrations with style.

Features • Installation • Usage • License

Barmaid is a lightweight, zero-dependency CLI tool that instantly converts your Alembic migration history into clear, meaningful Mermaid flowcharts.

Database migrations can get messy. Branches, merges, and head entanglements are hard to track in your head. Barmaid helps you see the state of your database schema evolution at a glance.

✨ Features

• 🚀 Zero Dependencies: Built with pure Python standard library. No bloat, no conflicts.
• 🌳 Complex Topography: Flawlessly handles branches, merges, and multiple heads.
• 🕵️‍♀️ Health Checks: Automatically detects and visually highlights orphaned revisions (missing parents).
• 🎨 Highly Customizable:
  • Switch orientations (Top-Down, Left-to-Right, etc.).
  • Output to file or stdout.
• 📦 Drop-in Ready: Works with any standard Alembic folder structure automatically.

📦 Installation

Install directly from source:

pip install .

Note: Barmaid requires Python 3.10 or higher.

🚀 Usage

Navigate to your project directory and let Barmaid do the rest. It will automatically hunt for your versions directory.

# Generate diagram and print to stdout
barmaid

Common Commands

Save to a file:

barmaid -o schema_evolution.mmd

Change orientation (Left-to-Right):

# Great for long, linear histories
barmaid -d LR

Specify a custom versions directory:

barmaid ./src/alembic/versions

CLI Options

📊 Visualizing the Output

Barmaid outputs standard Mermaid syntax. You can view the diagrams in:

1. GitHub / GitLab: Paste the output into any Markdown file (like a PR description or Wiki).
2. Mermaid Live Editor: Copy-paste for an instant interactive preview.
3. VS Code: Use the Mermaid Preview extension.

Example Output

graph TD
    a1b2c3d4["init_schema<br/>Create user table"]
    e5f6g7h8["add_email_column<br/>Add email to users"]
    i9j0k1l2["create_posts<br/>Add posts table"]
    
    a1b2c3d4 --> e5f6g7h8
    e5f6g7h8 --> i9j0k1l2
    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px

🤝 Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue or submit a pull request.

📄 License

This project is licensed under the MIT License.