124 lines
3.4 KiB
Markdown
124 lines
3.4 KiB
Markdown
# 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
|