Database¶

Each environment gets an Aurora PostgreSQL Serverless v2 cluster with IAM authentication (no passwords). The database auto-pauses after 4 hours of inactivity to save costs. First connection after pause takes ~30 seconds to wake up.

Database Roles¶

Four roles are created automatically:

Role	Purpose
`inspect_admin`	Migrations (rds_superuser)
`inspect_app`	API read/write
`inspect_app_ro`	Read-only access
`middleman`	LLM proxy model config reads

Connecting¶

Connect via IAM auth token (no passwords):

ENDPOINT=$(pulumi stack output database_endpoint)
TOKEN=$(aws rds generate-db-auth-token \
  --hostname $ENDPOINT --port 5432 --region us-west-2 --username inspect_app)
PGPASSWORD="$TOKEN" psql "host=$ENDPOINT dbname=inspect user=inspect_app sslmode=require"

Running Migrations¶

Get the database URL from your infrastructure outputs:

export DATABASE_URL=$(pulumi stack output database_url_admin)

Run migrations:

cd hawk
alembic upgrade head

Creating a New Migration¶

After changing the SQLAlchemy models in hawk/core/db/models.py:

alembic revision --autogenerate -m "description of change"

Test it round-trips cleanly:

alembic upgrade head && alembic downgrade -1 && alembic upgrade head

Schema Conventions¶

All tables have a pk UUID primary key, and created_at/updated_at timestamps
All timestamps are timezone-aware and stored in UTC
Model names are singular