Kysely 中使用 PostgreSQL 数组类型的正确姿势

在使用 Kysely 这个类型安全的 SQL 查询构建器与 PostgreSQL 数据库交互时，开发者可能会遇到一些关于数组类型的特殊问题。本文将深入探讨如何正确处理 PostgreSQL 数组类型，特别是当我们需要查询包含特定元素的数组列时。

数组类型在 PostgreSQL 中的表示

PostgreSQL 中的数组类型有其特殊的语法要求。与许多编程语言不同，PostgreSQL 使用花括号 {} 来表示数组字面量，而不是方括号 []。这是导致上述错误的主要原因。

正确的数组查询方式

当我们需要查询 in_episodes 数组列包含特定元素（如数字 1）的记录时，正确的 Kysely 查询应该是：

const videosOfEpisodeOne = await db
  .selectFrom('videos')
  .where('in_episodes', '@>', sql`array[1]`)
  .selectAll()
  .execute();

关键点在于使用 sql 模板标签和 array[] 语法来构造 PostgreSQL 能够识别的数组表达式。

表类型定义的最佳实践

在定义包含数组列的表类型时，我们应该明确指定数组元素的类型：

type VideoTable = {
  id: Generated<number>;
  in_episodes: ColumnType<number[], number[], number[]>;
}

这种定义方式确保了类型安全，同时明确了该列在数据库中是数字数组类型。

为什么原始查询会失败

原始查询直接使用了 JavaScript 数组 [1] 作为参数，这在 PostgreSQL 中会被解释为字符串字面量 "1"，而不是数组。PostgreSQL 期望数组字面量以 { 开头或者包含维度信息，因此会抛出 malformed array literal 错误。

其他有用的数组操作符

除了 @> (包含)操作符外，PostgreSQL 还提供了其他有用的数组操作符：

• &&：数组有重叠（有共同元素）
• <@：数组被包含
• =：数组相等
• ||：数组连接

在 Kysely 中，这些操作符都可以类似地使用 sql 模板标签来构造正确的查询条件。

总结

在使用 Kysely 与 PostgreSQL 交互时，处理数组类型需要特别注意 PostgreSQL 的特殊语法要求。通过使用 sql 模板标签和正确的数组构造语法，我们可以避免常见的错误，构建出既类型安全又符合 PostgreSQL 语法的查询。记住，数据库中的数组表示法与编程语言中的通常不同，这是许多开发者容易忽视的一个重要细节。