在使用Goose工具执行PostgreSQL数据库迁移时，如果迁移文件中包含使用美元引用定义的存储函数、触发器等对象，很容易出现未终止的美元引用字符串错误，导致迁移执行失败。
错误触发场景
Goose默认会按分号分割SQL语句来执行迁移，而PostgreSQL的函数定义中经常会包含美元引用字符串，这类字符串内部可能包含分号，Goose的默认分割逻辑会错误拆分美元引用内容，导致解析时出现未终止的字符串错误。
比如下面这段迁移SQL就会触发该错误：
-- 错误的迁移SQL示例
CREATE OR REPLACE FUNCTION test_func()
RETURNS void AS $$
BEGIN
-- 内部有分号，Goose默认会按分号拆分
INSERT INTO test_table (id, name) VALUES (1, 'test');
UPDATE test_table SET name = 'new' WHERE id = 1;
END;
$$ LANGUAGE plpgsql;
排查方法
遇到这类错误时，可以按照以下步骤排查：
- 检查迁移文件中是否包含PostgreSQL的美元引用语法，即
$$包裹的内容 - 查看美元引用内部是否存在分号，分号是Goose默认拆分语句的标记
- 确认迁移文件是否没有使用Goose的语句分隔符配置，导致默认拆分逻辑生效
解决方案
方案一：使用Goose的自定义语句分隔符
Goose支持通过特殊注释设置自定义语句分隔符，我们可以设置一个不会出现在函数定义中的分隔符，避免拆分美元引用内容。比如在迁移文件开头添加如下注释：
-- 设置自定义分隔符为//，避免拆分函数内的分号
-- +goose StatementBegin
-- +goose StatementEnd 可以配合使用，标记多行语句块
CREATE OR REPLACE FUNCTION test_func()
RETURNS void AS $$
BEGIN
INSERT INTO test_table (id, name) VALUES (1, 'test');
UPDATE test_table SET name = 'new' WHERE id = 1;
END;
$$ LANGUAGE plpgsql;
-- +goose StatementEnd
其中-- +goose StatementBegin和-- +goose StatementEnd会告诉Goose，这两个注释之间的内容作为一个完整的SQL语句执行，不会按内部的分号拆分。
方案二：改用单引号转义定义函数
如果不想使用自定义分隔符，也可以将美元引用替换为单引号转义的方式定义函数，不过这种方式需要手动转义函数内的单引号，可读性会差一些：
-- 单引号转义方式定义函数
CREATE OR REPLACE FUNCTION test_func()
RETURNS void AS '
BEGIN
INSERT INTO test_table (id, name) VALUES (1, ''test'');
UPDATE test_table SET name = ''new'' WHERE id = 1;
END;
' LANGUAGE plpgsql;
规范编写建议
为了避免这类问题，编写PostgreSQL迁移文件时建议遵循以下规范：
- 所有包含美元引用的函数、触发器定义，都使用
-- +goose StatementBegin和-- +goose StatementEnd包裹 - 不要在美元引用字符串内部使用
$$，避免嵌套导致解析错误 - 迁移文件执行前先在本地PostgreSQL环境中手动执行SQL，确认语法正确后再用Goose执行
验证修复效果
修复后可以执行Goose迁移命令验证：
# 执行迁移 goose postgres "host=127.0.0.1 user=test password=test dbname=test sslmode=disable" up
如果命令执行成功，没有报未终止的美元引用字符串错误，说明问题已经解决。
GoosePostgreSQL美元引用字符串数据库迁移函数定义修改时间：2026-07-16 13:57:49