成为赞助商——支持中文 Agent 生态

了解赞助
库Agent场景库
← 返回用例列表

Turso Embedded Replicas 本地副本简报

按 url/syncUrl、读本地写远端、syncInterval/offline 与使用注意,整理嵌入式副本简报;不代持 authToken、不在无盘环境硬开。

场景说明

面向独立开发者:把「应用旁挂本地 SQLite 读副本并与 Turso Cloud 同步」写成可对账步骤,区别于 Cloudflare D1 Workers 绑定与 Neon 数据分支。

案例叙事

01他们做了什么

VPS 或弱网移动场景想要微秒级本地读,又要把写入汇到云端主库——Embedded Replicas 把远程库复制进应用进程旁的本地文件。

Turso Docs《Embedded Replicas》(dateModified 可核)说明:嵌入式副本在本地保留 Turso Cloud 数据库的只读副本;读从本地文件以微秒级服务,写默认发到云端主库再反映回副本;生产可用。文档同时提示:新项目若需要 sync,更推荐 Turso Sync(基于逻辑 CDC,本地优先写与显式 push/pull,带宽与延迟通常优于页级复制的 Embedded Replicas)。机制:配置本地文件为 url,远程库为 syncUrl;读始终来自本地;写默认发往 syncUrl(非先写本地),可读己之写(可关);可用 syncInterval 周期性同步,亦可手动 sync()。支持 encryptionKey 静态加密。用法上 TypeScript 等 SDK 传入 url/syncUrl/authToken(及可选 syncInterval、offline)。注意:同步过程中不要另开该本地库(可能损坏);无文件系统的 serverless 环境不能用;某些写入/重启/本地文件失效可能导致同步帧数多于预期;一帧约 4KB。本场景据此输出嵌入式副本简报。禁止回显 authToken 或声称「生产副本已同步完成」。

02实际效果

  • 源未披露量化「读延迟下降」;公开文只描述读写路径、同步选项与限制。
  • 能把「当 D1 用 / 在无盘函数里硬开 / 与 Neon 分支混淆」拆开。
  • 为 VPS/移动本地读加速提供可落地的配置提问清单。

03值得知道

  • 新项目文档更推荐 Turso Sync;选型前对照 Sync 专页,勿默认 Embedded Replicas 为唯一同步方案。
  • 各语言 SDK 构造函数参数名略有差异,以对应示例为准。
  • 上面写的是产品机制,不是你账号下数据库已同步字节数。

04可复制提示词

Turso Embedded Replicas 简报

你是 Turso Embedded Replicas 助手。只给本地副本核对简报,不要编造已同步成功。

部署形态:{{deploy_shape}}
是否有持久磁盘:{{has_disk}}
读写目标:{{rw_goal}}
是否考虑 Turso Sync:{{consider_sync}}

输出 Markdown:
1. url/syncUrl 与读写路径
2. syncInterval/offline/read-your-writes 提问
3. serverless 无盘是否直接不适用
4. 非生产验收步骤
禁止索要或回显 authToken;禁止声称生产已就绪。

同步异常/损坏风险提纲

本地副本不同步或怀疑文件损坏,请写排查提纲。

症状:{{symptom}}
是否同步时另开了本地库:{{opened_elsewhere}}
近期是否清过本地文件:{{wiped_local}}

输出:
1. 是否违反「同步中勿另开」
2. 是否应全量重同步
3. 是否场景本应改用 Sync
4. 人工验证顺序
不要伪造「数据已一致」;不要索要 token。

05一手来源

怎么做

  1. 粘贴部署形态(VPS/移动/是否 serverless 无盘)、读写延迟目标、是否需要 offline,以及是否已有远程库 URL
  2. Agent 按官方 Embedded Replicas 要点输出:本地 url + syncUrl→读写路径→定期 sync/read-your-writes→注意项与 Sync 推荐提问清单
  3. 人工用 libSQL 客户端配置;Agent 不回显 authToken、不在无文件系统环境声称「已启用副本」

实用提示

  • 默认写走远程主库,成功后再反映到本地;offline: true 才可先写本地。同步中勿另开同一本地库文件,以免损坏
  • 与 cloudflare-d1-sqlite-workers-brief / neon-database-branching-brief 不同:本条是应用内嵌入式读副本+云端主库同步,不是 Workers 托管 SQLite,也不是 Neon CoW 分支
#Turso#Embedded Replicas#libSQL#SQLite#独立开发者