Postgres.js 中处理带点号字符串值的注意事项

在使用 Postgres.js 进行数据库操作时，开发者可能会遇到一个特殊问题：当查询条件中包含带点号（.）的字符串值时，如电子邮件地址，系统会抛出错误。本文将深入分析这一问题的原因，并提供正确的解决方案。

问题现象

当开发者尝试执行类似以下查询时：

await sql`SELECT ${sql(cols)} FROM users WHERE ${sql(fieldName)} = ${sql(fieldValue)} LIMIT 1`

如果 fieldValue 是一个包含点号的字符串（如 "[e-mail]"），Postgres.js 会抛出错误，提示"cross-database references are not implemented"或"missing FROM-clause entry for table"。

问题根源

这个问题的根本原因在于 Postgres.js 对 sql() 标签函数的特殊处理方式。当值被包裹在 sql() 中时，Postgres.js 会尝试将其解析为 SQL 标识符而非普通值。对于包含点号的字符串，PostgreSQL 会将其误解为数据库对象引用（如表名.列名格式），从而导致解析错误。

正确用法

Postgres.js 的设计哲学是区分 SQL 标识符和普通值：

1. SQL 标识符（如表名、列名）应使用 sql() 包裹
2. 普通值（如字符串、数字）应直接插入模板字符串中

因此，正确的写法应该是：

await sql`
  SELECT ${sql(cols)} FROM users WHERE ${sql(fieldName)} = ${fieldValue} LIMIT 1
`

深入理解

Postgres.js 的这种设计有以下几个优点：

1. 安全性：自动处理 SQL 注入防护
2. 清晰性：明确区分标识符和值
3. 灵活性：支持动态构建查询

对于包含特殊字符的值，Postgres.js 会自动进行适当的转义和引用，开发者无需手动处理。

最佳实践

1. 仅对动态表名、列名等标识符使用 sql() 标签
2. 普通查询值直接插入模板字符串
3. 对于复杂查询，可以考虑使用命名参数方式提高可读性

await sql`
  SELECT * FROM users 
  WHERE email = ${email} 
  AND created_at > ${startDate}
`

通过遵循这些原则，可以避免类似点号字符串导致的解析问题，同时编写出更安全、更易维护的数据库查询代码。