Golang数据库迁移管理工具插件Goose的使用

Goose是一个数据库迁移工具，既可以作为CLI使用，也可以作为库集成到Go应用中。

安装

go install github.com/pressly/goose/v3/cmd/goose@latest

对于macOS用户，也可以通过Homebrew安装：

brew install goose

基本使用

创建迁移文件

# 创建SQL迁移文件
$ goose create add_some_column sql
$ Created new file: 20170506082420_add_some_column.sql

# 使用顺序编号创建迁移文件
$ goose -s create add_some_column sql
$ Created new file: 00001_add_some_column.sql

# 创建Go迁移文件
$ goose create fetch_user_data go
$ Created new file: 20170506082421_fetch_user_data.go

应用迁移

# 应用所有可用迁移
$ goose up
$ OK    001_basics.sql
$ OK    002_next.sql
$ OK    003_and_again.go

# 迁移到特定版本
$ goose up-to 20170506082420
$ OK    20170506082420_create_table.sql

# 应用单个迁移
$ goose up-by-one
$ OK    20170614145246_change_type.sql

回滚迁移

# 回滚单个迁移
$ goose down
$ OK    003_and_again.go

# 回滚到特定版本
$ goose down-to 20170506082527
$ OK    20170506082527_alter_column.sql

# 回滚所有迁移(谨慎使用)
$ goose down-to 0

查看状态

$ goose status
$   Applied At                  Migration
$   =======================================
$   Sun Jan  6 11:25:03 2013 -- 001_basics.sql
$   Sun Jan  6 11:25:03 2013 -- 002_next.sql
$   Pending                  -- 003_and_again.go

查看当前版本

$ goose version
$ goose: version 002

环境变量配置

可以通过环境变量配置Goose：

export GOOSE_DRIVER=DRIVER
export GOOSE_DBSTRING=DBSTRING
export GOOSE_MIGRATION_DIR=MIGRATION_DIR
export GOOSE_TABLE=TABLENAME

或者使用.env文件：

GOOSE_DRIVER=postgres
GOOSE_DBSTRING=postgres://admin:admin@localhost:5432/admin_db
GOOSE_MIGRATION_DIR=./migrations
GOOSE_TABLE=custom.goose_migrations

迁移文件类型

SQL迁移

SQL迁移文件示例：

-- +goose Up
CREATE TABLE post (
    id int NOT NULL,
    title text,
    body text,
    PRIMARY KEY(id)
);

-- +goose Down
DROP TABLE post;

Go迁移

Go迁移文件示例：

package migrations

import (
	"database/sql"

	"github.com/pressly/goose/v3"
)

func init() {
	goose.AddMigration(Up, Down)
}

func Up(tx *sql.Tx) error {
	_, err := tx.Exec("UPDATE users SET username='admin' WHERE username='root';")
	if err != nil {
		return err
	}
	return nil
}

func Down(tx *sql.Tx) error {
	_, err := tx.Exec("UPDATE users SET username='root' WHERE username='admin';")
	if err != nil {
		return err
	}
	return nil
}

嵌入式SQL迁移

使用Go 1.16+的embed功能：

package main

import (
    "database/sql"
    "embed"

    "github.com/pressly/goose/v3"
)

//go:embed migrations/*.sql
var embedMigrations embed.FS

func main() {
    var db *sql.DB
    // 设置数据库连接

    goose.SetBaseFS(embedMigrations)

    if err := goose.SetDialect("postgres"); err != nil {
        panic(err)
    }

    if err := goose.Up(db, "migrations"); err != nil {
        panic(err)
    }

    // 运行应用
}

完整示例

1. 初始化项目

mkdir myproject
cd myproject
go mod init myproject
go get github.com/pressly/goose/v3

2. 创建迁移目录和文件

mkdir -p migrations
goose create init sql

编辑生成的迁移文件(migrations/xxxx_init.sql):

-- +goose Up
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    username VARCHAR(255) NOT NULL UNIQUE,
    email VARCHAR(255),
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- +goose Down
DROP TABLE users;

3. 创建main.go

package main

import (
	"database/sql"
	"log"

	_ "github.com/lib/pq"
	"github.com/pressly/goose/v3"
)

func main() {
	// 设置数据库连接
	db, err := sql.Open("postgres", "user=postgres dbname=postgres sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	defer db.Close()

	// 运行迁移
	if err := goose.SetDialect("postgres"); err != nil {
		log.Fatal(err)
	}

	if err := goose.Up(db, "migrations"); err != nil {
		log.Fatal(err)
	}

	log.Println("Migrations applied successfully!")
}

4. 运行迁移

go run main.go

注意事项

1. 对于MySQL，需要在连接字符串中添加parseTime=true和multiStatements=true参数
2. 迁移文件必须以数字开头，后跟下划线
3. Go迁移文件不能以*_test.go结尾
4. 建议采用混合版本控制策略，开发时使用时间戳，生产环境使用顺序编号

Goose支持多种数据库，包括Postgres、MySQL、SQLite、MSSQL等，是一个功能强大且灵活的数据库迁移工具。