alpinebits_python/alembic

Database Migrations

This directory contains Alembic database migrations for the Alpine Bits Python Server.

Quick Reference

Common Commands

# Check current migration status
uv run alembic current

# Show migration history
uv run alembic history --verbose

# Upgrade to latest migration
uv run alembic upgrade head

# Downgrade one version
uv run alembic downgrade -1

# Create a new migration (auto-generate from model changes)
uv run alembic revision --autogenerate -m "description"

# Create a new empty migration (manual)
uv run alembic revision -m "description"

Migration Files

Current Migrations

1. 535b70e85b64_initial_schema.py - Creates all base tables
2. 8edfc81558db_drop_and_recreate_conversions_tables.py - Handles conversions table schema change

How Migrations Work

1. Alembic tracks which migrations have been applied using the alembic_version table
2. When you run alembic upgrade head, it applies all pending migrations in order
3. Each migration has an upgrade() and downgrade() function
4. Migrations are applied transactionally (all or nothing)

Configuration

The Alembic environment (env.py) is configured to:

• Read database URL from config.yaml or environment variables
• Support PostgreSQL schemas
• Use async SQLAlchemy (compatible with FastAPI)
• Apply migrations in the correct schema

Best Practices

1. Always review auto-generated migrations - Alembic's autogenerate is smart but not perfect
2. Test migrations on dev first - Never run untested migrations on production
3. Keep migrations small - One logical change per migration
4. Never edit applied migrations - Create a new migration to fix issues
5. Commit migrations to git - Migrations are part of your code

Creating a New Migration

When you modify models in src/alpine_bits_python/db.py:

# 1. Generate the migration
uv run alembic revision --autogenerate -m "add_user_preferences_table"

# 2. Review the generated file in alembic/versions/
# Look for:
# - Incorrect type changes
# - Missing indexes
# - Data that needs to be migrated

# 3. Test it
uv run alembic upgrade head

# 4. If there are issues, downgrade and fix:
uv run alembic downgrade -1
# Edit the migration file
uv run alembic upgrade head

# 5. Commit the migration file to git
git add alembic/versions/2025_*.py
git commit -m "Add user preferences table migration"

Troubleshooting

"FAILED: Target database is not up to date"

This means pending migrations need to be applied:

uv run alembic upgrade head

"Can't locate revision identified by 'xxxxx'"

The alembic_version table may be out of sync. Check what's in the database:

# Connect to your database and run:
SELECT * FROM alembic_version;

Migration conflicts after git merge

If two branches created migrations at the same time:

# Create a merge migration
uv run alembic merge heads -m "merge branches"

Need to reset migrations (DANGEROUS - ONLY FOR DEV)

# WARNING: This will delete all data!
uv run alembic downgrade base  # Removes all tables
uv run alembic upgrade head     # Recreates everything

More Information

• Alembic Documentation
• Alembic Tutorial
• See ../MIGRATION_REFACTORING.md for details on how this project uses Alembic