go-goose

Expert guidance for using pressly/goose to create and run database migrations via the CLI or Go library.

When to trigger

The user mentions goose, pressly/goose, database migrations in Go, or asks how to run SQL/Go migrations.
The task involves embedding migrations, provider API usage, or CI workflows with goose.

Follow the repository's existing migration layout, dialect, and naming conventions first.
Ensure the database driver and goose dialect match (e.g., postgres driver with postgres dialect).
Prefer SQL migrations for schema changes; use Go migrations for complex data backfills or code-driven steps.
Keep migrations deterministic and idempotent within goose's rules (one Up, optional Down).

Clarify context: target DB/dialect, driver, migration directory, SQL vs Go migration needs, and desired command (create/up/down/status/etc).
Choose interface:
- CLI for ad-hoc runs or CI/CD.
- Library/Provider when migrations are executed inside Go services or tests.
Author migrations:
- SQL: use goose annotations and statement rules (see references/sql-annotations.md).
- Go: register migrations in init and wire into a custom binary or Provider (see references/go-migrations.md).
Run migrations:
- CLI usage, commands, and env vars in references/cli.md.
- Library/Provider patterns in references/library.md.
Versioning + ordering:
- Use hybrid versioning during development and fix for production sequencing if required (see references/versioning.md).

Provide exact commands or code snippets that match the user's dialect and environment.
Warn about missing Down migrations when rollbacks are required.
If a migration requires special parsing or non-transactional execution, call it out explicitly.