db-core/collection-setup

用途

本技能建立在 db-core 之上，用于创建带类型的集合（collection）。核心 API 是 createCollection，并通过适配器（options creator）对接不同的数据后端或本地存储。文档建议先阅读 db-core 以获得整体心智模型。

适配器选择

不同后端对应不同适配器与安装包：

后端	适配器	包
REST API / TanStack Query	`queryCollectionOptions`	`@tanstack/query-db-collection`
ElectricSQL（实时 Postgres）	`electricCollectionOptions`	`@tanstack/electric-db-collection`
PowerSync（SQLite 离线）	`powerSyncCollectionOptions`	`@tanstack/powersync-db-collection`
RxDB（响应式数据库）	`rxdbCollectionOptions`	`@tanstack/rxdb-db-collection`
TrailBase（事件流）	`trailBaseCollectionOptions`	`@tanstack/trailbase-db-collection`
无后端（UI 状态）	`localOnlyCollectionOptions`	`@tanstack/db`
浏览器 localStorage	`localStorageCollectionOptions`	`@tanstack/db`
浏览器 IndexedDB	`indexedDBCollectionOptions`	`@tanstack/db`

如果用户指定了后端（如 Electric、PowerSync），应直接使用对应适配器。只有在还没有后端时才使用 localOnlyCollectionOptions —— 集合 API 是统一的，之后切换到真实适配器只需更改 options creator。

同步模式

queryCollectionOptions 支持三种 syncMode：

eager（默认）：一次性加载所有数据，适合基本静态、数据量小于 1 万行的数据集。
on-demand：只加载实时查询请求的数据，适合搜索、目录、大于 5 万行的大表。
progressive（仅 Electric）：先查询子集、后台全量同步，适合需要即时首屏的协作应用，数据量不限。

在 on-demand 集合上调用 collection.preload() 是无效操作；应为所需子集创建实时查询并调用 liveQuery.preload()。

索引

索引默认关闭，autoIndex 默认值为 "off"。要启用自动索引，需设置 autoIndex: "eager" 并提供 defaultIndexType；若不提供 defaultIndexType，设置 autoIndex: "eager" 会抛出 CollectionConfigurationError。也可以手动使用 collection.createIndex() 创建索引、collection.removeIndex() 移除索引。

核心模式

仅本地集合（用于原型）

使用 localOnlyCollectionOptions，配合 getKey 与 initialData。

带类型转换的 schema

使用 zod 定义 schema，对转换字段使用 z.union([z.string(), z.date()])，以保证 TInput 是 TOutput 的超集，从而使 update() 能与 draft proxy 正确配合。

ElectricSQL 与 txid 追踪

使用 Electric 时务必提供 schema，否则集合类型会被推断为 Record<string, unknown>。onInsert 返回 { txid }，告知集合在 Electric 流回该事务前保持乐观状态。完整双路径模式（schema + parser）见 Electric 适配器参考。

常见错误

文档列出了若干必须避免的问题：

queryFn 返回空数组会删除全部数据（CRITICAL）：eager 模式下 queryFn 结果代表集合的完整状态，返回 [] 表示服务器没有条目，会移除所有行。应获取完整状态，或改用 on-demand 模式加 live query where() 过滤。
后端未使用正确适配器（CRITICAL）：真实后端应使用专用适配器处理同步、mutation 处理器和工具函数；使用 localOnlyCollectionOptions 或裸 createCollection 会绕过这些能力。
Electric txid 在 mutation 事务之外查询（CRITICAL）：pg_current_xact_id() 必须在与 mutation 相同的 SQL 事务内查询，否则 txid 不匹配，awaitTxId 会超时（默认 5 秒）。
queryFn 返回部分数据未合并（CRITICAL）：eager queryFn 结果会替换全部集合数据；增量 eager 拉取需与已有数据合并。on-demand 模式下应返回所请求子集的完整状态。
使用异步 schema 校验（HIGH）：schema 校验必须同步，异步校验会在 mutation 时抛出 SchemaMustBeSynchronousError；异步校验应放到 mutation 处理器中。
getKey 对某些项返回 undefined（HIGH）：getKey 必须为每一项返回定义值，否则抛出 UndefinedKeyError。
schema 转换时 TInput 非 TOutput 超集（HIGH）：当 schema 转换类型时，TInput 必须同时接受转换前与转换后的类型，update() 才能与 draft proxy 配合。
运行时没有安全随机数生成器（HIGH）：TanStack DB 的 safeRandomUUID() 在可用时使用 crypto.randomUUID()，回退到 crypto.getRandomValues()（包括非安全 HTTP 源）。对于两者都不可用的运行时（包括部分 React Native 版本），需添加 Web Crypto polyfill。
同时提供显式类型参数和 schema（MEDIUM）：提供 schema 时集合会从中推断类型，显式泛型会产生冲突的类型约束。
直接写入被下一次查询同步覆盖（MEDIUM）：utils.writeInsert 立即更新集合，但下一次 queryFn 返回的完整服务器状态会覆盖它；可使用 staleTime 阻止立即重新拉取，或在 mutation 处理器中返回 { refetch: false }。

限制

资料未提供具体收费、价格或平台可用性信息。

技能介绍

用途