SQLDelight 中关键字作为列名时 INSERT 语句生成问题解析

问题背景

在 SQLDelight 2.0.2 版本中，当使用 PostgreSQL 方言时，如果表名是 PostgreSQL 的关键字（如 "order"），并且在 .sq 文件中使用 VALUES ? 语法进行插入操作时，生成的代码会丢失表名周围必要的双引号，导致 SQL 语法错误。

问题表现

开发者定义了一个名为 "order" 的表（order 是 PostgreSQL 的关键字），并编写了如下插入语句：

CREATE TABLE "order"
(
    id uuid PRIMARY KEY NOT NULL
);

saveOrder:
INSERT INTO "order"
VALUES ?;

生成的 Kotlin 代码中，INSERT 语句变成了：

INSERT INTO order (id)
VALUES (?)

由于缺少双引号，PostgreSQL 会报语法错误："ERROR: syntax error at or near 'order'"。

技术分析

这个问题源于 SQLDelight 在处理 VALUES ? 这种特殊语法时的表名引用处理逻辑。在 SQLDelight 中，VALUES ? 是一种便捷语法，允许开发者直接传入一个对象而不是单独绑定每个字段值。

深入分析发现：

1. 对于常规的 INSERT 语句（明确列出列名），SQLDelight 能正确处理带引号的表名
2. 问题仅出现在使用 VALUES ? 语法时
3. 底层原因是 TreeUtil 类在处理表名时，使用了 SqlNamedElementImpl 的 text 属性，而不是保留原始文本格式

解决方案

修复方案的核心是确保在处理表名时保留原始的双引号。具体实现上：

1. 使用 tableName.node.text 替代简单的 text 属性访问
2. 这样可以获取到未经修改的原始表名文本，包括必要的引号
3. 保持与 SELECT 查询一致的处理逻辑

技术影响

这个修复对于使用 PostgreSQL 或其他需要引用标识符的 SQL 方言的开发者尤为重要。它确保了：

1. 代码生成的一致性，无论使用哪种 INSERT 语法
2. 对关键字作为标识符的完整支持
3. 向后兼容性，不影响现有正确代码

最佳实践

为避免类似问题，开发者可以：

1. 对于可能的关键字标识符，始终使用引号
2. 考虑使用更明确的 INSERT 语法（列出所有列名）
3. 在遇到类似问题时，检查生成的 SQL 语句是否符合目标数据库的语法要求

这个修复体现了 SQLDelight 对多种 SQL 方言支持的不断完善，特别是在处理数据库特定语法和关键字方面。