Prisma项目中TypedSQL查询数组参数引发的TypeError问题分析

问题背景

在使用Prisma ORM进行数据库操作时，开发者经常会遇到需要执行原生SQL查询的场景。Prisma提供了$queryRaw和$queryRawTyped方法来支持这种需求。然而，当这些查询涉及到数组参数时，特别是空数组时，可能会出现一些意料之外的行为。

问题现象

在Prisma项目中，当开发者尝试使用TypedSQL执行包含数组参数的查询时，可能会遇到以下错误：

TypeError: Cannot read properties of undefined (reading 'map')
  at gl (/node_modules/@prisma/client/runtime/library.js:114:15435) 
  at $t (/node_modules/@prisma/client/runtime/library.js:114:15380)

这个错误通常发生在以下场景：

1. 定义了一个包含数组参数的SQL模板
2. 调用$queryRawTyped方法时传入空数组作为参数
3. 在执行查询前，Prisma内部处理参数时抛出异常

技术分析

参数处理机制

Prisma在执行TypedSQL查询时，会对传入的参数进行特殊处理。对于数组参数，Prisma内部会尝试调用map方法进行转换。当传入undefined或null值时，就会触发上述错误。

空数组的特殊性

在PostgreSQL中，空数组[]与NULL是不同的概念。开发者通常会在SQL查询中使用IS NULL或= ANY()等条件来处理这两种情况。然而，Prisma在将JavaScript空数组转换为SQL参数时，可能存在一些边界情况处理不完善的问题。

解决方案

1. 参数索引修正

确保SQL查询中的参数索引从$1开始连续编号，避免跳过索引。例如：

SELECT p."id"
FROM "Property" p
LEFT JOIN "Address" addr ON addr."propertyId" = p."id"  
WHERE
  ($1::text[] IS NULL OR addr."stateAbbv" = ANY($1))
  AND ($2::text[] IS NULL OR addr."zip" = ANY($2))

2. 使用array_length检查

改用array_length函数来检查数组是否为空：

SELECT p."id"
FROM "Property" p
LEFT JOIN "Address" addr ON addr."propertyId" = p."id"  
WHERE
  (array_length($1::text[], 1) IS NULL OR addr."stateAbbv" = ANY($1::text[]))
  AND (array_length($2::text[], 1) IS NULL OR addr."zip" = ANY($2::text[]))

3. 参数传递方式

确保调用$queryRawTyped时正确传递参数：

const rows = await prisma.$queryRawTyped(
  filterProperties([], [])
);

最佳实践

1. 参数验证：在执行查询前，验证所有数组参数是否为有效值
2. 错误处理：使用try-catch包裹查询调用，捕获可能的异常
3. 日志记录：在开发环境中记录完整的查询和参数，便于调试
4. 类型安全：充分利用TypeScript类型检查，确保参数类型与SQL模板匹配

总结

Prisma的TypedSQL功能为开发者提供了强大的类型安全SQL查询能力，但在处理数组参数时仍需注意一些细节。通过理解Prisma内部参数处理机制，并采用适当的SQL编写方式，可以有效避免这类错误的发生。对于复杂的查询场景，建议先在开发环境中充分测试各种边界情况，确保生产环境的稳定性。