Migrator

The Universal Migration CLI for Python Apps

A lightweight, framework-agnostic database migration tool for Python projects using SQLAlchemy. Migrator automates what Alembic requires developers to set up manually — making migrations as simple as Django's makemigrations and migrate, but flexible enough for Python any project.

✨ Features

• Zero boilerplate — one command to init and start migrating
• Auto-detect models — finds SQLAlchemy Base classes automatically
• Smart config — no need to manually edit alembic.ini or env.py
• Framework agnostic — works with FastAPI, Flask, or standalone SQLAlchemy

📦 Installation

# SQLite / no extras needed
uv add migrator-cli

# PostgreSQL
uv add migrator-cli[postgres]

# MySQL
uv add migrator-cli[mysql]

# All database drivers
uv add migrator-cli[all]

Requires Python 3.11+.

🚀 Quick Start

Note: If you have an existing database with tables, see MIGRATION_GUIDE.md first.

1. Set up your database URL

Create a .env file:

DATABASE_URL=postgresql://user:password@localhost:5432/dbname

2. Initialize migrations

migrator init

3. Create your first migration

migrator makemigrations "create user table"

4. Apply migrations

migrator migrate

📖 Commands

# Initialize migration environment
migrator init

# Create new migration
migrator makemigrations "add email to users"

# Create migration and show SQL
migrator makemigrations "add email to users" --show-sql

# Apply migrations
migrator migrate

# Apply migrations without confirmation
migrator migrate --yes

# Preview migration SQL without applying
migrator migrate --dry-run

# Rollback migrations
migrator downgrade

# Show migration history
migrator history

# Show current revision
migrator current

# Mark database as migrated (for existing databases)
migrator stamp head

# Show migration status
migrator status

🏗️ Advanced Usage

Nested Project Structures

migrator init --base app.core.database:Base
migrator makemigrations "initial" --base app.core.database:Base

Async SQLAlchemy

# Your .env
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db
# Migrator auto-converts to: postgresql://user:pass@localhost/db

Custom Config

migrator init --config backend/settings.py

Verbose Mode

migrator init --verbose

🔧 Troubleshooting

Base not found? Use --base flag:

migrator init --base app.core.database:Base

Existing database? Use stamp:

migrator stamp head

🤝 Contributing

Contributions welcome! Submit a Pull Request.

📄 License

MIT License - see LICENSE file.