在底层，SQLite Sync 使用了 设计的高级CRDT（无冲突复制数据类型） 算法和数据结构 专为协作分布式系统 。这意味着：

• 即使没有网络连接，设备也可以独立更新数据。
• 当它们重新连接时，所有更改都会 自动合并并且不会发生冲突 。
• 无数据丢失。无覆盖。无需手动解决冲突。

简单来说，CRDT 使多个用户可以 同时 从任何地方编辑共享数据，并且一切正常。

目录

• 主要特点
• 内置网络层
• 行级安全性
• 您可以使用 SQLite Sync 构建什么？
• 文档
• 安装
• 入门
• 数据库架构建议 主键要求
• 列约束指南
• UNIQUE 约束注意事项
• 外键兼容性
• 触发器兼容性
• 执照

主要特点

• 离线优先设计 ：即使设备离线也能流畅运行。更改会在本地排队，并在连接恢复时自动同步。
• 基于 CRDT 的冲突解决 ：确定性且高效地合并更新，确保所有副本的最终一致性，而无需复杂的合并逻辑。
• 嵌入式网络层 ：无需外部库或同步服务器。SQLiteSync 内部处理连接设置、消息编码、重试和状态协调。
• 简单易用 ：只需将扩展加载到 SQLite 即可开始同步。无需实现自定义协议或状态机。
• 高效且有弹性 ：优化的二进制编码、自动批处理和强大的重试逻辑使得即使在不稳定的网络上也能快速可靠地实现同步。

无论您构建的是移动应用程序、物联网设备还是桌面工具，SQLite Sync 都能简化分布式数据管理，并在分散环境中充分发挥 SQLite 的潜力。

内置网络层

与需要您构建和维护复杂后端的传统同步系统不同， SQLite Sync 包含一个开箱 即用的内置网络层：

• 将您的数据库与云同步 使用单个函数调用 。
• 兼容。 语言或框架 与任何支持 SQLite 的
• 无需后端设置 - SQLite Sync 为您处理网络、更改跟踪和冲突解决。

同步层与 SQLite Cloud 紧密集成，实现跨设备、跨用户、跨平台的无缝安全数据共享。您可以轻松享受云同步的强大功能，而无需担心复杂性。

行级安全性

得益于底层 SQLite Cloud 基础架构， SQLite Sync 支持行级安全性 (RLS) 定义 - 允许您在行级别 精确的访问控制：

• 不仅控制谁可以读取或写入表，还控制 哪些特定行。 他们可以访问
• 在服务器上实施安全策略——无需客户端过滤。

例如：

• 用户A只能查看和编辑自己的数据。
• 用户 B 可以访问不同的行集 — 即使在同一个共享表中。

RLS 的好处 ：

• 数据隔离 ：确保用户只能访问他们被授权查看的内容。
• 内置隐私 ：安全策略在数据库级别实施。
• 简化开发 ：减少或消除应用程序代码中的复杂权限逻辑。

您可以使用 SQLite Sync 构建什么？

SQLite Sync 非常适合跨 Web、移动、桌面和边缘平台构建协作式分布式应用。一些示例用例包括：

📋 生产力与协作

• 共享待办事项列表 ：用户独立更新任务并轻松同步。
• 笔记应用程序 ：实时协作，离线编辑。
• Markdown 编辑器 ：离线工作，重新上线时同步 - 无冲突。

📱 移动和边缘

• 现场数据收集 ：用于远程检查、农业或调查。
• 销售点系统 ：具有同步库存的线下优先零售解决方案。
• 健康与健身应用程序 ：通过强大的隐私控制跨设备同步数据。

🏢 企业工作流程

• CRM 系统 ：通过行级访问控制同步每个用户的潜在客户和客户。
• 项目管理工具 ：离线友好的规划和任务管理。
• 费用追踪器 ：安全、自动地同步团队费用。

🧠 个人应用

• 日志和日记 ：跨设备同步的私人加密条目。
• 书签和阅读列表 ：个人或协作内容管理。
• 习惯追踪器 ：同步进度，确保数据安全和一致。

🌍 多用户、多租户系统

• SaaS 平台 ：每个用户或团队的行级访问。
• 协作设计工具 ：离线合并视觉编辑和注释。
• 教育应用程序 ：共享学习内容，并控制每个学生的访问。

文档

有关所有可用函数、其参数和示例的详细信息，请参阅 全面的 API 参考 。

安装

预构建的二进制文件

页面下载适合您平台的预构建二进制文件 从官方发布 ：

• Linux：x86 和 ARM
• macOS：x86 和 ARM
• Windows：x86
• 安卓
• iOS

WASM 版本

您可以从以下位置下载启用了 SQLite Sync 扩展的 WebAssembly (WASM) 版本的 SQLite： https://www.npmjs.com/package/@sqliteai/sqlite-wasm

Swift 包

您可以 将此存储库作为包依赖项添加到您的 Swift 项目中 的步骤 4 和 5 设置 SQLite 并支持扩展加载 。添加包后，您需要按照本指南 。

以下是如何使用该包的示例：

import CloudSync<
>>
...
var db: OpaquePointer?
sqlite3_open(":memory:", &db)
sqlite3_enable_load_extension(db, 1)
var errMsg: UnsafeMutablePointer<Int8>? = nil
sqlite3_load_extension(db, CloudSync.path, nil, &errMsg)
var stmt: OpaquePointer?
sqlite3_prepare_v2(db, "SELECT cloudsync_version()", -1, &stmt, nil)
defer { sqlite3_finalize(stmt) }
sqlite3_step(stmt)
log("cloudsync_version(): \(String(cString: sqlite3_column_text(stmt, 0)))")
sqlite3_close(db)

加载扩展
-- In SQLite CLI
.load ./cloudsync
-- In SQL
SELECT load_extension('./cloudsync');

入门
以下是开始使用 SQLite Sync 的简单示例：
先决条件
SQLite Cloud 帐户 注册 ：在SQLite Cloud 
SQLite 同步扩展 下载 ：从发布版本 
SQLite 云设置
中创建新项目和数据库 在SQLite Cloud Dashboard 
从仪表板复制连接字符串和 API 密钥
在本地和云数据库中创建具有相同模式的表
启用同步：单击 数据库的“OffSync” 按钮，然后选择要同步的每个表
本地数据库设置
# Start SQLite CLI
sqlite3 myapp.db

-- Load the extension
.load ./cloudsync
-- Create a table (primary key MUST be TEXT for global uniqueness)
CREATE TABLE IF NOT EXISTS my_data (
    id TEXT PRIMARY KEY NOT NULL,
    value TEXT NOT NULL DEFAULT '',
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);
-- Initialize table for synchronization
SELECT cloudsync_init('my_data');
-- Use your local database normally: read and write data using standard SQL queries
-- The CRDT system automatically tracks all changes for synchronization
-- Example: Insert data (always use cloudsync_uuid() for globally unique IDs)
INSERT INTO my_data (id, value) VALUES 
    (cloudsync_uuid(), 'Hello from device A!'),
    (cloudsync_uuid(), 'Working offline is seamless!');
-- Example: Update and delete operations work normally
UPDATE my_data SET value = 'Updated: Hello from device A!' WHERE value LIKE 'Hello from device A!';
-- View your data
SELECT * FROM my_data ORDER BY created_at;
-- Configure network connection before using the network sync functions
SELECT cloudsync_network_init('sqlitecloud://your-project-id.sqlite.cloud/database.sqlite');
SELECT cloudsync_network_set_apikey('your-api-key-here');
-- Or use token authentication (required for Row-Level Security)
-- SELECT cloudsync_network_set_token('your_auth_token');
-- Sync with cloud: send local changes, then check the remote server for new changes 
-- and, if a package with changes is ready to be downloaded, applies them to the local database
SELECT cloudsync_network_sync();
-- Keep calling periodically. The function returns > 0 if data was received
-- In production applications, you would typically call this periodically
-- rather than manually (e.g., every few seconds)
SELECT cloudsync_network_sync();
-- Before closing the database connection
SELECT cloudsync_terminate();
-- Close the database connection
.quit

-- On another device (or create another database for testing: sqlite3 myapp_2.db)
-- Follow the same setup steps: load extension, create table, init sync, configure network
-- Load extension and create identical table structure
.load ./cloudsync
CREATE TABLE IF NOT EXISTS my_data (
    id TEXT PRIMARY KEY NOT NULL,
    value TEXT NOT NULL DEFAULT '',
    created_at TEXT DEFAULT CURRENT_TIMESTAMP
);
SELECT cloudsync_init('my_data');
-- Connect to the same cloud database
SELECT cloudsync_network_init('sqlitecloud://your-project-id.sqlite.cloud/database.sqlite');
SELECT cloudsync_network_set_apikey('your-api-key-here');
-- Sync to get data from the first device 
SELECT cloudsync_network_sync();
-- repeat until data is received (returns > 0)
SELECT cloudsync_network_sync();
-- View synchronized data
SELECT * FROM my_data ORDER BY created_at;
-- Add data from this device to test bidirectional sync
INSERT INTO my_data (id, value) VALUES 
    (cloudsync_uuid(), 'Hello from device B!');
-- Sync again to send this device's changes
SELECT cloudsync_network_sync();
-- The CRDT system ensures all devices eventually have the same data,
-- with automatic conflict resolution and no data loss
-- Before closing the database connection
SELECT cloudsync_terminate();
-- Close the database connection
.quit

完整示例
请参阅 示例 目录以获得全面的演练，其中包括：
多设备协作
离线场景
行级安全设置
冲突解决示威
📦集成
同时使用 SQLite-AI：
SQLite-AI  – 设备上推理、嵌入生成和模型交互直接进入数据库
SQLite-Vector  – 从 SQL 进行向量搜索
SQLite-JS  – 在 JavaScript 中定义 SQLite 函数
数据库架构建议
在为 SQLite Sync 设计数据库模式时，请遵循以下最佳实践以确保最佳的 CRDT 性能和冲突解决：
主键要求
使用全局唯一标识符 ：始终使用带有 UUID、ULID 或类似的全局唯一标识符的 TEXT 主键
避免自动递增整数 ：整数主键可能会导致跨多个设备发生冲突
使用 cloudsync_uuid()：内置函数生成针对分布式系统优化的 UUIDv7 标识符
所有主键必须明确声明为 NOT NULL。
-- ✅ Recommended: Globally unique TEXT primary key
CREATE TABLE users (
    id TEXT PRIMARY KEY NOT NULL,          -- Use cloudsync_uuid()
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL
);
-- ❌ Avoid: Auto-incrementing integer primary key
CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,  -- Causes conflicts
    name TEXT NOT NULL,
    email TEXT UNIQUE NOT NULL
);

列约束指南
提供默认值 ：全部 NOT NULL列（主键除外）必须具有 DEFAULT价值观
考虑可空列 ：对于可选数据，使用可空列而不是空字符串
-- ✅ Recommended: Proper constraints and defaults
CREATE TABLE tasks (
    id TEXT PRIMARY KEY,
    title TEXT NOT NULL DEFAULT '',
    status TEXT NOT NULL DEFAULT 'pending',
    priority INTEGER NOT NULL DEFAULT 1,
    created_at INTEGER NOT NULL DEFAULT (strftime('%s', 'now')),
    assigned_to TEXT                       -- Nullable for optional assignment
);

UNIQUE 约束注意事项
使用行级安全性将单租户数据库架构转换为多租户数据库架构时，  UNIQUE 约束必须在云数据库的所有租户中保持全局唯一 。对于仅在租户内才应唯一的列，请使用复合 UNIQUE 约束。
-- ❌ Single-tenant: Unique email per database
CREATE TABLE users (
    id TEXT PRIMARY KEY,
    email TEXT UNIQUE NOT NULL  -- Problem: Not unique across tenants
);
-- ✅ Multi-tenant: Composite unique constraint
CREATE TABLE users (
    id TEXT PRIMARY KEY,
    tenant_id TEXT NOT NULL,
    email TEXT NOT NULL,
    UNIQUE(tenant_id, email)    -- Unique email per tenant
);

外键兼容性
当使用 SQLite Sync 的外键约束时，请注意与 CRDT 合并算法和行级安全策略的交互可能会导致约束违规。
潜在冲突
CRDT 合并算法和默认值 
CRDT 更改在同步期间逐列应用
在合并过程中，列可能会被临时分配默认值
如果外键列具有 DEFAULT 值，则该值必须存在于引用表中
行级安全性和 CASCADE 操作 
RLS 策略可能会阻止维护参照完整性所需的操作
如果 RLS 阻止访问相关行，则 CASCADE DELETE/UPDATE 操作可能会失败
建议
数据库设计模式 
优先使用应用程序级级联逻辑，而不是数据库级 CASCADE 操作
设计 RLS 策略以适应参照完整性操作
在适当的情况下使用可空外键以避免默认值问题
或者，确保外键列的 DEFAULT 值存在于其引用的表中
测试和验证 
启用外键约束的测试同步场景
监控开发过程中同步操作期间的约束违规
触发器兼容性
请注意，由于 SQLite Sync 的合并逻辑，某些类型的触发器可能会在同步期间导致错误。
重复操作 
如果触发器修改了也与 SQLite Sync 同步的表，则在合并操作期间触发器执行的更改可能会应用两次
这可能会导致违反约束或意外的数据状态，具体取决于表的约束
逐列处理 
SQLite Sync 在同步期间逐列应用更改
在处理每一列时，可能会对单个行调用多次 UPDATE 触发器
这可能会导致意外的触发行为
执照
许可协议 本项目遵循Elastic License 2.0 。您可以根据许可条款，将其用于非生产用途，包括使用、复制、修改和分发。如需用于生产或托管服务，请 联系 SQLite Cloud, Inc 获取商业许可。

来源：https://github.com/sqliteai/sqlite-sync