GORM 迁移脚本编写

数据库结构变更需版本化管理,本文介绍编写 GORM 迁移脚本的核心方法与最佳实践。

什么是迁移脚本

迁移脚本是记录数据库结构变更的独立文件,支持按版本顺序执行前进与回滚操作。

基础迁移结构

每个迁移文件包含 Up 和 Down 两个方法。

// 202605210001_create_users.go
package migrations

import "gorm.io/gorm"

func Up202605210001(db *gorm.DB) error {
    return db.AutoMigrate(&User{})
}

func Down202605210001(db *gorm.DB) error {
    return db.Migrator().DropTable(&User{})
}

命名规范:时间戳_描述.go,如 202605210001_create_users.go。

迁移注册与执行

将所有迁移注册到中央执行器。

type Migration struct {
    Version string
    Up      func(*gorm.DB) error
    Down    func(*gorm.DB) error
}

var Migrations = []Migration{
    {"202605210001", Up202605210001, Down202605210001},
    {"202605210002", Up202605210002, Down202605210002},
}

执行迁移:

func RunMigrations(db *gorm.DB, targetVersion string) error {
    // 1. 查询当前版本
    var current string
    db.Raw("SELECT version FROM schema_migrations ORDER BY version DESC LIMIT 1").
        Scan(&current)

    // 2. 执行前进或回滚
    for _, m := range Migrations {
        if m.Version > current && m.Version <= targetVersion {
            if err := m.Up(db); err != nil {
                return err
            }
            db.Create(&SchemaMigration{Version: m.Version})
        }
    }
    return nil
}

常见变更操作

添加列

func Up(db *gorm.DB) error {
    return db.Migrator().AddColumn(&User{}, "phone")
}

func Down(db *gorm.DB) error {
    return db.Migrator().DropColumn(&User{}, "phone")
}

修改列类型

func Up(db *gorm.DB) error {
    return db.Migrator().AlterColumn(&User{}, "email")
}

func Down(db *gorm.DB) error {
    // 回滚到原类型
    return db.Exec("ALTER TABLE users MODIFY email VARCHAR(100)").Error
}

创建索引

func Up(db *gorm.DB) error {
    return db.Migrator().CreateIndex(&User{}, "idx_email")
}

func Down(db *gorm.DB) error {
    return db.Migrator().DropIndex(&User{}, "idx_email")
}

• **每个迁移必须实现 Down:**缺失回滚脚本的迁移不应被接受。
• **幂等性:**迁移应可重复执行而不报错,使用 IF NOT EXISTS 等语法。
• **版本追踪:**创建 schema_migrations 表记录当前版本。
• **不可逆变更:**如删除列、清空表,Down 方法应返回明确错误提示。

要点总结

• 迁移脚本是数据库变更的版本管理方式,包含 Up 和 Down。
• 命名规范:时间戳_描述.go,按序执行。
• 每次变更必须实现回滚逻辑,缺失 Down 的迁移不应接受。
• 使用 schema_migrations 表追踪当前版本。

存放路径: D:\git2\jwdev\articles\GORM\专家\数据迁移与版本管理\迁移脚本编写.md