# Database Migrations

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

## Quick Reference

### Common Commands

```bash
# 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](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`:

```bash
# 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:
```bash
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:
```bash
# Connect to your database and run:
SELECT * FROM alembic_version;
```

### Migration conflicts after git merge

If two branches created migrations at the same time:
```bash
# Create a merge migration
uv run alembic merge heads -m "merge branches"
```

### Need to reset migrations (DANGEROUS - ONLY FOR DEV)

```bash
# 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](https://alembic.sqlalchemy.org/)
- [Alembic Tutorial](https://alembic.sqlalchemy.org/en/latest/tutorial.html)
- See [../MIGRATION_REFACTORING.md](../MIGRATION_REFACTORING.md) for details on how this project uses Alembic