Alembic experiments

alembic/README.md

@@ -0,0 +1,123 @@
+# 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