用途:为 TanStack DB 集合增加 SQLite 持久化层,使数据在页面刷新、应用重启和离线期间保留。同步集合中服务端仍是权威来源,持久化只作为本地缓存实现即时水合。该技能建立在 db-core 与 db-core/collection-setup 之上,需先阅读。
主要能力:persistedCollectionOptions 可包装任意适配器(electricCollectionOptions、queryCollectionOptions、powerSyncCollectionOptions 等),拦截同步层并持久化流经的数据;也支持无服务端的纯本地集合。平台包覆盖浏览器 OPFS、React Native、Expo、Electron、Node.js、Capacitor、Tauri、Cloudflare Durable Objects,均从核心重导出 persistedCollectionOptions。协调器负责领导者选举与跨实例通信:浏览器用 BrowserCollectionCoordinator(BroadcastChannel + Web Locks),Electron 用 ElectronCollectionCoordinator(IPC),单进程环境用 SingleProcessCoordinator。
使用方式:本地集合需提供 id、getKey、persistence、schemaVersion,并通过 collection.utils.acceptMutations() 应用变更;同步集合将适配器选项展开进 persistedCollectionOptions 并附加 persistence 与 schemaVersion。浏览器需创建协调器并传入 persistence,关闭时调用 coordinator.dispose() 与 database.close()。Electron 需在主进程 exposeElectronSQLitePersistence,渲染进程创建协调器与持久化。
限制:schemaVersion 不匹配会触发完全重置(同步集合从服务端重载,本地集合抛错),没有自定义迁移函数。本地集合缺少 id 会每次生成随机 UUID 导致数据无法跨刷新保留;多标签页缺少协调器会并发写坏数据库;修改数据形状后未提升 schemaVersion 会保留旧结构。离线事务队列见 tanstack-offline-transactions-offline。