Go Goose 怎样为包含分号的存储过程标记语句范围

我在把存储过程放进 Goose 的 SQL migration 时，最容易误判的一件事是：数据库能接受这段过程，并不代表 Goose 能按你想要的范围切分它。默认情况下，Goose 把分号当作 SQL 语句分隔符；而过程体内部往往还有多个分号，于是同一个过程可能被拆成几段。

处理方法很明确：在完整的过程定义前写 -- +goose StatementBegin，在定义结束后写 -- +goose StatementEnd。这两个注解告诉 Goose，边界内的内容要作为一条复杂语句交给数据库。

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

不要试图删除过程体里的分号，也不要把 MySQL 的 multiStatements 当成过程边界标记。真正负责“包住一条复杂语句”的是 Goose 的 StatementBegin 和 StatementEnd。

先看清故障信号：是 Goose 拆开了过程

典型场景是 migration 文件里包含函数、触发器或存储过程，数据库客户端手工执行没有问题，但执行 goose up 时在过程体的中间位置报语法错误。尤其当错误位置靠近第二个、第三个分号时，优先怀疑迁移工具的语句切分，而不是立刻改写数据库语法。

我通常先做三个快速判断：

• 确认错误发生在过程体内部，而不是过程头部的参数或返回类型。
• 数一下过程体里是否存在多个以分号结尾的语句。
• 检查文件是否只有 -- +goose Up，以及复杂语句两侧是否有完整边界标记。

这一步的意义是把问题分层：如果 Goose 已经把 SQL 切成半截，继续调整数据库连接串通常不会解决根因。

用两个标记包住完整的存储过程

下面用 PostgreSQL 风格的函数说明边界写法。过程体里的 ; 仍然保留，它们属于过程定义本身；外层由 Goose 注解包住。

-- +goose Up
-- +goose StatementBegin
CREATE OR REPLACE FUNCTION refresh_order_total(p_order_id bigint)
RETURNS numeric
LANGUAGE plpgsql
AS $$
DECLARE
    v_total numeric;
BEGIN
    -- 过程内部可以有多条语句，每条语句仍然需要分号
    SELECT COALESCE(SUM(amount), 0)
      INTO v_total
      FROM order_items
     WHERE order_id = p_order_id;

    -- 返回值前保留过程语言要求的结束分号
    RETURN v_total;
END;
$$;
-- +goose StatementEnd

这里的关键不是 $$ 的写法，而是 Goose 看到 StatementBegin 后，会把直到 StatementEnd 的内容当作同一条复杂 SQL。过程内部的 SELECT 和 RETURN 分号不会再被当成 Goose 的外层分隔点。

让 Up 和 Down 的边界保持对称

如果 migration 同时提供回滚，就把 Down 也当成独立语句段处理。不要只给 Up 加标记，然后让 Down 里的过程删除或重建逻辑继续按默认分号切分。

-- +goose Up
-- +goose StatementBegin
CREATE OR REPLACE FUNCTION refresh_order_total(p_order_id bigint)
RETURNS numeric
LANGUAGE plpgsql
AS $$
BEGIN
    -- 这里用一个最小实现演示复杂语句的范围
    RETURN 0;
END;
$$;
-- +goose StatementEnd

-- +goose Down
-- +goose StatementBegin
DROP FUNCTION IF EXISTS refresh_order_total(bigint);
-- +goose StatementEnd

Up 与 Down 的注解顺序要清楚：先进入对应方向，再打开复杂语句边界，最后关闭边界。这样排查回滚失败时，可以直接判断是方向标记缺失，还是数据库本身不允许当前的删除操作。

不要把 multiStatements 和语句边界混为一谈

这两个配置解决的问题不同：

官方文档还说明，Goose 默认会在事务中运行迁移；遇到不能放进事务的语句，可以在文件顶部使用 -- +goose NO TRANSACTION。这不是存储过程分号的替代方案，二者应分别判断。

-- +goose NO TRANSACTION
-- +goose Up
-- +goose StatementBegin
-- 复杂 DDL 或过程定义放在这里
-- +goose StatementEnd

如果你使用的是 MySQL，还要根据官方说明检查连接配置是否启用了多语句支持；但即使启用，也不要省略 Goose 的复杂语句边界标记。

出现失败时按这个顺序处理和回滚

1. 先保留原始 migration。 不要在生产环境直接删掉过程体分号，先复制一份待修改文件，避免把数据库语法问题和解析问题混在一起。
2. 定位第一个异常分号。 如果报错位置落在过程体内部，检查它是否位于 StatementBegin 与 StatementEnd 之间。
3. 补齐同一方向的边界。 Up、Down 各自拥有完整的一对标记；不要跨越方向复用一对标记。
4. 再判断事务限制。 只有当数据库语句本身不能在事务中运行时，才考虑 NO TRANSACTION，不要把它当成解析修复开关。
5. 回滚失败时先停止重复执行。 记录当前 Goose 版本、驱动、数据库方言和 migration 文件版本，确认版本表中的状态后再决定是修复 Down，还是人工处理已创建对象。

我会把“补边界”和“改事务”拆成两个独立变更，这样下一次告警能从日志中看出到底是哪一层发生了变化。

发布前的值班检查清单

• 复杂语句只有一个清晰的 StatementBegin 到 StatementEnd 范围。
• 过程体内部的分号、美元引用或数据库过程语言语法保持原样。
• -- +goose Up 在对应文件中存在且位于 Down 之前；Down 按需提供。
• 如果使用 NO TRANSACTION，变更说明里写清楚不能事务化的数据库原因。
• MySQL 场景单独检查 multiStatements，不要用连接参数替代 Goose 边界注解。

记住一句话就够了：数据库过程内部的分号属于过程语言，Goose 的语句边界属于迁移解析。把两层边界写清楚，存储过程就不会因为被错误切片而在迁移阶段失效。

相关问题

Goose 为什么默认按分号切分 SQL？ 因为普通 SQL migration 通常以分号结束；复杂语句需要显式标记，才能避免内部分号被当作外层分隔符。

StatementBegin 能不能只写在存储过程前面？ 不能。它必须和对应的 StatementEnd 成对出现，并包住完整定义。

加了 NO TRANSACTION 还需要 StatementBegin 吗？ 需要。前者处理事务边界，后者处理 Goose 的语句范围，是两个独立问题。