Syncular 0.5.0 – 基于 TypeScript 和 Rust 核心的离线优先 SQL 同步

概述

Syncular 0.5.0 提供离线优先的 SQL 同步，每个客户端都维护一个真实的本地 SQLite 数据库，并且写入操作通过一个乐观的输出箱（outbox）进行持久化，随后由服务器权威的提交日志（commit log）进行验证和排序。

该项目是自托管的，处于 pre‑1.0 阶段，不提供托管服务或点对点（peer‑to‑peer）模式。不同生态系统的原生打包成熟度各不相同。

架构

客户端将数据存储在真实的 SQLite 数据库中：在浏览器中由 Origin Private File System (OPFS) 支持的 sqlite-wasm，在其他地方则是原生 SQLite。所有写入操作都会在本地应用，并同时在同一个事务中记录到持久化的输出箱（outbox）中。服务器维护一个单一的有序提交日志，作为事实来源（source of truth），验证传入的更改，并使用应用程序后端定义的显式作用域进行解析。

协议与规范优先方法

Syncular 的协议在 SPEC.md 中独立于其实现进行了规范说明，spec/vectors/ 中的黄金字节向量（golden byte vectors）作为规范参考。当规范与代码出现分歧时，会调整代码以符合规范。协议草案命名为 SSP2，包含一种规范的二进制编码。

两个独立的内核——一个用 TypeScript 编写，另一个用 Rust 编写——通过一个与实现无关的合规性测试套件保持同步，该测试套件会对两种实现运行 95 个场景。

客户端核心与绑定

TypeScript 核心驱动 Web 客户端 (@syncular/client)，它运行在 @sqlite.org/sqlite-wasm 上。Rust 核心通过 Swift、Kotlin、Flutter、React Native、Tauri、原生 Rust 以及一个小型 C API 的语言绑定进行暴露。

这些绑定允许开发者将 Syncular 集成到原生移动端和桌面端应用程序中，同时共享相同的同步逻辑。

关键特性

  • 通过 WebSocket 进行实时同步，并带有可恢复的引导分段（bootstrap segments），以实现高效的初始同步。
  • 记录显式的冲突证据，以帮助应用程序理解并解析分歧的更改。
  • 授权撤销和本地清除功能，允许移除用户的权限并从客户端删除其数据。
  • 窗口化副本（Windowed replicas）允许客户端仅根据定义的范围同步数据子集。
  • 支持二进制大对象（blobs）以及常规 SQL 数据。
  • 提供可选的 CRDT 列，由位于 packages/crdt-yjs 目录下的基于 Yjs 的合并器支持。
  • 每列加密为选定字段提供端到端机密性。
  • 通过 typegen 包为五种语言提供类型安全的查询生成，该包从共享的中间表示（intermediate representation）生成模式感知（schema‑aware）的辅助函数。

开发实践

Syncular 遵循规范优先的方法论：规范是正确性的仲裁者。测试准则要求集成测试使用回环内存传输，在传输层进行故障注入，并提供显式的就绪信号——测试中禁止使用 sleep。真实的套接字（real-socket）测试是有限的且被隔离的。

该仓库鼓励“一条好的路径”：浏览器持久化到 OPFS，并将不支持的环境报告为错误，而同步通过 WebSocket 进行。

关于 AI 辅助，项目的贡献指南指出，欢迎使用大语言模型来编写测试、复现过程、基准测试、文档和生产代码，前提是每一行代码都经过了审查、理解并准备好进行辩护；低质量的机器生成贡献将被直接关闭且不予评论。

部署与限制

截至最新版本（v0.5.0, 2026 年 7 月 14 日），Syncular 仍处于 pre‑1.0 阶段。它仅设计用于自托管部署；不提供托管服务或点对点模式。README 中提到，原生打包的成熟度在不同生态系统中仍有差异，这意味着某些语言绑定可能比其他绑定更成熟。

社区问题与作者回复

  • SQL 中的 CRDT 处理：作者指出，Syncular 提供的可选 CRDT 列是通过 Yjs 合并器实现的，允许应用程序针对特定字段选择使用无冲突复制数据类型（CRDT），同时保持数据模型其余部分的关联性。

  • 冲突解析：Syncular 不使用自动冲突解析算法，而是记录显式的冲突证据，将解析策略留给应用程序开发者。

  • 与 PowerSync 的比较：作者并未提供直接比较；项目的文档中未提及 PowerSync。

  • 浏览器存储驱逐：作者确认了待处理的写入操作存储在由 OPFS 支持的 SQLite 数据库中，但并未说明该库是否请求了持久性存储，或者是否会警告用户关于输出箱（outbox）可能被驱逐的情况。

  • LLM 的使用：作者表示，在 Syncular 的开发过程中，LL，主要用于编写测试和迭代技术概念，并遵循与所有贡献一样严格的审查标准。

这些观点直接取自仓库的 README、发布说明以及作者在 Hacker News 帖子上的评论。

结论

Syncular 0.5.0 交付了一个规范驱动、离线优先的 SQL 同步解决方案，具有 TypeScript 和 Rust 运行时，双内核架构，持久化的输出箱模型，以及从加密列到可选 CRDT 支持的一系列特性，旨在为那些需要自托管、具备实时同步能力且不依赖于托管服务的开发者提供支持。

Sources