Golang数据库迁移工具migrate使用指南

migrate是一个流行的Golang数据库迁移工具，支持多种数据库系统，包括PostgreSQL、MySQL、SQLite、MongoDB等。下面我将详细介绍如何使用migrate进行数据库迁移。

安装migrate

首先安装migrate命令行工具和Go库：

# 安装命令行工具
go install -tags 'postgres' github.com/golang-migrate/migrate/v4/cmd/migrate@latest

# 添加依赖到项目
go get -u github.com/golang-migrate/migrate/v4

基本使用

1. 创建迁移文件

migrate create -ext sql -dir db/migrations -seq create_users_table

这会创建两个文件：

• db/migrations/000001_create_users_table.up.sql - 升级迁移
• db/migrations/000001_create_users_table.down.sql - 回滚迁移

2. 编写迁移SQL

在up文件中添加创建表的SQL：

-- db/migrations/000001_create_users_table.up.sql
CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    email VARCHAR(255) UNIQUE NOT NULL,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

在down文件中添加删除表的SQL：

-- db/migrations/000001_create_users_table.down.sql
DROP TABLE IF EXISTS users;

3. 执行迁移

在Go代码中执行迁移：

package main

import (
	"log"

	"github.com/golang-migrate/migrate/v4"
	_ "github.com/golang-migrate/migrate/v4/database/postgres"
	_ "github.com/golang-migrate/migrate/v4/source/file"
)

func main() {
	m, err := migrate.New(
		"file://db/migrations",
		"postgres://user:password@localhost:5432/dbname?sslmode=disable")
	if err != nil {
		log.Fatal(err)
	}
	defer m.Close()

	// 执行所有待处理的迁移
	if err := m.Up(); err != nil && err != migrate.ErrNoChange {
		log.Fatal(err)
	}
}

高级功能

1. 版本控制

// 获取当前版本
version, dirty, err := m.Version()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Current version: %d, dirty: %v\n", version, dirty)

// 迁移到特定版本
err = m.Migrate(2) // 迁移到版本2
if err != nil {
    log.Fatal(err)
}

// 回滚一步
err = m.Steps(-1)
if err != nil {
    log.Fatal(err)
}

2. 使用嵌入文件系统

将迁移文件嵌入到二进制文件中：

import (
	"embed"
	"github.com/golang-migrate/migrate/v4/source/iofs"
)

//go:embed db/migrations/*.sql
var fs embed.FS

func main() {
	d, err := iofs.New(fs, "db/migrations")
	if err != nil {
		log.Fatal(err)
	}

	m, err := migrate.NewWithSourceInstance("iofs", d, "postgres://...")
	if err != nil {
		log.Fatal(err)
	}
	// ...
}

3. 自定义迁移源

type MySource struct {
    // 实现migrate.Source接口
}

m, err := migrate.NewWithSourceInstance("custom", &MySource{}, "postgres://...")

最佳实践

1. 原子性迁移：每个迁移应该是一个原子操作，要么完全成功，要么完全失败。

2. 幂等性：迁移脚本应该是幂等的，可以安全地多次执行。

3. 小步迁移：每个迁移应该只做一件事，保持迁移小而简单。

4. 测试迁移：在测试环境中测试迁移和回滚。

5. 版本控制：将迁移文件与应用程序代码一起进行版本控制。

常见问题解决

1. 数据库锁定：migrate使用锁表来防止并发迁移，如果迁移意外中断可能导致锁表。可以手动删除锁表或使用force命令。

2. 脏状态：如果迁移部分失败，数据库会标记为"dirty"。需要手动修复并运行m.Force(version)清除脏状态。

3. 环境变量：建议使用环境变量管理数据库连接字符串：

dsn := fmt.Sprintf("postgres://%s:%s@%s:%s/%s?sslmode=disable",
    os.Getenv("DB_USER"),
    os.Getenv("DB_PASSWORD"),
    os.Getenv("DB_HOST"),
    os.Getenv("DB_PORT"),
    os.Getenv("DB_NAME"))

migrate是一个强大而灵活的数据库迁移工具，通过合理使用可以大大简化数据库版本管理的工作。