# Go Goose

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

- Skill: `diegosouzapw/go-goose` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/go-goose`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/go-goose/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/go-goose

---


# 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**:
   - **CLI** for ad-hoc runs or CI/CD.
   - **Library/Provider** when migrations are executed inside Go services or tests.
3. **Author migrations**:
   - SQL: use goose annotations and statement rules (see [references/sql-annotations.md](references/sql-annotations.md)).
   - Go: register migrations in init and wire into a custom binary or Provider (see [references/go-migrations.md](references/go-migrations.md)).
4. **Run migrations**:
   - CLI usage, commands, and env vars in [references/cli.md](references/cli.md).
   - Library/Provider patterns in [references/library.md](references/library.md).
5. **Versioning + ordering**:
   - Use hybrid versioning during development and `fix` for production sequencing if required (see [references/versioning.md](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](references/cli.md)
- SQL annotations and parsing rules: [references/sql-annotations.md](references/sql-annotations.md)
- Go migration registration patterns: [references/go-migrations.md](references/go-migrations.md)
- Library and Provider API usage: [references/library.md](references/library.md)
- Versioning and ordering: [references/versioning.md](references/versioning.md)