SQL Formatter 项目中的 T-SQL MERGE 语句 $action 伪列格式化问题解析

在 SQL 开发工作中，MERGE 语句是一个非常强大的数据操作工具，特别是在 T-SQL 中。最近在 SQL Formatter 项目中发现了一个关于 MERGE 语句 OUTPUT 子句中 $action 伪列的特殊格式化问题，值得深入探讨。

问题背景

T-SQL 的 MERGE 语句允许开发者在单个原子操作中执行插入、更新或删除操作。在 OUTPUT 子句中，$action 是一个特殊的伪列，它返回当前行执行的操作类型（INSERT、UPDATE 或 DELETE）。这个特性对于日志记录和审计非常有用。

问题现象

当开发者在 SQL Formatter 中尝试格式化包含 $action 伪列的 MERGE 语句时，格式化器会抛出解析错误。例如以下语句：

MERGE INTO DestinationTable WITH (HOLDLOCK)
AS Target
USING SourceTable
AS Source
    ON Target.Id = Source.Id
WHEN NOT MATCHED THEN
    INSERT (Name, Updated, Created)
    VALUES (Source.Name, GETUTCDATE(), GETUTCDATE())
WHEN MATCHED THEN
    UPDATE SET
        Target.Name = Source.Name,
        Target.Updated = Source.Updated
OUTPUT
    COALESCE(Inserted.Id, Source.Id) AS SourceId,
    $action AS Action;

格式化器会报错："Unexpected "$action AS" at line 25 column 5"，这是因为 `$action` 没有被正确识别为 T-SQL 的特殊关键字。

技术分析

$action 是 T-SQL 特有的伪列，它：

1. 仅在 MERGE 语句的 OUTPUT 子句中有效
2. 不区分大小写（$ACTION 同样有效）
3. 是固定的伪列名，不能修改为类似 $action2 的形式
4. 返回值为字符串类型的操作类型

在 SQL 解析器中，这类特殊标识符需要特别处理。它们既不是普通标识符，也不是参数或变量，而是语言内置的特殊符号。

解决方案

SQL Formatter 项目通过以下方式解决了这个问题：

1. 将 $action 添加到 T-SQL 关键字列表中
2. 确保在关键字大小写转换时正确处理（如 keywordCase:upper 选项）
3. 保持与 SQL Server 相同的不区分大小写特性

临时解决方案

在修复版本发布前，开发者可以使用参数类型配置作为临时解决方案：

{
  paramTypes: { named: ['@', '$'] }
}

这个配置告诉格式化器将 $ 开头的标识符视为参数，避免解析错误。

最佳实践

在使用 MERGE 语句时，建议：

1. 明确指定 $action 的别名（如 $action AS Operation）
2. 考虑在日志表中存储操作类型
3. 注意 MERGE 语句的事务隔离级别（如示例中的 HOLDLOCK 提示）

总结

SQL 格式化工具需要不断适应各种数据库特有的语法特性。这次 $action 伪列的修复体现了 SQL Formatter 项目对 T-SQL 完整性的持续支持。开发者在使用高级 SQL 特性时，应当注意工具链的兼容性，并及时报告发现的问题，共同完善开源生态。

对于需要处理 MERGE 语句输出结果的场景，正确格式化的 SQL 不仅能提高代码可读性，还能减少潜在的语法错误，是数据库开发中不可忽视的一环。