# Alembic Database Migrations
This directory contains Alembic migrations for the Trackly backend database.
## Prerequisites
- PostgreSQL database running and accessible
- Environment variables configured in `.env.development` or `.env.production`
## First Time Setup
If your database already has tables created (e.g., from `metadata.create_all()`), you need to tell Alembic that your database is already at the latest migration version:
```bash
uv run alembic stamp head
```
Or using the helper script:
```bash
python migrate.py stamp head
```
This marks the database as being at the current migration state without actually running the migrations.
## Common Commands
### Run migrations (apply all pending migrations):
```bash
uv run alembic upgrade head
# or
python migrate.py upgrade
```
### Mark database at current version (without running migrations):
```bash
uv run alembic stamp head
# or
python migrate.py stamp
```
### Revert last migration:
```bash
uv run alembic downgrade -1
# or
python migrate.py downgrade
```
### Create a new migration (auto-generate from models):
```bash
uv run alembic revision --autogenerate -m "description of changes"
```
### Create a new empty migration:
```bash
uv run alembic revision -m "description of changes"
```
### Show current migration version:
```bash
uv run alembic current
# or
python migrate.py current
```
### Show migration history:
```bash
uv run alembic history
# or
python migrate.py history
```
### Downgrade to a specific revision:
```bash
uv run alembic downgrade <revision_id>
```
### Upgrade to a specific revision:
```bash
uv run alembic upgrade <revision_id>
```
## Configuration
- **alembic.ini**: Main configuration file
- **env.py**: Migration environment configuration with async support
- **versions/**: Directory containing migration files
## Async Support
This project uses SQLAlchemy async connections (asyncpg driver for PostgreSQL).
The migrations are configured to work with async engines automatically.
## Troubleshooting
### "relation already exists" error
This happens when tables already exist in the database. Use `alembic stamp head` to mark the database at the current version without running migrations.
### "No module named app"
Make sure you're running alembic from the backend directory and using `uv run alembic` to ensure the correct Python environment is used.