尧图网页设计 
Electric v0.10 发布解析Shape 过滤与 Blob 数据支持【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric本篇文章基于仓库中 2024-04-10 的官方发布说明website/blog/posts/2024-04-10-electricsql-v0.10-released.md深入解读 Electric v0.10 的两大核心能力真正可用的 Shape 过滤where-clause 与 include-tree以及BYTEA/Blob 数据类型支持。读者将掌握sync()API 的正确用法、SQL 字符串 where 子句的书写方式、底层过滤实现的原理以及从 v0.10 到当前版本 Shape 体系columns、queryable_columns、子查询、优化 where 子句的演进脉络。[!WARNING] 版本说明 本文描述的 v0.10 是 Electric 的早期版本该版本已不再活跃。发布说明原文亦附有提示当前架构的演进请参考仓库中后续的 website/blog/posts/ 系列发布文章与最新文档。当前最新 API 与语义以 Shapes 指南 和 TypeScript Client 文档 为准。发布概览v0.10 解决了什么v0.10 是 Electric 首次真正支持基于 Shape 的 where-clause 与 include-tree 过滤的版本。在此之前sync()API 虽然已经存在但其实现是一个占位实现——它会**过度同步over-sync**数据并且强制要求开发者把相关的表全部包含进来。这意味着开发者无法真正利用 Shape 机制去控制哪些数据同步到本地设备。v0.10 同时新增了对**字节数组与 BlobBYTEA列**的数据类型支持为后续支持存储大字符串、文件乃至基于 SQLite Blob 的数据库如 CozoDB铺平了道路。Shape 过滤让动态部分复制真正落地Shape 是 Electric 系统中控制云端与本地设备之间同步什么数据的关键原语。它把 Postgres 数据的小子集按需同步到本地应用与服务中从而避免把整库数据通过网络灌入本地设备Shapes 指南。sync() API 用法保持不变v0.10 中sync()API 的调用方式与此前一致const shape await db.projects.sync({ where: { id: abcd, }, include: { issues: true, }, }) await shape.synced但行为发生了本质变化v0.10 之前上述代码会同步projects和issues两张表的全部行占位实现 过度同步v0.10 之后只同步id abcd的那条 project 记录以及属于该项目的 issues 记录。这正是 Shape 设计意图的体现通过 where-clause 过滤行、通过 include-tree 关联相关表实现按需的动态部分复制dynamic partial replication把同步到本地设备的数据量降到最低。支持 SQL 字符串形式的 where 子句v0.10 还新增了以 SQL 字符串形式书写 where 子句的能力const { synced } await electric.db.issues.sync({ where: this.project_id in [7, 42], })这一能力将 Shape 同步的底层实现从底层 wire protocol 中暴露出来未来将支持更多的 Postgres 操作符。在后续版本中SQL 字符串 where 子句成为 Shape 定义的标准形态例如当前客户端支持位置参数TypeScript Client 文档const stream new ShapeStream({ url: http://localhost:3000/v1/shape, params: { table: issues, where: project_id $1, params: { 1: 7 }, // 或使用数组 [7] }, })使用位置占位符$1而非直接拼接用户输入可以避免 SQL 注入类问题——这一点在 Shapes 指南 中被明确推荐。底层实现where 子句是如何被解析与求值的从源码结构看where 子句的过滤链路在 packages/sync-service/lib/electric/replication/eval/ 目录下实现parser.ex 负责把 SQL 字符串解析为内部 ASTparse_query/1处理二进制查询最终通过parse_where_stmt提取:where_clause并构建求值环境见 parser.ex 中关于where_clause、parse_query与parse_where_stmt的实现decomposer.ex 将 where 子句分解为一组表达式列表外层列表是子表达式序列内层列表是逐个比较运算供后续求值器逐项判断filter/index.ex 则承载 Shape 过滤的索引化求值逻辑这正是后续优化 where 子句optimized where clauses能力的基础。where 子句的语法边界当前版本语义v0.10 允许的完整 SQL 语法以当时发布的 Shapes 文档 为准。结合当前仓库文档where 子句支持的要素包括Shapes 指南列类型数值类型、boolean、uuid、text、interval、日期时间类型timetz除外、数组操作符比较、、、、、、逻辑AND/OR/NOT、算术、字符串LIKE/ILIKE、数组包含、被包含、重叠、空值测试IS NULL/IS NOT NULL、成员关系IN/NOT IN、区间BETWEEN等位置占位符如$1参数值需与 where 子句一同提供子查询可用id IN (SELECT ...)基于其他表的数据过滤例如只同步属于某组织的用户约束不能使用非确定性 SQL 函数如count()、now()。当前文档也明确列出了暂不支持的操作符类别JSONB、全文检索、几何、网络地址、范围类型等并指出权威清单位于 parser.ex 与known_functions.ex。状态实验性experimental发布说明明确强调v0.10 中的 Shapes 仍是实验性功能。可以做到的用 where-clause 与 include-tree 过滤同步到本地设备的内容尚未实现的关键能力控制设备关闭同步sync off the device取消订阅unsubscribing。此外当时仍存在一定程度的过度同步——多对一关系many-to-one为了维护引用完整性会被同步进来详见 Shapes 文档中的 limitations 部分。:::caution Breaking changes 如果你此前依赖 Shape 过度同步的临时行为v0.10 之后需要更新你的 Shape 定义。 :::Blob 支持BYTEA 与基于 Blob 的数据库v0.10 为BYTEA列即 blobs增加了数据类型支持解锁了两类应用场景在数据库中存储大字符串和/或文件的应用使用 SQLite Blob 持久化数据的数据库——例如 CozoDB。借助 v0.10 的 Blob 支持可以用 Electric 在用户与设备之间同步 Cozo 数据把它变成多用户、实时的关系-图-向量数据库CREATE TABLE cozo ( k BLOB primary key, v BLOB ); ALTER TABLE cozo ENABLE ELECTRIC;启用 Electric 之后k/v两个 Blob 列即可通过 Shape 机制参与同步。Bug fixes 与其他改进与以往一样v0.10 同时包含若干 bug 修复与小的改进。发布说明建议查阅完整的 Release notes 获取所有更新组件的清单。从 v0.10 至今Shape 体系的演进v0.10 确立了Shape 过滤这一方向后续版本在其上持续演进当前语义见 Shapes 指南include-tree → 多 Shape 与子查询新版本中 Shape 为单表模型include-tree 尚未实现同步关联数据推荐使用多个 Shape 客户端 join或where 子查询的方式Shapes 指南columns 列投影新增columns参数只同步指定列必须包含主键进一步压缩同步体积queryable_columns限定客户端子集查询subsetwhere/order_by/columns可引用的列白名单服务端主 where 不受其限制优化 where 子句对field constant、field IN (list)、field IN (subquery)、array_field array_constant等子句做索引化求值使得吞吐量不再随 Shape 数量线性下降详见 benchmarks子查询增量维护子查询数据变化时行会自动移入/移出 Shape且对AND/OR/NOT复合表达式保持增量移动避免整 Shape 全量重同步。实践建议生产环境安全生产应用应通过后端 API 或代理请求 Shape用于鉴权与安全控制auth 指南同步体积控制优先组合使用 where 子句、columns与queryable_columns把同步到本地设备的行与列都压缩到最小用户输入过滤构造 where 子句时使用位置占位符$1并配合params传值避免 SQL 注入类风险数据吞吐where 子句求值会影响写入吞吐优先使用可被优化的子句形态等值、IN列表、IN (subquery)等以保持稳定吞吐。关键仓库路径索引发布说明原文website/blog/posts/2024-04-10-electricsql-v0.10-released.mdShapes 权威指南website/docs/sync/guides/shapes.mdTypeScript 客户端 APIwebsite/docs/sync/api/clients/typescript.mdHTTP APIShape Log / 子集快照website/docs/sync/api/http.mdwhere 子句解析器packages/sync-service/lib/electric/replication/eval/parser.exwhere 子句分解器packages/sync-service/lib/electric/replication/eval/decomposer.exShape 过滤索引packages/sync-service/lib/electric/shapes/filter/index.exShape API 服务端实现packages/sync-service/lib/electric/shapes/api.ex【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Electric v0.10 发布解析：Shape 过滤与 Blob 数据支持
Electric v0.10 发布解析Shape 过滤与 Blob 数据支持【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric本篇文章基于仓库中 2024-04-10 的官方发布说明website/blog/posts/2024-04-10-electricsql-v0.10-released.md深入解读 Electric v0.10 的两大核心能力真正可用的 Shape 过滤where-clause 与 include-tree以及BYTEA/Blob 数据类型支持。读者将掌握sync()API 的正确用法、SQL 字符串 where 子句的书写方式、底层过滤实现的原理以及从 v0.10 到当前版本 Shape 体系columns、queryable_columns、子查询、优化 where 子句的演进脉络。[!WARNING] 版本说明 本文描述的 v0.10 是 Electric 的早期版本该版本已不再活跃。发布说明原文亦附有提示当前架构的演进请参考仓库中后续的 website/blog/posts/ 系列发布文章与最新文档。当前最新 API 与语义以 Shapes 指南 和 TypeScript Client 文档 为准。发布概览v0.10 解决了什么v0.10 是 Electric 首次真正支持基于 Shape 的 where-clause 与 include-tree 过滤的版本。在此之前sync()API 虽然已经存在但其实现是一个占位实现——它会**过度同步over-sync**数据并且强制要求开发者把相关的表全部包含进来。这意味着开发者无法真正利用 Shape 机制去控制哪些数据同步到本地设备。v0.10 同时新增了对**字节数组与 BlobBYTEA列**的数据类型支持为后续支持存储大字符串、文件乃至基于 SQLite Blob 的数据库如 CozoDB铺平了道路。Shape 过滤让动态部分复制真正落地Shape 是 Electric 系统中控制云端与本地设备之间同步什么数据的关键原语。它把 Postgres 数据的小子集按需同步到本地应用与服务中从而避免把整库数据通过网络灌入本地设备Shapes 指南。sync() API 用法保持不变v0.10 中sync()API 的调用方式与此前一致const shape await db.projects.sync({ where: { id: abcd, }, include: { issues: true, }, }) await shape.synced但行为发生了本质变化v0.10 之前上述代码会同步projects和issues两张表的全部行占位实现 过度同步v0.10 之后只同步id abcd的那条 project 记录以及属于该项目的 issues 记录。这正是 Shape 设计意图的体现通过 where-clause 过滤行、通过 include-tree 关联相关表实现按需的动态部分复制dynamic partial replication把同步到本地设备的数据量降到最低。支持 SQL 字符串形式的 where 子句v0.10 还新增了以 SQL 字符串形式书写 where 子句的能力const { synced } await electric.db.issues.sync({ where: this.project_id in [7, 42], })这一能力将 Shape 同步的底层实现从底层 wire protocol 中暴露出来未来将支持更多的 Postgres 操作符。在后续版本中SQL 字符串 where 子句成为 Shape 定义的标准形态例如当前客户端支持位置参数TypeScript Client 文档const stream new ShapeStream({ url: http://localhost:3000/v1/shape, params: { table: issues, where: project_id $1, params: { 1: 7 }, // 或使用数组 [7] }, })使用位置占位符$1而非直接拼接用户输入可以避免 SQL 注入类问题——这一点在 Shapes 指南 中被明确推荐。底层实现where 子句是如何被解析与求值的从源码结构看where 子句的过滤链路在 packages/sync-service/lib/electric/replication/eval/ 目录下实现parser.ex 负责把 SQL 字符串解析为内部 ASTparse_query/1处理二进制查询最终通过parse_where_stmt提取:where_clause并构建求值环境见 parser.ex 中关于where_clause、parse_query与parse_where_stmt的实现decomposer.ex 将 where 子句分解为一组表达式列表外层列表是子表达式序列内层列表是逐个比较运算供后续求值器逐项判断filter/index.ex 则承载 Shape 过滤的索引化求值逻辑这正是后续优化 where 子句optimized where clauses能力的基础。where 子句的语法边界当前版本语义v0.10 允许的完整 SQL 语法以当时发布的 Shapes 文档 为准。结合当前仓库文档where 子句支持的要素包括Shapes 指南列类型数值类型、boolean、uuid、text、interval、日期时间类型timetz除外、数组操作符比较、、、、、、逻辑AND/OR/NOT、算术、字符串LIKE/ILIKE、数组包含、被包含、重叠、空值测试IS NULL/IS NOT NULL、成员关系IN/NOT IN、区间BETWEEN等位置占位符如$1参数值需与 where 子句一同提供子查询可用id IN (SELECT ...)基于其他表的数据过滤例如只同步属于某组织的用户约束不能使用非确定性 SQL 函数如count()、now()。当前文档也明确列出了暂不支持的操作符类别JSONB、全文检索、几何、网络地址、范围类型等并指出权威清单位于 parser.ex 与known_functions.ex。状态实验性experimental发布说明明确强调v0.10 中的 Shapes 仍是实验性功能。可以做到的用 where-clause 与 include-tree 过滤同步到本地设备的内容尚未实现的关键能力控制设备关闭同步sync off the device取消订阅unsubscribing。此外当时仍存在一定程度的过度同步——多对一关系many-to-one为了维护引用完整性会被同步进来详见 Shapes 文档中的 limitations 部分。:::caution Breaking changes 如果你此前依赖 Shape 过度同步的临时行为v0.10 之后需要更新你的 Shape 定义。 :::Blob 支持BYTEA 与基于 Blob 的数据库v0.10 为BYTEA列即 blobs增加了数据类型支持解锁了两类应用场景在数据库中存储大字符串和/或文件的应用使用 SQLite Blob 持久化数据的数据库——例如 CozoDB。借助 v0.10 的 Blob 支持可以用 Electric 在用户与设备之间同步 Cozo 数据把它变成多用户、实时的关系-图-向量数据库CREATE TABLE cozo ( k BLOB primary key, v BLOB ); ALTER TABLE cozo ENABLE ELECTRIC;启用 Electric 之后k/v两个 Blob 列即可通过 Shape 机制参与同步。Bug fixes 与其他改进与以往一样v0.10 同时包含若干 bug 修复与小的改进。发布说明建议查阅完整的 Release notes 获取所有更新组件的清单。从 v0.10 至今Shape 体系的演进v0.10 确立了Shape 过滤这一方向后续版本在其上持续演进当前语义见 Shapes 指南include-tree → 多 Shape 与子查询新版本中 Shape 为单表模型include-tree 尚未实现同步关联数据推荐使用多个 Shape 客户端 join或where 子查询的方式Shapes 指南columns 列投影新增columns参数只同步指定列必须包含主键进一步压缩同步体积queryable_columns限定客户端子集查询subsetwhere/order_by/columns可引用的列白名单服务端主 where 不受其限制优化 where 子句对field constant、field IN (list)、field IN (subquery)、array_field array_constant等子句做索引化求值使得吞吐量不再随 Shape 数量线性下降详见 benchmarks子查询增量维护子查询数据变化时行会自动移入/移出 Shape且对AND/OR/NOT复合表达式保持增量移动避免整 Shape 全量重同步。实践建议生产环境安全生产应用应通过后端 API 或代理请求 Shape用于鉴权与安全控制auth 指南同步体积控制优先组合使用 where 子句、columns与queryable_columns把同步到本地设备的行与列都压缩到最小用户输入过滤构造 where 子句时使用位置占位符$1并配合params传值避免 SQL 注入类风险数据吞吐where 子句求值会影响写入吞吐优先使用可被优化的子句形态等值、IN列表、IN (subquery)等以保持稳定吞吐。关键仓库路径索引发布说明原文website/blog/posts/2024-04-10-electricsql-v0.10-released.mdShapes 权威指南website/docs/sync/guides/shapes.mdTypeScript 客户端 APIwebsite/docs/sync/api/clients/typescript.mdHTTP APIShape Log / 子集快照website/docs/sync/api/http.mdwhere 子句解析器packages/sync-service/lib/electric/replication/eval/parser.exwhere 子句分解器packages/sync-service/lib/electric/replication/eval/decomposer.exShape 过滤索引packages/sync-service/lib/electric/shapes/filter/index.exShape API 服务端实现packages/sync-service/lib/electric/shapes/api.ex【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考