Install Alembic in Python Step by Step

Alembic is a lightweight database migration tool for SQLAlchemy. It helps manage database schema changes. This guide will walk you through installing and setting it up.

Prerequisites

Before installing Alembic, ensure you have Python and pip installed. You also need SQLAlchemy for database operations.

Check Python version:

python --version

Python 3.8.5

Step 1: Install Alembic

Use pip to install Alembic. Run this command in your terminal:

pip install alembic

If you encounter a ModuleNotFoundError, check our guide on solving Python module errors.

Step 2: Initialize Alembic

Navigate to your project directory and run:

alembic init alembic

This creates an alembic folder with configuration files.

Step 3: Configure Alembic

Edit alembic.ini to set your database URL:

 
sqlalchemy.url = driver://user:pass@localhost/dbname

Update env.py to import your models:

 
from myapp.models import Base
target_metadata = Base.metadata

Step 4: Create Your First Migration

Generate an initial migration with:

alembic revision -m "create users table"

Edit the generated migration file in alembic/versions/.

Step 5: Run the Migration

Apply your migration to the database:

alembic upgrade head

This executes all pending migrations.

Example Migration File

Here's a sample migration that creates a users table:

 
def upgrade():
    op.create_table(
        'users',
        Column('id', Integer, primary_key=True),
        Column('name', String(50)),
        Column('email', String(100), unique=True)
    )

def downgrade():
    op.drop_table('users')

Common Commands

Important Alembic commands to remember:

• alembic current - Shows current revision
• alembic history - Shows migration history
• alembic downgrade -1 - Reverts last migration

Troubleshooting

If you get connection errors, double-check your alembic.ini settings. For other issues, the ModuleNotFoundError guide might help.

Conclusion

Alembic simplifies database migrations in Python projects. Follow these steps to install and configure it properly. Always test migrations in a development environment first.

Remember to commit your migration files to version control. This ensures all team members apply the same schema changes.