RxDBAdapterRemoteBase

Defined in: packages/rxdb/src/rxdb-adapter.ts:659

数据库适配器基类（远程）

Extends

RxDBAdapterBase

Extended by

Constructors

Constructor

new RxDBAdapterRemoteBase(rxdb): RxDBAdapterRemoteBase;

Defined in: packages/rxdb/src/rxdb-adapter.ts:328

Parameters

Parameter	Type
`rxdb`	`RxDB`

Returns

RxDBAdapterRemoteBase

Inherited from

RxDBAdapterBase.constructor

Properties

repository_cache

protected readonly repository_cache: Map<EntityType, RepositoryInstance<EntityType>>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:326

Inherited from

RxDBAdapterBase.repository_cache

repository_map

protected readonly repository_map: Map<string, AdapterRepositoryConstructor<RxDBAdapterRemoteBase, RepositoryInstance<EntityType>>>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:325

Inherited from

RxDBAdapterBase.repository_map

rxdb

readonly rxdb: RxDB;

Defined in: packages/rxdb/src/rxdb-adapter.ts:328

Inherited from

RxDBAdapterBase.rxdb

Methods

branchExists()?

optional branchExists(branchId): Promise<boolean>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:807

Parameters

Parameter	Type
`branchId`	`string`

Returns

Promise<boolean>

fetchMetadata()

abstract fetchMetadata(entityName, query): Observable<QueryCacheEntityMetadata[]>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:780

获取实体元数据，用于新鲜度比较（QueryCache 专用）

只返回 { id, updatedAt } 元数据，网络传输量比完整数据减少 90%+。这是 QueryCache 同步策略的核心能力。

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名称
`query`	`RuleGroup`<`unknown`>	查询条件

Returns

Observable<QueryCacheEntityMetadata[]>

Observable<QueryCacheEntityMetadata[]> - 实体 ID 和 updatedAt

Example

adapter.fetchMetadata('Product', { where: { status: 'active' } })
  .subscribe(metadata => {
    // metadata: [{ id: 'p1', updatedAt: '2026-01-12T10:00:00Z' }, ...]
  });

Remarks

实现必须满足以下两条契约，二者都是调用方承重的前提，不是建议（RV-001 / RV-002）：

1. 恰好发射一次全量结果，然后 complete。 分页实现要把所有页拼好再发一次，不能每页一发。原因是两个调用点的语义正好相反：

QueryCacheEngine（#syncQuery / #syncAndReadLocal）用 forkJoin —— 只保留最后一次 发射，且不 complete 就永远不产出。逐页发射会静默丢掉除末页以外的全部元数据，进而把它们误判成 orphan 并从本地缓存中驱逐。
query-cache-primary 的 #fetchMetadata 用 firstValueFrom —— 只取第一次发射。逐页发射会让它只看到首页。

2. 传输失败必须能被 isNetworkError 判 true，业务失败必须判 false。 最省事也最可靠的做法是传输失败直接抛 NetworkOfflineError（isNetworkError 的第 1 条判据就是 instanceof，不依赖任何字符串约定，命中即 true）。

抛其他错误类型时才要当心数字 status 属性：第 2 条判据是「带数字 status ⇒ 不是网络错误」，会在第 3、4、5 条（errno / name / TypeError + 消息正则）之前把它判死。也就是说传输失败挂 status 会被判成业务失败，而业务失败应当挂上 status —— 那正是 HTTP 适配器让 HttpResponseError 带状态码、让 HttpDisconnectedError 不带的原因。

分类错了不会报错，只会让 find({ offlineFallback: true }) 在断网时不返回缓存而是抛异常；反向错了（把 RLS 拒绝当成离线）则会让调用方拿到陈旧缓存而看不到真正的失败原因。

findByIds()

abstract findByIds<T>(entityName, ids): Observable<T[]>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:803

按 ID 列表批量获取完整数据（QueryCache 专用）

用于拉取过时或缺失的数据，避免 N+1 问题。

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名称
`ids`	`string`[]	需要获取的实体 ID 列表

Returns

Observable<T[]>

Observable<T[]> - 完整实体数据

Example

adapter.findByIds('Product', ['p1', 'p2', 'p3'])
  .subscribe(products => {
    // products: [{ id: 'p1', name: 'Product A', ... }, ...]
  });

Remarks

与 RxDBAdapter.fetchMetadata 同契约：恰好发射一次（ids 分块查询要合并后再发，调用方同样用 forkJoin）并 complete；传输失败要抛能被 isNetworkError 判 true 的错误。

getChangeCount()

abstract getChangeCount(
   sinceId, 
   repositoryFilter?, 
   branchId?
): Promise<{
  count: number;
  latestChangeId: number;
}>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:693

获取远程变更数量（轻量级，不下载数据）

此方法只查询远程有多少新变更，不返回实际数据。用于实现 checkRepositoryUpdates() 功能，节省带宽。

Parameters

Parameter	Type	Description
`sinceId`	`number`	起始 changeId（不包含该 ID）
`repositoryFilter?`	`string`[]	可选的实体过滤列表
`branchId?`	`string`	可选的分支 ID（只计数该分支的变更）

Returns

Promise<{ count: number; latestChangeId: number; }>

变更数量和最新 changeId

getRepository()

abstract getRepository<T, RT>(EntityType): RT;

Defined in: packages/rxdb/src/rxdb-adapter.ts:330

Type Parameters

Type Parameter	Default type
`T` extends `EntityType`	-
`RT` extends `IRepository`<`T`>	`IRepository`<`T`>

Parameters

Parameter	Type
`EntityType`	`T`

Returns

RT

Inherited from

RxDBAdapterBase.getRepository

mergeChanges()

abstract mergeChanges(
   actions, 
   branchId?, 
   changes?
): Promise<
  | number
  | void
  | RemoteMergeResult>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:720

应用压缩后的变更到远程实体表

实现策略（Supabase）：

将 actions (Map) 转换为 RemoteChange 记录
在事务中： a) 写入远程 RemoteChange 表（用于其他客户端 pull） b) 直接操作远程实体表（INSERT/UPDATE/DELETE）

Parameters

Parameter	Type	Description
`actions`	`SwitchVersionActions`	压缩后的变更操作集合（从本地 push 来的）
`branchId?`	`string`	分支 ID（用于在远程变更记录中设置 branchId）
`changes?`	`IRxDBChange`[]	完整的原始变更记录（可选，用于保留完整的变更历史）

Returns

Promise< | number | void | RemoteMergeResult>

创建的远程 RxDBChange 的最大 ID（用于更新 lastPullRemoteChangeId）

Remarks

提供 changes 时，实现必须以客户端 ID 和本地 change ID 作为幂等键。相同批次重试时不得重复执行实体副作用，并且必须为每个本地 change ID 返回首次提交得到的同一个远端 ID。

pullBranches()?

optional pullBranches(): Promise<RemoteBranchInfo[]>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:809

Returns

Promise<RemoteBranchInfo[]>

pullChanges()

abstract pullChanges(
   sinceId, 
   limit?, 
   repositoryFilter?, 
   filter?, 
   branchId?
): Promise<RemoteChange[]>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:674

从远程拉取变更记录

Parameters

Parameter	Type	Description
`sinceId`	`number`	拉取此 ID 之后的变更（不包含该 ID）
`limit?`	`number`	最大拉取数量
`repositoryFilter?`	`string`[]	可选的实体过滤列表（用于 repository-level sync）
`filter?`	`RuleGroup`	可选的行级过滤条件（用于 SyncType.Filter）
`branchId?`	`string`	可选的分支 ID（只拉取该分支的变更）

Returns

Promise<RemoteChange[]>

变更记录数组，按 id ASC 排序

Remarks

当提供 filter 参数时，会通过 JOIN 实体表并应用过滤条件，只返回满足条件的实体对应的变更记录。

pullChangesBatch()?

optional pullChangesBatch(
   requests, 
   limit, 
   branchIds?
): Promise<RemoteChange[]>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:737

批量拉取多个实体的变更记录（单次 HTTP 请求）

每个实体可以有不同的 sinceId（水位线），通过服务端 OR 过滤实现单次请求获取所有实体的变更。

Parameters

Parameter	Type	Description
`requests`	`PullBatchRequest`[]	每个实体的拉取请求（namespace + 实体名 + sinceId）
`limit`	`number`	最大拉取数量
`branchIds?`	`string`[]	分支 ID 列表（支持包含祖先分支）

Returns

Promise<RemoteChange[]>

变更记录数组，按 id ASC 排序

pushBranches()?

optional pushBranches(branches): Promise<{
  skipped: string[];
  synced: number;
}>;

Defined in: packages/rxdb/src/rxdb-adapter.ts:805

Parameters

Parameter	Type
`branches`	`Record`<`string`, `unknown`>[]

Returns

Promise<{ skipped: string[]; synced: number; }>

repository()

protected repository<RT>(repositoryName, RepositoryClass): void;

Defined in: packages/rxdb/src/rxdb-adapter.ts:332

Type Parameters

Type Parameter
`RT` extends `RepositoryInstance`<`EntityType`>

Parameters

Parameter	Type
`repositoryName`	`string`
`RepositoryClass`	`AdapterRepositoryConstructor`<`RxDBAdapterRemoteBase`, `RT`>

Returns

void

Inherited from

RxDBAdapterBase.repository

Extends​

Extended by​

Constructors​

Constructor​

Parameters​

Returns​

Inherited from​

Properties​

repository_cache​

Inherited from​

repository_map​

Inherited from​

rxdb​

Inherited from​

Methods​

branchExists()?​

Parameters​

Returns​

fetchMetadata()​

Parameters​

Returns​

Example​

Remarks​

findByIds()​

Type Parameters​

Parameters​

Returns​

Example​

Remarks​

getChangeCount()​

Parameters​

Returns​

getRepository()​

Type Parameters​

Parameters​

Returns​

Inherited from​

mergeChanges()​

Parameters​

Returns​

Remarks​

pullBranches()?​

Returns​

pullChanges()​

Parameters​

Returns​

Remarks​

pullChangesBatch()?​

Parameters​

Returns​

pushBranches()?​

Parameters​

Returns​

repository()​

Type Parameters​

Parameters​

Returns​

Inherited from​

Extends

Extended by

Constructors

Constructor

Parameters

Returns

Inherited from

Properties

repository_cache

Inherited from

repository_map

Inherited from

rxdb

Inherited from

Methods

branchExists()?

Parameters

Returns

fetchMetadata()

Parameters

Returns

Example

Remarks

findByIds()

Type Parameters

Parameters

Returns

Example

Remarks

getChangeCount()

Parameters

Returns

getRepository()

Type Parameters

Parameters

Returns

Inherited from

mergeChanges()

Parameters

Returns

Remarks

pullBranches()?

Returns

pullChanges()

Parameters

Returns

Remarks

pullChangesBatch()?

Parameters

Returns

pushBranches()?

Parameters

Returns

repository()

Type Parameters

Parameters

Returns

Inherited from