Back to Details

go-goose

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

go-goose

go-goose

Expert guidance for using pressly/goose to create and run database migrations via the CLI or Go library.
通过CLI或Go库使用pressly/goose创建和运行数据库迁移的专业指南。

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.
  • 用户提及goose、pressly/goose、Go语言数据库迁移，或询问如何运行SQL/Go迁移时。
  • 任务涉及嵌入式迁移、Provider API使用，或结合goose的CI工作流时。

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).
  • 优先遵循仓库现有的迁移布局、数据库方言和命名规范。
  • 确保数据库驱动与goose方言匹配（例如：
    postgres
    驱动搭配
    postgres
    方言）。
  • 架构变更优先使用SQL迁移；复杂数据回填或代码驱动的步骤使用Go迁移。
  • 确保迁移在goose规则内具有确定性和幂等性（一个Up方法，可选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).
    • Go: register migrations in init and wire into a custom binary or Provider (see references/go-migrations.md).
  4. Run migrations:
    • CLI usage, commands, and env vars in references/cli.md.
    • Library/Provider patterns in references/library.md.
  5. Versioning + ordering:
    • Use hybrid versioning during development and 
      fix
      for production sequencing if required (see references/versioning.md).
  1. 明确上下文：目标数据库/方言、驱动、迁移目录、SQL与Go迁移的需求，以及所需命令（创建/升级/回滚/状态等）。
  2. 选择交互方式：
    • CLI：用于临时运行或CI/CD流程。
    • 库/Provider：当迁移在Go服务或测试内部执行时使用。
  3. 编写迁移：
    • SQL迁移：使用goose注解和语句规则（参考references/sql-annotations.md）。
    • Go迁移：在init函数中注册迁移，并集成到自定义二进制文件或Provider中（参考references/go-migrations.md）。
  4. 运行迁移：
    • CLI用法、命令和环境变量参考references/cli.md。
    • 库/Provider模式参考references/library.md。
  5. 版本控制与排序：
    • 开发阶段使用混合版本控制；若生产环境需要排序，使用
      fix
      标记（参考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.
  • 提供与用户方言和环境匹配的精确命令或代码片段。
  • 当需要回滚时，提醒用户缺失Down迁移的问题。
  • 如果迁移需要特殊解析或非事务执行，需明确指出。

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
  • CLI用法与环境变量：references/cli.md
  • SQL注解与解析规则：references/sql-annotations.md
  • Go迁移注册模式：references/go-migrations.md
  • 库与Provider API使用：references/library.md
  • 版本控制与排序：references/versioning.md