使用go-pg-migrations实现PostgreSQL数据库迁移管理

go-pg-migrations是一个基于go-pg库的PostgreSQL数据库迁移管理工具，它可以帮助你轻松管理数据库schema的版本变更。下面我将详细介绍如何使用这个库。

安装

首先安装go-pg-migrations和依赖的go-pg库：

go get github.com/go-pg/migrations/v8
go get github.com/go-pg/pg/v10

基本用法

1. 创建迁移文件

迁移文件需要放在特定目录下，通常命名为migrations。每个迁移文件命名格式为：[版本号]_[描述].up.sql和[版本号]_[描述].down.sql。

例如：

• migrations/001_init.up.sql - 初始化数据库
• migrations/001_init.down.sql - 回滚初始化

2. 初始化迁移器

package main

import (
	"log"
	"os"

	"github.com/go-pg/migrations/v8"
	"github.com/go-pg/pg/v10"
)

func main() {
	db := pg.Connect(&pg.Options{
		Addr:     "localhost:5432",
		User:     "postgres",
		Password: "password",
		Database: "mydb",
	})
	defer db.Close()

	// 创建迁移器
	migrator := migrations.NewCollector()

	// 从文件系统加载迁移
	err := migrator.DiscoverSQLMigrations("migrations")
	if err != nil {
		log.Fatal(err)
	}

	// 运行迁移命令
	oldVersion, newVersion, err := migrator.Run(db, os.Args[1:]...)
	if err != nil {
		log.Fatal(err)
	}

	if newVersion != oldVersion {
		log.Printf("migrated from version %d to %d\n", oldVersion, newVersion)
	} else {
		log.Printf("version is %d\n", oldVersion)
	}
}

常用命令

编译上述代码后，可以通过命令行参数执行不同操作：

# 初始化迁移表
./migrator init

# 查看当前版本
./migrator version

# 升级到最新版本
./migrator up

# 升级到特定版本
./migrator up 2

# 回滚一个版本
./migrator down

# 回滚到特定版本
./migrator down 1

# 重置数据库(所有down迁移)
./migrator reset

迁移文件示例

001_init.up.sql

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE posts (
    id SERIAL PRIMARY KEY,
    user_id INTEGER REFERENCES users(id),
    title TEXT NOT NULL,
    body TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

001_init.down.sql

DROP TABLE posts;
DROP TABLE users;

002_add_user_status.up.sql

ALTER TABLE users ADD COLUMN status TEXT DEFAULT 'active';

002_add_user_status.down.sql

ALTER TABLE users DROP COLUMN status;

使用Go代码定义迁移

除了SQL文件，你也可以用Go代码定义迁移：

func init() {
	migrations.Register(func(db migrations.DB) error {
		_, err := db.Exec(`
			CREATE TABLE products (
				id SERIAL PRIMARY KEY,
				name TEXT NOT NULL,
				price DECIMAL(10,2) NOT NULL
			)
		`)
		return err
	}, func(db migrations.DB) error {
		_, err := db.Exec("DROP TABLE products")
		return err
	})
}

高级用法

事务性迁移

默认情况下，每个迁移都在单独的事务中执行。你可以禁用此行为：

migrator.SetTableName("my_migrations") // 自定义迁移表名
migrator.DisableSQLMigrations()        // 禁用SQL迁移
migrator.DisableTx()                   // 禁用事务

自定义日志

migrator.SetLogger(logger) // 实现migrations.Logger接口

集成到现有项目

在实际项目中，你可以将迁移逻辑封装成单独的命令：

// cmd/migrate/main.go
package main

import (
	"log"
	"os"

	"github.com/go-pg/migrations/v8"
	"github.com/go-pg/pg/v10"
	"github.com/yourproject/internal/db"
)

func main() {
	migrator := migrations.NewCollector()
	err := migrator.DiscoverSQLMigrations("migrations")
	if err != nil {
		log.Fatal(err)
	}

	_, _, err = migrator.Run(db.GetDB(), os.Args[1:]...)
	if err != nil {
		log.Fatal(err)
	}
}

最佳实践

1. 每个迁移文件只做一件事
2. 确保down迁移能正确回滚up迁移的操作
3. 在生产环境执行迁移前，先在测试环境验证
4. 考虑使用版本控制来管理迁移文件
5. 对于大型数据库，考虑将数据迁移与结构迁移分开

go-pg-migrations提供了一种简单而强大的方式来管理PostgreSQL数据库的变更，特别适合与go-pg/pg库一起使用。通过遵循上述模式，你可以轻松实现数据库的版本控制和团队协作。