Go Goose UpTo 和 UpByOne 执行迁移的范围有什么区别

Goose 的 UpTo 和 UpByOne 都是向前执行迁移，但它们的边界不一样：UpTo 把指定版本当作上限，可能连续执行多个未执行迁移；UpByOne 只执行当前版本之后排序得到的下一个迁移。它们不是“执行到某个文件”和“版本号加一”的简单别名。

官方地址：https://github.com/pressly/goose

判断时只看三件事：数据库当前版本、迁移集合中的版本排序，以及调用方想要的执行范围。版本文件之间即使相差很大，UpByOne 仍然只取一个；目标版本也不能替代缺失的迁移实现。

先区分目标版本上限与单次迁移数量

假设迁移集合里有 100、150、240、310 四个版本，数据库当前版本是 100。此时调用 UpTo(..., 310)，范围内的 150、240、310 都可能被连续应用；调用 UpByOne(...)，只会选择当前版本之后的第一个可执行迁移，也就是 150。

这里的“第一个”来自 Goose 收集后的版本排序，不是把当前数字直接加一。下一份文件可以从 100 跳到 150，也可以使用时间戳版本。数字间的空档本身不是要执行的迁移。

UpTo 看的是目标版本上限

Goose 的 UpTo 会先收集当前版本与目标版本之间的迁移，再读取数据库中的已应用版本，过滤掉已经执行的项，最后按版本顺序执行仍然高于当前版本且不超过目标版本的迁移。

所以目标版本是“最多执行到哪里”，不是“只执行一份”。如果当前版本为 100、目标版本为 240，集合里有 150 和 240 两份未执行迁移，正常情况下两份都会进入本次调用。若目标版本低于当前版本，这就不是向前补齐的场景，应重新确认是否误用了向前 API。

package main

import (
    "context"
    "database/sql"
    "fmt"

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

func migrateTo(ctx context.Context, db *sql.DB) error {
    // 目标版本是上限；100 到 240 之间的未执行迁移可能连续执行。
    if err := goose.UpToContext(ctx, db, "./migrations", 240); err != nil {
        return fmt.Errorf("迁移到目标版本失败: %w", err)
    }
    // 由调用方决定失败后是否停止发布流程，不在这里改写版本表。
    return nil
}

如果中间版本缺失，Goose 默认会报告缺失迁移，而不是默默跳过去。WithAllowMissing 会改变这一行为，但它解决的是缺失项策略，不会把目标版本变成单步执行开关。

UpByOne 只取下一个未执行迁移

UpByOne 的实现会复用向前收集和版本判断逻辑，再设置单次应用选项。遍历到第一个满足“版本高于数据库当前版本且尚未应用”的迁移后，执行它并立即返回。因此它适合把一次发布拆成可观察的小步，而不是用来指定一个最终版本。

func applyOne(ctx context.Context, db *sql.DB) error {
    // 每次只推进一个版本，数字不必与当前版本连续。
    if err := goose.UpByOneContext(ctx, db, "./migrations"); err != nil {
        // 没有下一个版本时，调用方可以把它当作“已追平”处理。
        return fmt.Errorf("执行下一份迁移失败: %w", err)
    }
    return nil
}

命令行对应关系也很直接：

# 迁移到指定版本上限，可能执行多份未完成迁移。
goose postgres DB_URL up-to 240

# 只推进当前版本之后的下一份迁移。
goose postgres DB_URL up-by-one

上面的命令只展示调用边界，示例中的环境变量和数据库连接没有在本文中执行。生产环境应把驱动、连接串、迁移目录与目标环境绑定，避免把测试库的当前版本误当成生产状态。

版本空档和“没有下一份”怎么判断

排查“为什么 UpByOne 没有按预期执行”时，先看 status 得到的当前版本和待执行列表，再确认迁移目录、嵌入文件系统或 Go 注册迁移是否与运行中的二进制一致。不要因为版本号有空档就手工创建一个空迁移，也不要直接改数据库版本表来跳过真实变更。

按调用方目标选择 API

需要把数据库推进到一个明确的发布版本时，用 UpTo；需要在发布流水线、灰度过程或人工排障中每次只推进一份时，用 UpByOne。如果业务要求“最多推进 N 份”，可以在调用方循环 UpByOne，但必须明确处理中途失败和已经没有下一份的情况。

UpTo 只执行一份迁移吗？不是。它以目标版本限制范围，范围中有多份未执行迁移时会连续应用。

UpByOne 是把版本号加一吗？不是。它按已收集迁移的版本排序找下一份，版本号可以是不连续的时间戳。

已经到最新版本时两者返回一样吗？不应混为一谈。UpTo 的无迁移场景通常是正常返回；UpByOne 用“没有下一版本”的错误表达没有可推进项，调用方需要单独处理。

可以用 UpByOne 替代回滚吗？不可以。它只负责向前应用一份迁移，回滚应使用 Goose 的 Down 相关命令或 API，并单独评估数据可逆性。