Golang 数据库 Schema 迁移与嵌入二进制文件

在 Go 语言中，处理数据库 schema 迁移并将迁移文件嵌入到二进制中是常见的需求。下面我将介绍几种实现方式。

1. 使用 go-migrate 库

go-migrate 是一个流行的数据库迁移工具，支持多种数据库。

安装

go get -u github.com/golang-migrate/migrate/v4

基本使用

import (
    "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:///path/to/migrations",
        "postgres://user:password@localhost:5432/database?sslmode=disable")
    if err != nil {
        // 处理错误
    }
    
    // 执行所有待处理的迁移
    if err := m.Up(); err != nil && err != migrate.ErrNoChange {
        // 处理错误
    }
}

2. 嵌入迁移文件到二进制

使用 Go 1.16+ 的 embed 功能，我们可以将迁移文件直接嵌入到二进制中。

项目结构

project/
├── migrations/
│   ├── 0001_init.up.sql
│   └── 0001_init.down.sql
├── main.go

使用 embed 嵌入文件

package main

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

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

func main() {
    d, err := iofs.New(fs, "migrations")
    if err != nil {
        panic(err)
    }
    
    m, err := migrate.NewWithSourceInstance("iofs", d, "postgres://user:password@localhost:5432/database?sslmode=disable")
    if err != nil {
        panic(err)
    }
    
    if err := m.Up(); err != nil && err != migrate.ErrNoChange {
        panic(err)
    }
}

3. 使用 sql-migrate 库

另一个流行的选择是 sql-migrate。

安装

go get github.com/rubenv/sql-migrate

使用示例

package main

import (
    "database/sql"
    "embed"
    "log"
    
    "github.com/rubenv/sql-migrate"
    _ "github.com/lib/pq"
)

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

func main() {
    db, err := sql.Open("postgres", "user=postgres dbname=test sslmode=disable")
    if err != nil {
        log.Fatal(err)
    }
    
    // 创建迁移源
    migrations := &migrate.EmbedFileSystemMigrationSource{
        FileSystem: migrationsFS,
        Root:       "migrations",
    }
    
    // 执行迁移
    n, err := migrate.Exec(db, "postgres", migrations, migrate.Up)
    if err != nil {
        log.Fatal(err)
    }
    
    log.Printf("Applied %d migrations!\n", n)
}

4. 自定义简单迁移方案

对于简单需求，可以自己实现迁移逻辑：

package main

import (
    "database/sql"
    "embed"
    "fmt"
    "io/fs"
    _ "github.com/lib/pq"
)

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

func main() {
    db, err := sql.Open("postgres", "postgres://user:password@localhost/dbname?sslmode=disable")
    if err != nil {
        panic(err)
    }
    defer db.Close()
    
    // 创建迁移表
    _, err = db.Exec(`CREATE TABLE IF NOT EXISTS schema_migrations (
        version TEXT PRIMARY KEY,
        applied_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
    )`)
    if err != nil {
        panic(err)
    }
    
    // 读取已应用的迁移
    applied := make(map[string]bool)
    rows, err := db.Query("SELECT version FROM schema_migrations")
    if err != nil {
        panic(err)
    }
    defer rows.Close()
    
    for rows.Next() {
        var version string
        if err := rows.Scan(&version); err != nil {
            panic(err)
        }
        applied[version] = true
    }
    
    // 应用新迁移
    files, err := fs.ReadDir(migrations, "migrations")
    if err != nil {
        panic(err)
    }
    
    for _, file := range files {
        if file.IsDir() {
            continue
        }
        
        version := file.Name()
        if _, ok := applied[version]; ok {
            continue
        }
        
        content, err := fs.ReadFile(migrations, "migrations/"+version)
        if err != nil {
            panic(err)
        }
        
        // 在事务中执行迁移
        tx, err := db.Begin()
        if err != nil {
            panic(err)
        }
        
        if _, err := tx.Exec(string(content)); err != nil {
            tx.Rollback()
            panic(fmt.Errorf("migration %s failed: %v", version, err))
        }
        
        if _, err := tx.Exec("INSERT INTO schema_migrations (version) VALUES ($1)", version); err != nil {
            tx.Rollback()
            panic(fmt.Errorf("failed to record migration %s: %v", version, err))
        }
        
        if err := tx.Commit(); err != nil {
            panic(err)
        }
        
        fmt.Printf("Applied migration: %s\n", version)
    }
}

最佳实践

1. 版本控制：每个迁移文件应该有明确的版本号前缀
2. 原子性：每个迁移应该在一个事务中执行
3. 回滚：为每个迁移提供对应的回滚脚本
4. 测试：在测试环境中验证迁移
5. 备份：在生产环境执行前备份数据

以上方案可以根据项目需求选择使用。对于大多数项目，go-migrate 或 sql-migrate 结合 embed 功能是很好的选择。