ElectricSQL 中使用参数化 WHERE 子句的注意事项

在 ElectricSQL 项目中，开发者经常需要通过 Shape 机制订阅数据库表的变更。其中 WHERE 子句的参数化查询是一个常见需求，但在使用过程中可能会遇到一些版本兼容性问题。

参数化查询的正确用法

ElectricSQL 支持在 Shape 定义中使用参数化 WHERE 条件，这是防止 SQL 注入的最佳实践。标准用法如下：

const shape = new Shape({
  // ...其他配置
  params: {
    table: "目标表名",
    where: "条件字段 = $1",  // 使用$1作为占位符
    params: [参数值]        // 传入实际参数数组
  }
});

这种语法与 PostgreSQL 的参数化查询规范一致，使用$1、$2等作为占位符，然后在params数组中按顺序提供实际值。

常见错误分析

开发者可能会遇到错误提示："ParamRef is not supported in this context"。这通常表明：

1. 使用的 ElectricSQL 服务端版本过旧
2. 参数占位符语法使用不当
3. 参数数组与占位符数量不匹配

版本兼容性关键点

在 ElectricSQL 1.0.0-beta.23 及更早版本中，参数化查询功能可能存在限制。从 1.0.4 版本开始，服务端完善了对参数化 WHERE 子句的支持。

如果遇到类似问题，建议：

1. 检查服务端版本
2. 确保客户端和服务端版本兼容
3. 考虑升级到最新稳定版

最佳实践建议

1. 始终使用参数化查询来防范 SQL 注入
2. 保持客户端和服务端版本同步
3. 在开发环境充分测试 WHERE 条件
4. 对于复杂查询，考虑先在 PostgreSQL 客户端验证语法

通过遵循这些准则，可以确保 ElectricSQL 的数据订阅功能既安全又可靠。