Alembic

1

Basic Alembic

Here is a step-by-step guide to using Alembic with SQLAlchemy for database migrations, using the same style of commands you mentioned:

---

1. Install Dependencies

First, install the required packages:

pip install sqlalchemy alembic

---

2. Create a Simple Project Structure

Organize your project like this:

my_project/
├── app/
│   ├── __init__.py
│   ├── models.py
├── alembic/   # Alembic directory (auto-created)
├── alembic.ini
├── manage.py

---

3. Initialize SQLAlchemy

app/__init__.py:

from sqlalchemy import create_engine
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

# Configure the database URL (SQLite for simplicity)
DATABASE_URL = "sqlite:///test.db"

engine = create_engine(DATABASE_URL, connect_args={"check_same_thread": False})
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

app/models.py:

from app import Base
from sqlalchemy import Column, Integer, String

class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True)
    email = Column(String, unique=True, index=True)

---

4. Initialize Alembic

Run the following command to initialize Alembic:

alembic init alembic

This creates:

• The alembic directory (migration scripts live here).

• The alembic.ini configuration file.

---

5. Configure Alembic

Open alembic.ini and set your database connection URL:

sqlalchemy.url = sqlite:///test.db

---

6. Set Up the Migration Environment

Modify the env.py file in the alembic directory to include your Base:

from app import Base

# Add this to the run_migrations_online function
from app import engine

target_metadata = Base.metadata

---

7. Run Commands

Use the manage.py script to run Alembic commands.

manage.py:

import os
from alembic.config import Config
from alembic import command

def init():
    """Initialize Alembic migration environment."""
    print("Alembic has already been initialized. Run 'alembic init' directly if needed.")

def migrate():
    """Generate a new migration."""
    alembic_cfg = Config("alembic.ini")
    command.revision(alembic_cfg, autogenerate=True, message="Initial migration")

def upgrade():
    """Apply migrations."""
    alembic_cfg = Config("alembic.ini")
    command.upgrade(alembic_cfg, "head")

def downgrade():
    """Revert migrations."""
    alembic_cfg = Config("alembic.ini")
    command.downgrade(alembic_cfg, "-1")

if __name__ == "__main__":
    import sys

    commands = {
        "db init": init,
        "db migrate": migrate,
        "db upgrade": upgrade,
        "db downgrade": downgrade,
    }

    if len(sys.argv) < 2:
        print("Usage: python manage.py <command>")
    elif sys.argv[1] in commands:
        commands[sys.argv[1]]()
    else:
        print(f"Unknown command: {sys.argv[1]}")

---

8. Generate and Apply Migrations

Run the following commands:

a. Autogenerate a Migration

python manage.py db migrate

b. Apply the Migration

python manage.py db upgrade

c. Revert a Migration (Optional)

python manage.py db downgrade

---

9. Verify Database Changes

Use a SQLite viewer or query the database to ensure the users table exists.

sqlite3 test.db
.tables
SELECT * FROM users;

---

Notes:

• Alembic automatically detects changes to the models when using autogenerate=True in env.py.

• You can manually edit migration files in the alembic/versions/ directory for complex schema updates.

This approach mirrors the workflow you described (db init, db migrate, db upgrade) using Alembic.

---

2

---

3

---

4

---

5

---

6

---

7

---

8

---

9

---

10

---

11

---

12

---

13

---

14

---

15

---

16

---

17

---

18

---

19

---

20

---

21

---

22

---

23

---

24

---

25

---