Turso React Native SDK 完全指南在移动端构建可离线同步的嵌入式副本数据库【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/turso导读本文围绕 bindings/react-native/README.md 展开完整讲解 Turso React Native 绑定tursodatabase/sync-react-native的安装、配置与使用它允许你的 iOS / Android 应用在本地以 SQLite 兼容的嵌入式副本embedded replica方式运行数据库并在有网络时与 Turso 云端数据库双向同步。读完本文你将掌握本地数据库、云同步数据库、加密远程库的完整接入方案以及 SDK 的底层架构JSI 桥接、异步 IO 处理原理。Turso 本身是一个用 Rust 编写的 SQL 数据库引擎兼容 SQLite并新增了同步引擎能力。本 SDK 把这一能力桥接进 React Native核心逻辑位于 TypeScript 与 Rust 中C 层只是一个薄薄的 JSI 桥接层。1. 安装与平台配置1.1 安装 npm 包npm install tursodatabase/sync-react-native从仓库的 bindings/react-native/package.json 可以看到该包的元信息主入口为lib/commonjs/index.js构建产物由react-native-builder-bob生成TypeScript 类型定义位于lib/typescript/index.d.ts源码位于src/index.ts。它要求react 18.0.0、react-native 0.76.0peerDependencies运行环境 Node 需 18。1.2 iOSpod installcd ios pod installiOS 依赖一个预编译的 Rust XCFrameworkturso-sync-sdk-kit.xcframework。CocoaPods 配置见 bindings/react-native/turso-sync-react-native.podspec平台要求ios 13.0以vendored_frameworks方式引入 Rust 构建产物设备与模拟器架构自动切换内置script_phase若libs/ios/turso-sync-sdk-kit.xcframework不存在会先执行make ios编译 Rust 库C 标准c20链接-lc。如果你需要从源码重新构建 Rust 原生库可参考 bindings/react-native/Makefilemake ios会通过rustup target add添加aarch64-apple-ios与aarch64-apple-ios-sim目标后执行cargo build --releasemake android则交叉编译aarch64-linux-android、armv7-linux-androideabi、x86_64-linux-android、i686-linux-android四个 ABI 的.so文件。1.3 AndroidminSdkVersionAndroid 侧要求minSdkVersion不低于21在android/build.gradle中配置。原生桥接模块实现位于 bindings/react-native/android/src/main/java/com/turso/sync/reactnative/TursoModule.java通过System.loadLibrary(turso_sync_sdk_kit)加载 Rust 动态库通过getConstants()暴露ANDROID_DATABASE_PATH应用的数据库目录、ANDROID_FILES_PATH、ANDROID_EXTERNAL_FILES_PATH等常量暴露install()同步方法把 JSI 桥接安装到 JS 运行时。iOS 侧对应实现见 bindings/react-native/ios/TursoModule.mm它读取应用 Documents 目录若配置了Turso_AppGroup则使用 App Group 容器路径便于 App 与扩展共享数据并通过turso::install(*runtime, callInvoker, ...)安装 JSI 模块。注意SDK 依赖 React Native 的New Architecture新架构src/index.ts在模块加载时会检查原生模块与__TursoProxy全局对象若 JSI 绑定安装失败会直接抛错提示。2. 快速开始同步数据库import { Database, getDbPath } from tursodatabase/sync-react-native; // 获取平台可写路径 const dbPath getDbPath(myapp.db); // 创建带同步功能的数据库 const db new Database({ path: dbPath, url: libsql://your-db.turso.io, authToken: your-auth-token, }); // 连接若本地为空则从远端引导初始化 await db.connect(); // 查询本地副本快速 const users await db.all(SELECT * FROM users); // 本地写入 await db.run(INSERT INTO users (name) VALUES (?), [Alice]); // 与远端同步 await db.push(); // 推送本地变更 await db.pull(); // 拉取远端变更 // 用完关闭 await db.close();关键点说明getDbPath(filename)返回平台特定的可写目录下的绝对路径。iOS 为 Documents 目录Android 为数据库目录见 src/index.ts 与paths.databasegetter。connect()本地库直接打开同步库则会执行create()bootstrap并建立连接见 src/Database.ts。url是判据Database构造函数通过isSyncConfig(opts)判断——只要url非空即进入同步模式见 src/Database.ts。你还可以使用便捷函数connect(opts)它会new Database(opts)并立即connect()后返回实例见 src/index.ts。3. 纯本地数据库Local-Only Database不传url即为纯本地数据库无需网络、无需鉴权const db new Database({ path: getDbPath(local.db) }); await db.connect(); await db.exec(CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)); await db.run(INSERT INTO users (name) VALUES (?), [Bob]); const user await db.get(SELECT * FROM users WHERE id ?, [1]); await db.close();本地模式在原生层以阻塞 IO打开async_io: false而同步模式使用异步 IOasync_io: true因为同步引擎需要外部网络 IO 循环配合见 src/Database.ts。所有数据库操作均为异步 API统一了本地与同步两种场景的调用方式。另外路径可以是相对路径自动放入可写目录、绝对路径甚至是:memory:内存数据库见 src/index.ts 中的connect文档注释。4. 加密远程数据库Encrypted Remote Database当云端数据库启用了加密时通过remoteEncryption传入加密配置const db new Database({ path: getDbPath(encrypted.db), url: libsql://your-db.turso.io, authToken: your-auth-token, remoteEncryption: { cipher: aes256gcm, key: base64-encoded-key, }, });加密参数详解定义见 src/types.tscipher 取值密钥要求reservedBytes保留字节数aes256gcm/aes128gcm/chacha20poly1305base64 编码16 或 32 字节视 cipher28aegis128l/aegis128x2/aegis128x4base64 编码32aegis256/aegis256x2/aegis256x4base64 编码48Database内部通过getReservedBytesForCipher()根据 cipher 计算保留字节数并传入同步引擎见 src/Database.ts这些保留字节数与 Turso Cloud 的加密设置保持一致。同步引擎会收到remoteEncryptionKey与remoteEncryptionCipher密钥用于构造 HTTP 请求头。5. API 参考5.1 Database 方法方法说明connect()打开 / 引导初始化数据库exec(sql)执行 SQL无返回结果支持多条语句run(sql, params?)执行 SQL返回{ changes, lastInsertRowid }get(sql, params?)查询单行all(sql, params?)查询所有行prepare(sql)创建预编译语句返回Statementclose()关闭数据库5.2 同步方法提供url时可用方法说明push()推送本地变更到远端pull()拉取远端变更到本地有变更返回true无变更返回falsesync()先 push 再 pullstats()获取同步统计信息说明sync()在当前仓库的Database类中体现为push()与pull()的组合使用文档 API 表中列出源码中push()/pull()分别对应原生pushChanges()与waitChanges()applyChanges()两个阶段见 src/Database.ts。同步库还额外提供checkpoint()用于触发检查点。5.3 同步统计stats()返回值SyncStats结构定义见 src/types.ts字段含义cdcOperationsCDC变更数据捕获操作数mainWalSize主 WAL 大小revertWalSize回滚 WAL 大小lastPullUnixTime最近一次拉取时间Unix 时间戳lastPushUnixTime最近一次推送时间networkSentBytes网络发送字节数networkReceivedBytes网络接收字节数revision远端版本号字符串或null5.4 事务Transactionsawait db.transaction(async () { await db.run(INSERT INTO users (name) VALUES (?), [Alice]); await db.run(INSERT INTO users (name) VALUES (?), [Bob]); // 成功则提交出错则回滚 });transactionT(fn)的实现非常直观见 src/Database.ts先exec(BEGIN)回调成功则exec(COMMIT)抛出异常则exec(ROLLBACK)并重新抛出错误。此外还提供了inTransactiongetter内部通过connection.getAutocommit()判断与lastInsertRowidgetter 便于事务内取最近插入行 ID。5.5 预编译语句Statementprepare(sql)返回Statement支持链式bind()、run()、get()、all()、reset()、finalize()。参数绑定支持三种形态见 src/Statement.ts位置参数数组stmt.run(1, Alice)或stmt.run([1, Alice])命名参数对象stmt.run({ $id: 1 })内部通过namedPosition(name)解析占位符位置单个标量值stmt.run(42)。值类型映射见 src/Statement.tsnull/undefined→ NULL整数number→ INTEGER浮点number→ REALstring→ TEXTArrayBuffer/ TypedArray → BLOB。查询结果统一按列名组织为RowRecordstring, SQLiteValue其中SQLiteValue null | number | string | ArrayBuffer。6. 高级配置参数DatabaseOpts 全解除path、url、authToken、remoteEncryption之外DatabaseOpts还支持以下配置完整定义见 src/types.ts参数类型默认值说明clientNamestringturso-sync-react-native客户端标识SDK 会追加唯一后缀保证clientId唯一longPollTimeoutMsnumber不设则无超时拉取操作的长轮询超时bootstrapIfEmptybooleantrue本地为空时是否从远端引导初始化设为false则客户端仅在联网时才能连接全新数据库pushOperationsThresholdnumber不设则一次推送全部变更单个 push HTTP 批次中 CDC 操作数上限达到后按事务边界拆分单个用户事务永不被拆散pullBytesThresholdnumber不设则单次往返完成 bootstrapbootstrap 下载按字节拆分多个/pull-updates请求对query引导策略无效logicalMvccPullbooleanfalse强制增量拉取使用 MVCC 逻辑日志流默认自动探测远端协议并持久化仅在需要时作为逃生舱口开启partialSyncExperimentalobject未启用实验性局部同步见下6.1 实验性局部同步partialSyncExperimentalconst db new Database({ path: getDbPath(partial.db), url: libsql://your-db.turso.io, authToken: your-auth-token, partialSyncExperimental: { // 前缀策略启动时仅本地加载前 N 字节 bootstrapStrategy: { kind: prefix, length: 1024 * 1024 }, // 或查询策略仅加载指定 SQL 触及的页面 // bootstrapStrategy: { kind: query, query: SELECT * FROM users }, segmentSize: 128 * 1024, // 按段加载128KB 约 32 页 prefetch: true, // 预取可能即将访问的页面 }, });三种引导策略说明见 src/types.tsprefix启动时仅下载数据库文件前 N 字节query仅下载指定 SQL 语句访问过的页面segmentSize让同步引擎按段批量加载页面如 128KB 段即加载约 32 页prefetch预取未来可能访问的页面。当局部同步遇到缺失页面时语句执行会返回TursoStatus.IOSDK 通过drainSyncIo()驱动同步引擎的 IO 队列补页后继续执行见 src/Statement.ts 中的executeWithIo/stepWithIo循环以及 src/internal/ioProcessor.ts。7. 底层架构解析TypeScript 驱动、C 薄桥、Rust 引擎理解 SDK 的分层有助于排查问题与评估性能┌─────────────────────────────────────────────┐ │ TypeScript 层Database / Statement / │ │ asyncOperation / ioProcessor │ ├─────────────────────────────────────────────┤ │ JSI 桥接层CTursoHostObject、 │ │ TursoDatabaseHostObject、TursoSync... │ ├─────────────────────────────────────────────┤ │ 原生模块iOS: TursoModule.mm / │ │ Android: TursoModule.java │ ├─────────────────────────────────────────────┤ │ Rust 引擎sdk-kit sync/sdk-kit │ │ 以 .xcframework / .so 形式内置 │ └─────────────────────────────────────────────┘架构要点JSI 直连无 JSON 序列化原生层通过 JSIJavaScript Interface把__TursoProxy注入全局对象见 src/index.tsTypeScript 直接调用原生方法避免传统 Bridge 的序列化开销。原生侧 Host Object 源码位于 bindings/react-native/cpp/TursoHostObject.cpp、TursoDatabaseHostObject.cpp、TursoConnectionHostObject.cpp、TursoStatementHostObject.cpp、TursoSyncDatabaseHostObject.cpp等。异步 IO 全部由 JavaScript 驱动同步引擎产生三类 IO 请求见 src/internal/ioProcessor.ts 与NativeSyncIoItem的getKind()HTTP使用 React Native 标准fetch()发出URL 会从libsql:///turso://规范化为https://并自动注入Authorization: Bearer token头FULL_READ / FULL_WRITE整库文件的原子读写默认走内置 JSI 文件系统函数NONE空操作。这一设计的好处是网络请求在 RN 调试器中可见、可自定义 fetch 行为如代理、自定义头、可 mock 测试、使用平台原生网络栈而非 C HTTP 库。异步操作驱动循环同步操作create、connect、pushChanges、waitChanges、applyChanges、checkpoint、stats返回NativeSyncOperation由 src/internal/asyncOperation.ts 的driveOperation()循环调用resume()状态为TursoStatus.IO时先处理 IO 队列再继续TursoStatus.DONE时按resultKind提取连接 / 变更 / 统计结果。并发安全Database内部持有一个AsyncLock所有语句执行run/get/all/finalize在锁内完成“绑定参数 → 执行 → 重置”避免并发绑定/执行竞态exec()则利用prepareFirsttailIdx循环处理多语句 SQL。状态码体系TursoStatus枚举src/types.ts涵盖OK/DONE/ROW/IO/BUSY/INTERRUPT/ERROR/MISUSE/CONSTRAINT/READONLY/DATABASE_FULL/NOTADB/CORRUPT/IOERR等TursoType枚举则对应 SQLite 值类型INTEGER/REAL/TEXT/BLOB/NULL用于结果行读取。可插拔文件系统通过setFileSystemImpl(readFile, writeFile)可覆盖内置文件读写实现如加密、压缩等自定义需求默认使用 JSI 内置函数见 src/internal/ioProcessor.ts。8. 调试与日志SDK 提供setup()用于配置引擎日志应在任何数据库操作之前调用见 src/index.tsimport { setup } from tursodatabase/sync-react-native; setup({ logLevel: debug, logger: (log) { console.log([${log.level}] ${log.target}: ${log.message}); }, });日志级别为error | warn | info | debug | trace每条日志包含message、target、file、line、timestamp、level字段类型定义见 src/types.ts。9. 最佳实践与注意事项离线优先Offline-first把bootstrapIfEmpty设为false可避免网络不可用时对全新库的无谓 bootstrap 尝试日常读写全部落在本地副本响应快且离线可用。路径管理优先使用getDbPath()或相对路径SDK 自动归一化到可写目录Android 上数据库目录为/data/data/应用包名/databases/iOS 为 Documents 目录同步库会在主文件旁生成-info、-wal等伴随文件。善用stats()通过cdcOperations、networkSentBytes、networkReceivedBytes等指标监控同步负载与网络消耗。局部同步是实验特性仅当数据库体积较大、需要控制启动下载量时才启用partialSyncExperimental并理解其“按需补页”的 IO 行为。事务边界pushOperationsThreshold会按事务边界拆分推送批次单个用户事务不会被拆散——这保证了远端回放的一致性语义。版本与平台约束当前包版本为0.8.0-pre.10预发布要求 RN 新架构New Architecture、iOS 13、Android minSdk 21如需从源码构建原生库参考 bindings/react-native/Makefile 的make ios/make android。10. 继续深入仓库SDK 入口与类型 bindings/react-native/src/index.ts、bindings/react-native/src/types.ts数据库与语句实现 bindings/react-native/src/Database.ts、bindings/react-native/src/Statement.ts异步 IO 与操作驱动 bindings/react-native/src/internal/ioProcessor.ts、bindings/react-native/src/internal/asyncOperation.ts原生桥接 bindings/react-native/ios/TursoModule.mm、bindings/react-native/android/src/main/java/com/turso/sync/reactnative/TursoModule.java、bindings/react-native/cpp/Rust 引擎底层 sync/engine/、sync/sdk-kit/、sdk-kit/完整示例工程 examples/react-native/【免费下载链接】tursoA SQL database in Rust: SQLite-compatible, now also speaking Postgres (experimental). The LLVM of databases.项目地址: https://gitcode.com/GitHub_Trending/tu/turso创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考