本文详解如何在 go 项目中正确安装并使用 pressly/goose 创建数据库迁移文件，涵盖命令行用法、常见错误排查及版本兼容性说明。
本文详解如何在 go 项目中正确安装并使用 pressly/goose 创建数据库迁移文件，涵盖命令行用法、常见错误排查及版本兼容性说明。
Goose 是一个轻量、易用的 Go 语言数据库迁移工具，广泛用于管理 SQL 迁移脚本的版本控制与执行。早期存在多个 fork（如 LiamStask/goose），但当前推荐使用官方维护的 Pressly/goose，它已修复旧版中 goose create 命令失效等问题，并支持 Go Modules、多数据库驱动及 CLI 增强功能。
✅ 正确安装与初始化
请避免使用已弃用的旧 fork（如 Bitbucket 上的 liamstask/goose）。应统一采用最新版 Pressly/goose：
# 推荐：使用 go install（Go 1.16+） go install github.com/pressly/goose/v4/cmd/goose@latest # 或（Go < 1.16）： go get -u github.com/pressly/goose/v4/cmd/goose
⚠️ 注意：v4 是当前稳定主版本，务必包含 /v4/ 路径；若省略，可能拉取不兼容的 v3 或旧分支。
✅ 创建迁移文件
确保当前目录下已存在 goose.yml（或 goose.conf）配置文件，或通过 -dir 和 -dbstring 显式指定路径与数据库连接串。最简方式如下：
# 在项目根目录执行（需有 goose.yml） goose create add_users_table sql # 输出示例： # goose: created db/migrations/20240520143218_add_users_table.sql
该命令会生成一对 .sql 文件（up/down），时间戳前缀确保顺序执行；也可指定 go 类型生成 Go 语言迁移：
goose create initialize_schema go
将生成 xxx_initialize_schema.go，内含 Up 和 Down 函数，适合复杂逻辑（如数据转换、条件判断等）。
? 关键注意事项
-
配置文件优先级：goose.yml > 环境变量 > CLI 参数。典型 goose.yml 示例：
# goose.yml dialect: postgres database: "user=dev dbname=test sslmode=disable" dir: ./migrations
- 路径问题：goose create 必须在包含配置文件或能被识别为 Go module 的项目根目录运行；否则提示“no migrations found”或命令无响应。
- 版本一致性：若仍遇到 command not found 或静默失败，请检查 $GOPATH/bin 是否在 PATH 中，或直接调用全路径（如 $(go env GOPATH)/bin/goose create ...）。
✅ 验证与后续步骤
创建后，可立即预览迁移内容，并用以下命令测试执行流程：
goose status # 查看迁移状态（pending/applied） goose up # 执行待迁移（up） goose down # 回滚最新一次（down）
总结：使用 Pressly/goose 创建迁移的核心在于——选用正确版本、配置有效路径、理解命令上下文。旧版兼容性问题已彻底解决，建议所有新项目统一迁移到 github.com/pressly/goose/v4 并遵循其文档实践。
