Metadata-Version: 2.4
Name: migrator-cli
Version: 0.1.0
Summary: Universal migration CLI for Python apps
Author: Peter Adelodun
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: alembic>=1.17.1
Requires-Dist: mako>=1.3.10
Requires-Dist: pydantic>=2.12.4
Requires-Dist: python-dotenv>=1.2.1
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=14.2.0
Requires-Dist: sqlalchemy>=2.0.44
Requires-Dist: typer>=0.20.0
Description-Content-Type: text/markdown

# 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 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
- **Pythonic CLI** — clean, readable, extensible commands

## 📦 Installation

### Quick Install (Recommended)

```bash
curl -sSL https://raw.githubusercontent.com/Adelodunpeter25/migrator/main/install.sh | bash
```

### Using pip

```bash
pip install git+https://github.com/Adelodunpeter25/migrator.git
```

### Using uv

```bash
uv add git+https://github.com/Adelodunpeter25/migrator.git
```

### Uninstall

```bash
curl -sSL https://raw.githubusercontent.com/Adelodunpeter25/migrator/main/uninstall.sh | bash
```

## 🚀 Quick Start

### 1. Set up your database URL

Create a `.env` file:

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

Or use `settings.py`, `config.py`, `config.yaml`, or `config.toml`.

### 2. Initialize migrations

```bash
migrator init
```

This creates:

```
migrations/
├── versions/
├── env.py
├── script.py.mako
└── alembic.ini
```

### 3. Create your first migration

```bash
migrator makemigrations "create user table"
```

### 4. Apply migrations

```bash
migrator migrate
```

## 📖 Commands

### `migrator init`

Initialize migration environment in your project.

```bash
migrator init
migrator init --dir custom_migrations
```

### `migrator makemigrations`

Create a new migration with auto-detection.

```bash
migrator makemigrations "add email to users"
migrator makemigrations "initial" --manual  # Create empty migration
```

### `migrator migrate`

Apply pending migrations.

```bash
migrator migrate
migrator migrate --revision abc123  # Migrate to specific revision
```

### `migrator downgrade`

Rollback migrations.

```bash
migrator downgrade  # Rollback one migration
migrator downgrade --revision abc123  # Rollback to specific revision
migrator downgrade --revision base  # Rollback all migrations
```

### `migrator history`

Show migration history.

```bash
migrator history
```

### `migrator current`

Show current database revision.

```bash
migrator current
```

## ⚙️ Configuration

Migrator automatically detects your database URL from multiple sources (in order):

1. `.env` file (`DATABASE_URL` or `SQLALCHEMY_DATABASE_URI`)
2. Environment variables
3. `settings.py` or `config.py`
4. `config.yaml` or `config.toml`

### Example configurations

**.env**
```bash
DATABASE_URL=postgresql://user:password@localhost:5432/dbname
```

**settings.py**
```python
DATABASE_URL = "postgresql://user:password@localhost:5432/dbname"
```

**config.yaml**
```yaml
database:
  url: postgresql://user:password@localhost:5432/dbname
```

**config.toml**
```toml
[database]
url = "postgresql://user:password@localhost:5432/dbname"
```

## 🔧 How It Works

### Auto-Detection

Migrator automatically finds your SQLAlchemy Base class by:

1. Checking common import paths (`app.models`, `models`, `database`, etc.)
2. Scanning your project files for declarative base classes
3. Injecting the correct import into Alembic's `env.py`

### Alembic Integration

Migrator wraps Alembic's powerful migration engine with a simpler interface:

- Uses `alembic.command` API internally
- Customizes templates for auto-import
- Provides Django-style command names
- Adds beautiful terminal output

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.