尧图网页设计 
从一次数据获取到本地嵌入式数据库解读 Electric 官网 CTA 中的渐进式同步路线【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric导读home-cta.md 是 Electric 官网首页底部的行动引导区块它浓缩了该项目两条核心落地路径一条是渐进式采纳——通过 HTTP API、客户端库与框架 Hooks 一次数据获取、逐步接入另一条是升级路径——将数据同步到浏览器本地嵌入式 PGlite 数据库配合持久化与实时响应查询获得完整的 local-first 体验。本文将以这份 CTA 为骨架结合仓库中electric-sql/react与sync-into-pglite.tsx的实现拆解这两条路线的原理与实战细节。CTA 在官网中的角色渐进式采纳的信息架构在website/old-index.md中可以看到HomeCTA被导入并渲染在.home-cta容器内old-index.md 与 old-index.md。它位于首页特性介绍与用户案例之后起到收束行动的作用。整段 CTA 的逻辑结构是起步极轻You can start by adopting Electric incrementally, one data fetch at a time——强调可以增量采纳一次数据获取即可开始。三条接入通道HTTP APIAPI 文档、TypeScript 客户端库TypeScript client、框架 HooksReact 集成。升级路径you can level-up all the way to syncing into a local embedded PGlite database——从单次请求升级为本地嵌入式数据库内的持续同步。这种先轻后重的设计对应 Electric Sync 的核心模型通过名为Shape的原语把 Postgres 数据的小子集同步到本地客户端见 Sync 文档。Shape 既可被 HTTP 流式消费也可落进本地 PGlite正是 CTA 两条路径的底层支撑。路径一用useShape一次数据获取接入CTA 首先展示的是 React 场景下最直接的接入方式import { useShape } from electric-sql/react const Component () { const { data } useShape({ url: ${BASE_URL}/v1/shape, params: { table: items } }) return ( pre{ JSON.stringify(data) }pre ) }useShape做了什么useShape定义在 packages/react-hooks/src/react-hooks.tsx#L164-L211。它的核心流程是调用getShapeStream(options)获取或创建一个ShapeStreamHTTP 层负责从/v1/shape拉取并持续订阅数据变更调用getShape(shapeStream)获取或创建一个Shape把流式日志物化为行数组通过useSyncExternalStoreWithSelector订阅Shape的变化并把结果映射为UseShapeResult返回。UseShapeResult接口react-hooks.tsx#L92-L114包含data: T[]—— 物化后的行数组CTA 示例中的JSON.stringify(data)输出的正是它shape: ShapeT与stream: ShapeStreamT—— 当前 Shape 及其底层流isLoading: boolean—— 初始拉取期间为truelastSyncedAt?: number—— 最近一次同步完成的 Unix 时间戳isError与error—— 错误状态与错误对象。parseShapeDatareact-hooks.tsx#L126-L138把这些字段从Shape实例中解出其中data直接取shape.currentRowsisLoading取shape.isLoading()。全局缓存避免重复消费CTA 强调一次数据获取而getShapeStream/getShape内部的全局缓存让这一点更扎实streamCache以sortedOptionsHash(options)为键缓存ShapeStreamreact-hooks.tsx#L47-L69shapeCache以流实例为键缓存Shapereact-hooks.tsx#L71-L90。多个组件使用相同参数时会共享同一条流、同一个物化 Shape不会为同一份 Shape 日志重复建立连接。preloadShapereact-hooks.tsx#L17-L24则用于路由加载阶段提前把数据物化好等待shape.rows就绪后再渲染组件。连接方式直接连接与 API 代理CTA 中url直接指向${BASE_URL}/v1/shape这是开发环境最直接的用法。React 集成文档 对此有更完整的说明直接连接仅开发如url: http://localhost:3000/v1/shape, params: { table: items }直接连 Electric 的 Shape 端点生产推荐走后端 API 代理如url: http://localhost:3001/api/items由你的 API 转发请求从而把安全、鉴权、统一接口收敛到后端避免暴露数据库结构PostgreSQL 参数params中还可追加where: status active做行过滤、columns: [id, title]做列裁剪控制同步子集的大小。订阅控制react-hooks 文档 还给出了用AbortController在组件卸载时中止订阅的写法signal会被传入ShapeStreamOptions若同一流的共享订阅被 abortgetShapeStream会把对应缓存项清理掉见 react-hooks.tsx#L53-L62。路径二升级到 PGlite——本地嵌入式数据库同步CTA 的第二段是关键升级路径把数据同步进浏览器本地嵌入的 PGlite 数据库。PGlite 是 WASM 版 Postgres可在浏览器、Node.js 与边缘环境运行见 PGlite 页面。CTA 强调两点能力内置持久化PGlite 文件系统与实时响应live queries。CTA 引用的完整示例来自sync-into-pglite.tsx共四个步骤import { PGlite } from electric-sql/pglite import { live } from electric-sql/pglite/live import { electricSync } from electric-sql/pglite-sync import { useLiveQuery } from electric-sql/pglite-react // 1. 创建持久化的本地 PGlite 数据库 const pg await PGlite.create({ dataDir: idb://my-database, extensions: { electric: electricSync(), live, }, }) // 2. 建立本地数据库 schema await pg.exec( CREATE TABLE IF NOT EXISTS items ( id SERIAL PRIMARY KEY, ); ) // 3. 建立持续的 Shape 订阅 await pg.electric.syncShapeToTable({ shape: { url: ${BASE_URL}/v1/shape }, table: items, primaryKey: [id], }) // 4. 用 live query 把本地数据绑定到组件 const Component () { const items useLiveQuery(SELECT * FROM items;) return pre{JSON.stringify(items)}/pre }关键配置逐项说明dataDir: idb://my-databasePGlite 的文件系统挂载点。idb://前缀表示持久化到浏览器 IndexedDB配合 PGlite 的文件系统抽象实现数据在刷新后的留存这是 CTA 中 built-in persistence 的落点。对应文件系统能力见仓库中的 PGlite 相关用法。extensions.electric: electricSync()注册 Electric 同步扩展在本地数据库中启用syncShapeToTable等同步能力。extensions.live注册 live query 扩展是第 4 步useLiveQuery能够对本地数据做响应式查询的前提。CREATE TABLE IF NOT EXISTS items (id SERIAL PRIMARY KEY)先建好与 Shape 数据对齐的本地表结构。syncShapeToTable({ shape, table, primaryKey })把远端 Shape/v1/shape持续同步到本地items表primaryKey用于本地物化时的行去重与更新。useLiveQuery(SELECT * FROM items;)以 SQL 查询本地表返回随本地数据变化自动更新的响应式结果——这正是 CTA 中 live reactivity 的体现。注意一个细节CTA 中的useShape示例与 PGlite 示例都指向${BASE_URL}/v1/shape说明两条路径消费的是同一个 HTTP Shape 协议HTTP API——差别只在于数据最终停留在组件内存还是本地数据库。从源码看升级路径的意义在website/index.md的首页模板中还保留了works-with-sql-template与works-with-sse-template两段隐藏模板index.md一段是 SQL 写入示例INSERT INTO todos VALUES (sync)一段是 SSE 流式数据示例data: {type: text-delta, delta: Hi, }。这说明项目首页想传达的是Electric 同步生态既覆盖 SQL 式的数据写入路径也覆盖流式事件路径。而 PGlite 路线正是把SQL 可查询与实时同步合二为一的载体——本地数据既可用SELECT任意查询又保持与 Postgres 的持续一致。渐进式路线如何映射到仓库示例CTA 的先一次数据获取、再升级到 PGlite路线在仓库示例中有直接对应物轻量接入示例examples/react下的Example.tsx展示了用 React Hooks 消费 Shape 数据的最小化应用对应 CTA 的第一段完整 PGlite 示例examples/linearlite与examples/linearlite-read-only把 Issue 跟踪这类真实业务搬进了本地嵌入式数据库对应 CTA 的升级段其electric.tsx里能看到PGlite、electricSync与 live query 的完整装配方式。以 examples/linearlite/src/electric.tsx 为对照可以验证 CTA 中sync-into-pglite.tsx的四步装配创建数据库 → 建表 → 注册同步 → 响应式查询就是生产级示例的简化版核心 API 与参数完全一致只是少了真实业务表与 UI 层。落地清单最小接入npm i electric-sql/react然后用useShape({ url: BASE_URL /v1/shape, params: { table } })在组件内声明式获取数据官方 Quickstartwebsite/docs/sync/quickstart.md可在几分钟内跑通端到端同步生产建议把url指向自己的后端 API 代理而不是直连 Electric 端点用where/columns参数裁剪同步子集升级到 PGlite安装electric-sql/pglite、electric-sql/pglite-sync、electric-sql/pglite-react按sync-into-pglite.tsx四步装配把 Shape 落进idb://持久化的本地库再用useLiveQuery绑定组件进阶级在路由加载时用preloadShape提前物化数据多个组件共享同一 Shape 时依赖全局缓存避免重复建流。总结home-cta.md用极简篇幅勾勒了 Electric 的一条完整采纳曲线从一次数据获取的 HTTP Shape 接入到本地嵌入式 PGlite 数据库 持久化 live query的 local-first 形态。两条路径共享同一个/v1/shape协议区别仅在于数据终态——这也正是仓库docs/agents-development.md所强调的 agent 平台定位同步能力可以按需渐进注入而不必一次性推翻现有架构。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 从一次数据获取到本地嵌入式数据库：解读 Electric 官网 CTA 中的渐进式同步路线
从一次数据获取到本地嵌入式数据库解读 Electric 官网 CTA 中的渐进式同步路线【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric导读home-cta.md 是 Electric 官网首页底部的行动引导区块它浓缩了该项目两条核心落地路径一条是渐进式采纳——通过 HTTP API、客户端库与框架 Hooks 一次数据获取、逐步接入另一条是升级路径——将数据同步到浏览器本地嵌入式 PGlite 数据库配合持久化与实时响应查询获得完整的 local-first 体验。本文将以这份 CTA 为骨架结合仓库中electric-sql/react与sync-into-pglite.tsx的实现拆解这两条路线的原理与实战细节。CTA 在官网中的角色渐进式采纳的信息架构在website/old-index.md中可以看到HomeCTA被导入并渲染在.home-cta容器内old-index.md 与 old-index.md。它位于首页特性介绍与用户案例之后起到收束行动的作用。整段 CTA 的逻辑结构是起步极轻You can start by adopting Electric incrementally, one data fetch at a time——强调可以增量采纳一次数据获取即可开始。三条接入通道HTTP APIAPI 文档、TypeScript 客户端库TypeScript client、框架 HooksReact 集成。升级路径you can level-up all the way to syncing into a local embedded PGlite database——从单次请求升级为本地嵌入式数据库内的持续同步。这种先轻后重的设计对应 Electric Sync 的核心模型通过名为Shape的原语把 Postgres 数据的小子集同步到本地客户端见 Sync 文档。Shape 既可被 HTTP 流式消费也可落进本地 PGlite正是 CTA 两条路径的底层支撑。路径一用useShape一次数据获取接入CTA 首先展示的是 React 场景下最直接的接入方式import { useShape } from electric-sql/react const Component () { const { data } useShape({ url: ${BASE_URL}/v1/shape, params: { table: items } }) return ( pre{ JSON.stringify(data) }pre ) }useShape做了什么useShape定义在 packages/react-hooks/src/react-hooks.tsx#L164-L211。它的核心流程是调用getShapeStream(options)获取或创建一个ShapeStreamHTTP 层负责从/v1/shape拉取并持续订阅数据变更调用getShape(shapeStream)获取或创建一个Shape把流式日志物化为行数组通过useSyncExternalStoreWithSelector订阅Shape的变化并把结果映射为UseShapeResult返回。UseShapeResult接口react-hooks.tsx#L92-L114包含data: T[]—— 物化后的行数组CTA 示例中的JSON.stringify(data)输出的正是它shape: ShapeT与stream: ShapeStreamT—— 当前 Shape 及其底层流isLoading: boolean—— 初始拉取期间为truelastSyncedAt?: number—— 最近一次同步完成的 Unix 时间戳isError与error—— 错误状态与错误对象。parseShapeDatareact-hooks.tsx#L126-L138把这些字段从Shape实例中解出其中data直接取shape.currentRowsisLoading取shape.isLoading()。全局缓存避免重复消费CTA 强调一次数据获取而getShapeStream/getShape内部的全局缓存让这一点更扎实streamCache以sortedOptionsHash(options)为键缓存ShapeStreamreact-hooks.tsx#L47-L69shapeCache以流实例为键缓存Shapereact-hooks.tsx#L71-L90。多个组件使用相同参数时会共享同一条流、同一个物化 Shape不会为同一份 Shape 日志重复建立连接。preloadShapereact-hooks.tsx#L17-L24则用于路由加载阶段提前把数据物化好等待shape.rows就绪后再渲染组件。连接方式直接连接与 API 代理CTA 中url直接指向${BASE_URL}/v1/shape这是开发环境最直接的用法。React 集成文档 对此有更完整的说明直接连接仅开发如url: http://localhost:3000/v1/shape, params: { table: items }直接连 Electric 的 Shape 端点生产推荐走后端 API 代理如url: http://localhost:3001/api/items由你的 API 转发请求从而把安全、鉴权、统一接口收敛到后端避免暴露数据库结构PostgreSQL 参数params中还可追加where: status active做行过滤、columns: [id, title]做列裁剪控制同步子集的大小。订阅控制react-hooks 文档 还给出了用AbortController在组件卸载时中止订阅的写法signal会被传入ShapeStreamOptions若同一流的共享订阅被 abortgetShapeStream会把对应缓存项清理掉见 react-hooks.tsx#L53-L62。路径二升级到 PGlite——本地嵌入式数据库同步CTA 的第二段是关键升级路径把数据同步进浏览器本地嵌入的 PGlite 数据库。PGlite 是 WASM 版 Postgres可在浏览器、Node.js 与边缘环境运行见 PGlite 页面。CTA 强调两点能力内置持久化PGlite 文件系统与实时响应live queries。CTA 引用的完整示例来自sync-into-pglite.tsx共四个步骤import { PGlite } from electric-sql/pglite import { live } from electric-sql/pglite/live import { electricSync } from electric-sql/pglite-sync import { useLiveQuery } from electric-sql/pglite-react // 1. 创建持久化的本地 PGlite 数据库 const pg await PGlite.create({ dataDir: idb://my-database, extensions: { electric: electricSync(), live, }, }) // 2. 建立本地数据库 schema await pg.exec( CREATE TABLE IF NOT EXISTS items ( id SERIAL PRIMARY KEY, ); ) // 3. 建立持续的 Shape 订阅 await pg.electric.syncShapeToTable({ shape: { url: ${BASE_URL}/v1/shape }, table: items, primaryKey: [id], }) // 4. 用 live query 把本地数据绑定到组件 const Component () { const items useLiveQuery(SELECT * FROM items;) return pre{JSON.stringify(items)}/pre }关键配置逐项说明dataDir: idb://my-databasePGlite 的文件系统挂载点。idb://前缀表示持久化到浏览器 IndexedDB配合 PGlite 的文件系统抽象实现数据在刷新后的留存这是 CTA 中 built-in persistence 的落点。对应文件系统能力见仓库中的 PGlite 相关用法。extensions.electric: electricSync()注册 Electric 同步扩展在本地数据库中启用syncShapeToTable等同步能力。extensions.live注册 live query 扩展是第 4 步useLiveQuery能够对本地数据做响应式查询的前提。CREATE TABLE IF NOT EXISTS items (id SERIAL PRIMARY KEY)先建好与 Shape 数据对齐的本地表结构。syncShapeToTable({ shape, table, primaryKey })把远端 Shape/v1/shape持续同步到本地items表primaryKey用于本地物化时的行去重与更新。useLiveQuery(SELECT * FROM items;)以 SQL 查询本地表返回随本地数据变化自动更新的响应式结果——这正是 CTA 中 live reactivity 的体现。注意一个细节CTA 中的useShape示例与 PGlite 示例都指向${BASE_URL}/v1/shape说明两条路径消费的是同一个 HTTP Shape 协议HTTP API——差别只在于数据最终停留在组件内存还是本地数据库。从源码看升级路径的意义在website/index.md的首页模板中还保留了works-with-sql-template与works-with-sse-template两段隐藏模板index.md一段是 SQL 写入示例INSERT INTO todos VALUES (sync)一段是 SSE 流式数据示例data: {type: text-delta, delta: Hi, }。这说明项目首页想传达的是Electric 同步生态既覆盖 SQL 式的数据写入路径也覆盖流式事件路径。而 PGlite 路线正是把SQL 可查询与实时同步合二为一的载体——本地数据既可用SELECT任意查询又保持与 Postgres 的持续一致。渐进式路线如何映射到仓库示例CTA 的先一次数据获取、再升级到 PGlite路线在仓库示例中有直接对应物轻量接入示例examples/react下的Example.tsx展示了用 React Hooks 消费 Shape 数据的最小化应用对应 CTA 的第一段完整 PGlite 示例examples/linearlite与examples/linearlite-read-only把 Issue 跟踪这类真实业务搬进了本地嵌入式数据库对应 CTA 的升级段其electric.tsx里能看到PGlite、electricSync与 live query 的完整装配方式。以 examples/linearlite/src/electric.tsx 为对照可以验证 CTA 中sync-into-pglite.tsx的四步装配创建数据库 → 建表 → 注册同步 → 响应式查询就是生产级示例的简化版核心 API 与参数完全一致只是少了真实业务表与 UI 层。落地清单最小接入npm i electric-sql/react然后用useShape({ url: BASE_URL /v1/shape, params: { table } })在组件内声明式获取数据官方 Quickstartwebsite/docs/sync/quickstart.md可在几分钟内跑通端到端同步生产建议把url指向自己的后端 API 代理而不是直连 Electric 端点用where/columns参数裁剪同步子集升级到 PGlite安装electric-sql/pglite、electric-sql/pglite-sync、electric-sql/pglite-react按sync-into-pglite.tsx四步装配把 Shape 落进idb://持久化的本地库再用useLiveQuery绑定组件进阶级在路由加载时用preloadShape提前物化数据多个组件共享同一 Shape 时依赖全局缓存避免重复建流。总结home-cta.md用极简篇幅勾勒了 Electric 的一条完整采纳曲线从一次数据获取的 HTTP Shape 接入到本地嵌入式 PGlite 数据库 持久化 live query的 local-first 形态。两条路径共享同一个/v1/shape协议区别仅在于数据终态——这也正是仓库docs/agents-development.md所强调的 agent 平台定位同步能力可以按需渐进注入而不必一次性推翻现有架构。【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考