Kysely SQL模板标签在SQLite中的SELECT语句括号问题解析

问题背景

在使用Kysely这个TypeScript SQL查询构建器时，开发者遇到了一个与SQLite兼容性相关的问题。当通过SQL模板标签构建包含EXCEPT操作的复杂查询时，Kysely自动生成的SELECT语句会被包裹在括号中，这在SQLite中会导致语法错误。

问题复现

考虑以下原始SQL查询：

INSERT INTO "cardTag"
SELECT
  KEY AS cardId,
  value AS tag
FROM json_tree(blah)
EXCEPT
SELECT *
FROM "cardTag"
WHERE "cardId" IN (?, ?, ?)

当尝试使用Kysely的SQL模板标签实现时：

await db
  .insertInto('cardTag')
  .expression(
    (qb) => sql<CardTag>`
SELECT key AS cardId,
       value AS tag
FROM json_tree(blah)
EXCEPT
${qb.selectFrom('cardTag').selectAll().where('cardId', 'in', cardIds)}`
  )
  .execute()

生成的SQL会在EXCEPT后的SELECT语句外添加括号，这在SQLite中是不被允许的：

INSERT INTO "cardTag"
SELECT key AS cardId,
       value AS tag
FROM json_tree(blah)
EXCEPT
(SELECT * FROM "cardTag" WHERE "cardId" IN (?, ?, ?)) -- 非法括号

技术分析

这个问题源于Kysely默认的查询编译器行为。在DefaultQueryCompiler中，SELECT查询默认会被wrapInParens标志包裹在括号中，这是为了确保查询在不同数据库引擎中的一致性。然而，SQLite对EXCEPT操作符后的子查询有特殊要求，不允许使用括号。

解决方案

临时解决方案

开发者发现可以使用Kysely提供的sql.join工具函数手动处理IN子句参数：

await db
  .insertInto('cardTag')
  .expression(
    (qb) => sql<CardTag>`
SELECT key AS cardId,
       value AS tag
FROM json_tree(blah)
EXCEPT
SELECT * FROM cardTag where cardId in (${sql.join(cardIds)})`
  )
  .execute()

这种方法避免了使用Kysely的查询构建器生成SELECT语句，从而绕过了括号问题。

长期解决方案

从技术实现角度看，更彻底的解决方案是修改SQLite的查询编译器，覆盖visitSelectQuery方法，移除wrapInParens标志。这需要修改Kysely的核心代码，为SQLite提供特殊的处理逻辑。

最佳实践建议

1. 当使用SQLite特有的函数(如json_tree)时，考虑完全使用原始SQL模板字符串
2. 对于复杂的集合操作(UNION/EXCEPT/INTERSECT)，注意不同数据库的语法差异
3. 在必须混合使用Kysely构建器和原始SQL时，优先使用Kysely提供的参数化工具(如sql.join)
4. 关注Kysely的版本更新，这个问题未来可能会在框架层面得到解决

总结

这个问题展示了ORM/查询构建器在处理不同数据库方言时的挑战。虽然Kysely提供了强大的类型安全和流畅的API，但在处理特定数据库的语法细节时，开发者仍需了解底层SQL的知识。通过合理使用原始SQL模板和构建器的组合，可以找到既安全又兼容的解决方案。