name	postgres-migrations
description	This skill should be used when adding a database migration, or when asked "add a column/table", "why isn't the schema updated", "how do I run migrations here". Documents that migrations are a fully separate binary from the API server and are never run automatically.

Postgres migrations (goose)

Migrations live in api/internal/storage/postgres/migrations/ and run through a separate binary, cmd/migrate, built on pressly/goose — bridged from the app's pgxpool.Pool to goose's required *sql.DB via stdlib.OpenDBFromPool.

`cmd/server` never touches migrations

Starting the API (go run ./cmd/server) does not run pending migrations. A fresh database will produce query errors until migrations are applied separately:

make migrate-up

Other targets: make migrate-down, make migrate-status, make migrate CMD=<goose-command> for anything not covered by the named targets.

Adding a migration

New .sql files go under api/internal/storage/postgres/migrations/, following goose's naming/format conventions already used by the existing 7 migrations there. After adding one, run make migrate-up locally (see the run skill for full local-setup order) and verify it applies cleanly before considering the change done — the verify skill's "drive the actual flow" step applies here too.

name	postgres-migrations
description	This skill should be used when adding a database migration, or when asked "add a column/table", "why isn't the schema updated", "how do I run migrations here". Documents that migrations are a fully separate binary from the API server and are never run automatically.