# migrations/ — Alembic Schema Management

See @../../CLAUDE.md for project-wide patterns.

## What This Is
Database schema versioning via Alembic against PostgreSQL. Migrations run automatically on startup via `init_db()` in `db.py`.

## Current Migration Chain
```
pg_initial_schema_0001 (fresh PostgreSQL schema — all tables)
```

## Adding a New Migration
```bash
cd /path/to/peon-mcp
uv run alembic revision -m "description_of_change"
```
Then edit the generated file in `versions/`. Set `revision` and `down_revision` to chain correctly.

## Key Patterns
- All CREATE TABLE use `IF NOT EXISTS` — safe to run on partial state
- `init_db()` in db.py runs Alembic `upgrade head` with a SQLAlchemy sync connection (`postgresql+psycopg://`)
- The asyncpg pool uses `postgresql://` or `postgres://` URLs
- `sqlalchemy.url` is set at runtime by `init_db()`, not in alembic.ini

## Gotchas
- **PostgreSQL types**: Use `SERIAL`/`GENERATED ALWAYS AS IDENTITY`, `TIMESTAMPTZ`, `BOOLEAN`, `DOUBLE PRECISION`
- **Some migrations have no downgrade()** — irreversible schema changes (table drops)
- When adding columns: add to BOTH the migration file AND update the initial schema for documentation
- Test migrations against a fresh DB AND an existing DB with data
