Merge pull request #39 from borhanst/alembic-migration

Alembic migration

Author: borhanst

docs/guide/alembic-setup.md

@@ -1,60 +1,95 @@
 # Alembic Setup
 
-FastAPI Admin Kit does not bundle Alembic. This guide shows how to set up Alembic in your project to manage database migrations for both your models and the admin tables.
+FastAPI Admin Kit provides built-in models for authentication (users, roles, permissions) and audit logging. This guide shows how to set up Alembic to manage database migrations for both admin tables and your application models.
 
-## Install Alembic
+## Quick Start with `fak init-alembic`
+
+The easiest way to get started is using the built-in CLI command:
 
 ```bash
-pip install alembic
+# For a new project
+fak init-alembic --app myapp:app --auto-migrate
+
+# For an existing database (baseline migration)
+fak init-alembic --app myapp:app --baseline
 ```
 
-## Initialize Alembic
+This command:
+1. Creates `alembic.ini` with proper configuration
+2. Creates `alembic/env.py` that imports admin models from `fastapi_admin_kit.migrations.models`
+3. Creates `alembic/script.py.mako` template
+4. Optionally auto-generates the initial migration (`--auto-migrate`)
+5. Optionally creates a baseline migration for existing databases (`--baseline`)
+
+### What `init-alembic` Does
 
-```bash
-alembic init alembic
+```
+myproject/
+├── alembic.ini          # Alembic configuration
+├── alembic/
+│   ├── env.py           # Migration environment (imports admin models)
+│   ├── script.py.mako   # Migration template
+│   └── versions/        # Migration scripts
 ```
 
-## Configure `alembic.ini`
+The generated `alembic/env.py` includes:
 
-Set the database URL:
+```python
+# Import admin models (materialized from schemas)
+from fastapi_admin_kit.migrations.models import Base as AdminBase
 
-```ini
-[alembic]
-script_location = alembic
-sqlalchemy.url = sqlite+aiosqlite:///./your_database.db
+# Import your app models
+# from myapp.models import Base as AppBase
+
+# Combine metadata for autogenerate
+target_metadata = [AdminBase.metadata]
+# target_metadata.append(AppBase.metadata)  # Add your models
 ```
 
-For PostgreSQL:
+## Manual Alembic Setup
 
-```ini
-sqlalchemy.url = postgresql+asyncpg://user:password@localhost:5432/your_database
+If you prefer manual setup or have an existing Alembic configuration:
+
+### 1. Install Alembic
+
+```bash
+pip install alembic
+```
+
+### 2. Initialize Alembic
+
+```bash
+alembic init alembic
 ```
 
-## Configure `alembic/env.py`
+### 3. Configure `alembic/env.py`
 
 Replace the contents of `alembic/env.py`:
 
 ```python
 import asyncio
 import sys
-from pathlib import Path
 from logging.config import fileConfig
+from pathlib import Path
 
 from sqlalchemy import pool
 from sqlalchemy.engine import Connection
 from sqlalchemy.ext.asyncio import async_engine_from_config
 
 from alembic import context
 
+# Add project root to path
 sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
 
-from models import Base as UserBase
-from fastapi_admin_kit.models.base import Base as AdminBase
+# Import admin models (materialized from schemas)
+from fastapi_admin_kit.migrations.models import Base as AdminBase
 
-target_metadata = UserBase.metadata
-for table in AdminBase.metadata.tables.values():
-    if table.name not in target_metadata.tables:
-        target_metadata._add_table(table.name, table.schema, table)
+# Import your application models
+# from myapp.models import Base as AppBase
+
+# Combine metadata for autogenerate
+target_metadata = [AdminBase.metadata]
+# target_metadata.append(AppBase.metadata)  # Add your models
 
 config = context.config
 
@@ -101,63 +136,174 @@ else:
     run_migrations_online()
 ```
 
-Adjust the import to match your project:
+### 4. Configure Database URL
 
-```python
-# If models are in app/models.py
-from app.models import Base as UserBase
+Edit `alembic.ini`:
 
-# If models are in src/models/__init__.py
-from src.models import Base as UserBase
+```ini
+[alembic]
+script_location = alembic
+sqlalchemy.url = sqlite+aiosqlite:///./your_database.db
+# For PostgreSQL:
+# sqlalchemy.url = postgresql+asyncpg://user:pass@localhost:5432/dbname
 ```
 
-## Generate Initial Migration
+### 5. Generate Initial Migration
 
 ```bash
-alembic revision --autogenerate -m "initial schema"
+alembic revision --autogenerate -m "init admin models"
 ```
 
-## Apply Migration
+### 6. Apply Migrations
 
 ```bash
 alembic upgrade head
 ```
 
-## Sync Engine
+## Production vs Development Mode
+
+FastAPI Admin Kit supports two modes:
+
+| Mode | Setting | Behavior |
+|------|---------|----------|
+| **Development** (default) | `use_alembic=False` | Uses `create_all()` + auto-migration (adds missing columns) |
+| **Production** | `use_alembic=True` | Expects Alembic to manage schema; skips `create_all()` |
 
-For synchronous engines, replace `run_migrations_online`:
+### In Your Application
 
 ```python
-from sqlalchemy import engine_from_config
+from fastapi_admin_kit import Admin
+from fastapi_admin_kit.config import BehaviorConfig
+
+admin = Admin(
+    app=app,
+    engine=engine,
+    # ... other config ...
+    behavior=BehaviorConfig(use_alembic=True),  # Production mode
+)
+```
 
-def run_migrations_online() -> None:
-    connectable = engine_from_config(
-        config.get_section(config.config_ini_section, {}),
-        prefix="sqlalchemy.",
-        poolclass=pool.NullPool,
-    )
-    with connectable.connect() as connection:
-        context.configure(connection=connection, target_metadata=target_metadata)
-        with context.begin_transaction():
-            context.run_migrations()
+### In Lifespan (Production)
+
+```python
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Run alembic upgrade head on startup
+    from alembic.config import Config
+    from alembic import command
+
+    alembic_cfg = Config("alembic.ini")
+    command.upgrade(alembic_cfg, "head")
+
+    await admin.setup(app)
+    yield
 ```
 
-## Existing Tables
+## CLI Commands
 
-If tables were created with `create_all()` before Alembic:
+### Initialize Alembic
 
 ```bash
+# New project with auto-generated initial migration
+fak init-alembic --app myapp:app --auto-migrate
+
+# Existing project with database (creates baseline)
+fak init-alembic --app myapp:app --baseline
+
+# Force overwrite existing alembic config
+fak init-alembic --app myapp:app --force
+```
+
+### Run Migrations (Production)
+
+```bash
+# Run all pending migrations (equivalent to alembic upgrade head)
+fak migrate-alembic
+
+# Run to specific revision
+fak migrate-alembic <revision>
+
+# Use custom app path to find alembic.ini
+fak migrate-alembic --app myapp:app
+```
+
+### Dev Mode Migrations (Legacy)
+
+```bash
+# Add missing columns / recreate tables (dev only)
+fak migrate User Product
+
+# Convert old permissions format
+fak migrate-permissions
+```
+
+## Existing Database Migration (Baseline)
+
+If you have an existing database created with `create_all()`:
+
+```bash
+# Create baseline migration and stamp as applied
+fak init-alembic --app myapp:app --baseline
+
+# Or manually:
+alembic revision -m "baseline_existing_schema"
+# Edit the migration to match your current schema
 alembic stamp head
 ```
 
-## Verify Admin Tables
+## Adding Your Models to Migrations
+
+In `alembic/env.py`, add your application's metadata:
 
 ```python
-from fastapi_admin_kit.models.base import Base as AdminBase
-print(list(AdminBase.metadata.tables.keys()))
+from fastapi_admin_kit.migrations.models import Base as AdminBase
+from myapp.models import Base as AppBase  # Your models
+
+target_metadata = [AdminBase.metadata, AppBase.metadata]
 ```
 
+Then autogenerate will include both admin and app tables:
+
+```bash
+alembic revision --autogenerate -m "add product table"
+```
+
+## Junction Tables
+
+The admin models include two junction tables for many-to-many relationships:
+- `admin_user_roles` — User ↔ Role
+- `admin_role_permissions` — Role ↔ Permission
+
+These are automatically created via SQLAlchemy relationships and included in migrations.
+
+## Troubleshooting
+
+### "Table already exists" on initial migration
+
+If tables were created via `create_all()` before Alembic:
+
+```bash
+# Option 1: Baseline (recommended)
+fak init-alembic --baseline
+
+# Option 2: Stamp head manually
+alembic stamp head
+```
+
+### Import errors in `env.py`
+
+Ensure your project root is in `sys.path`:
+
+```python
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+```
+
+### Async engine issues
+
+The generated `env.py` uses `async_engine_from_config` for async migrations. For sync engines, use the sync variant in the template.
+
 ## Next Steps
 
-- [Model Registration](model-registration.md)
-- [Authentication & RBAC](auth-rbac.md)
+- [Model Registration](../guide/model-registration.md) — Register your models with the admin
+- [Authentication & RBAC](../guide/auth-rbac.md) — Set up roles and permissions
+- [Existing Alembic Integration](./existing-alembic-integration.md) — Integrate with existing Alembic setup

docs/guide/cli.md

@@ -110,7 +110,7 @@ fak deletepermissions User Product
 
 ### migrate
 
-Add missing columns or drop obsolete columns from tables:
+Add missing columns or drop obsolete columns from tables (dev mode only):
 
 ```bash
 fak migrate User Product
@@ -122,6 +122,52 @@ fak-admin migrate User Product
 | `tables` | Class or table names (required) |
 | `-d, --database-url` | Database URL |
 
+### migrate-alembic
+
+Run Alembic migrations (production mode):
+
+```bash
+# Run all pending migrations (equivalent to alembic upgrade head)
+fak migrate-alembic
+
+# Run to specific revision
+fak migrate-alembic <revision>
+
+# Use custom app path to find alembic.ini
+fak migrate-alembic --app myapp:app
+```
+
+| Option | Description |
+|--------|-------------|
+| `revision` | Target revision (default: `head`) |
+| `-a, --app` | App module path (e.g., `myapp:app`) to locate alembic.ini |
+
+### init-alembic
+
+Initialize Alembic configuration for migrations:
+
+```bash
+# New project with auto-generated initial migration
+fak init-alembic --app myapp:app --auto-migrate
+
+# Existing project with database (creates baseline migration)
+fak init-alembic --app myapp:app --baseline
+
+# Force overwrite existing alembic config
+fak init-alembic --app myapp:app --force
+
+# Custom database URL
+fak init-alembic --app myapp:app -d "postgresql+asyncpg://user:pass@localhost/db"
+```
+
+| Option | Description |
+|--------|-------------|
+| `-a, --app` | App module path (e.g., `myapp:app`) to locate project root |
+| `-d, --database-url` | Database URL to write to alembic.ini |
+| `--auto-migrate` | Auto-generate initial migration for admin models |
+| `--baseline` | Create baseline migration for existing database (stamps head) |
+| `--force` | Overwrite existing alembic.ini and alembic/ directory |
+
 ### migrate-permissions
 
 Convert old shared permissions to per-role format: