name: go-goose
description: Use this skill to plan, write, or run database migrations with the pressly/goose CLI and Go library (SQL/Go migrations, env vars, provider API, embedded migrations).
metadata:
short-description: Expert guidance for goose CLI and Go library migrations.

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.

Core rules

• 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).

Workflow

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

Output expectations

• 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.

References

• CLI usage and env vars: references/cli.md
• SQL annotations and parsing rules: references/sql-annotations.md
• Go migration registration patterns: references/go-migrations.md
• Library and Provider API usage: references/library.md
• Versioning and ordering: references/versioning.md