tanstack-db

TanStack DB

概述

TanStack DB 是一个基于差分数据流构建的响应式客户端存储，通过集合、实时查询和乐观变更扩展 TanStack Query。它将数据规范化为类型化集合，支持亚毫秒级跨集合查询，并提供即时乐观更新，失败时自动回滚。

适用场景： 需要本地优先数据的响应式 UI、支持实时更新的跨集合联接、带自动同步的乐观变更、通过 ElectricSQL 或其他后端进行实时同步，以及超出 TanStack Query 按查询缓存模式能力的应用。

不适用场景： 简单的获取并显示（仅使用 TanStack Query 即可）、仅使用服务器组件的应用、纯同步本地状态（使用 useState/Zustand），以及采用规范化缓存的 GraphQL（Apollo/urql）。

TanStack DB 目前处于 beta 阶段。不同版本之间的 API 可能会发生变化。

快速参考

模式	API	要点
创建集合	createCollection(queryCollectionOptions({...}))	使用 getKey 定义一组类型化对象
实时查询（React）	useLiveQuery((q) => q.from({...}).where(...))	底层数据变化时自动更新
筛选	.where(({ t }) => eq(t.field, value))	支持 eq、gt、lt、like、and、or、not
选择字段	.select(({ t }) => ({ id: t.id, name: t.name }))	从集合中投影特定字段
排序结果	.orderBy(({ t }) => t.field, 'asc')	按升序或降序排序
联接集合	.join({ b: collB }, ({ a, b }) => eq(...), 'inner')	类型安全的跨集合联接
分组和聚合	.groupBy(...).select(({ t }) => ({ count: count(t.id) }))	支持 count、sum、avg、min、max
插入	collection.insert({ ...data })	乐观插入，通过 onInsert 处理器同步
更新	collection.update(key, (draft) => { ... })	Immer 风格的草稿变更，通过 onUpdate 同步
删除	collection.delete(key)	乐观删除，通过 onDelete 处理器同步
Electric 同步	electricCollectionOptions({ shapeOptions: {...} })	通过 ElectricSQL 实时同步 Postgres
实时查询集合	liveQueryCollectionOptions({ query })	根据实时查询定义派生集合
本地存储	localStorageCollectionOptions({...})	持久化本地数据，并在多个标签页间同步

同步模式（v0.5+）

模式	行为	适用场景
预加载（默认）	集合初始化时加载所有记录	小型数据集（少于 1k 行）
按需	仅加载查询请求的数据（谓词下推）	大型数据集、选择性加载
渐进式	快速完成首次绘制，在后台同步完整数据集	兼顾两者，适用于 100k+ 条数据

常见错误

错误	正确做法
直接使用 TanStack Query 管理本地状态	使用集合和实时查询处理响应式本地数据
忘记在集合配置中设置 getKey	始终提供 getKey，以唯一标识各项
未提供持久化处理程序	定义 onInsert/onUpdate/onDelete，以便与服务端同步
使用 useQuery 而不是 useLiveQuery	useLiveQuery 支持响应式跨集合查询
在组件内部创建集合	在模块作用域中定义集合，而非在组件内部
在 React 应用中从 @tanstack/db 导入	从 @tanstack/react-db 导入（重新导出核心功能）
期待在未配置的情况下自动与服务端同步	集合需要显式配置持久化处理程序才能同步
未安装集合类型包	安装 @tanstack/query-db-collection 以使用 REST API

委派

如果有 tanstack-query 技能，请将 TanStack Query 特定模式（查询键、缓存失效、SSR）委派给它。 否则，建议使用：npx skills add oakoss/agent-skills --skill tanstack-query 如果有 electricsql 技能，请将 ElectricSQL 设置、形状、身份验证代理和写入模式委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y 如果有 local-first 技能，请将架构决策、同步引擎对比和冲突解决委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y

• 查询模式探索：使用 Explore Agent
• 架构审查：使用 Task Agent

参考资料

• 设置、安装和集合配置
• 实时查询、筛选、联接和聚合
• 乐观变更、持久化处理程序和同步模式
• ElectricSQL 集成、电气集合和 txid 模式
• 错误类层次结构、事务状态和回滚模式
• 仅本地集合和 localStorage 集合及跨标签页同步
• 跨集合事务、联接、批处理和生命周期