RemoteRxDBChangeRepository

Defined in: packages/rxdb/src/system/types.remote.ts:66

RxDBChange 远程仓库接口

Extends

RxDBAdapterRemoteBase.IRxDBAdapter

Properties

name

readonly name: string;

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

适配器名，与 RxDB.adapter() 登记时用的键同值；错误消息与 getAdapter() 都按它认人

Inherited from

IRxDBAdapter.name

repository_cache

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

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

Inherited from

RxDBAdapterRemoteBase.repository_cache

repository_map

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

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

Inherited from

RxDBAdapterRemoteBase.repository_map

rxdb

readonly rxdb: RxDB;

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

Inherited from

RxDBAdapterRemoteBase.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>

Inherited from

RxDBAdapterRemoteBase.branchExists

connect()

connect(): Promise<IRxDBAdapter>;

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

建立连接并把系统表补到当前水位。

Returns

Promise<IRxDBAdapter>

自身，便于链式使用

Remarks

建表与系统迁移都在这里发生（见 isCurrentRxDBSystemVersion），因此它可能很慢，也可能因为库比本进程新而抛 UnsupportedRxDBSystemVersionError。

Inherited from

IRxDBAdapter.connect

count()

count(options): Promise<number>;

Defined in: packages/rxdb/src/system/types.remote.ts:81

count 查询

Parameters

Parameter	Type	Description
`options`	`CountOptions`<typeof `RxDBChange`, `RxDBChangeRuleGroup`>	查询选项

Returns

Promise<number>

返回查询结果数量

create()

create(entity): Promise<RxDBChange>;

Defined in: packages/rxdb/src/system/types.remote.ts:88

创建实体

Parameters

Parameter	Type	Description
`entity`	`RxDBChange`	要创建的实体

Returns

Promise<RxDBChange>

返回创建后的实体

disconnect()

disconnect(): Promise<void>;

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

断开连接并释放底层句柄。

Returns

Promise<void>

Remarks

与 RxDB.destroy() 不同，断开是可逆的：同一个适配器实例之后还能再 connect()。实现须幂等——未连接时调用是空操作而不是抛错。

Inherited from

IRxDBAdapter.disconnect

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 拒绝当成离线）则会让调用方拿到陈旧缓存而看不到真正的失败原因。

Inherited from

RxDBAdapterRemoteBase.fetchMetadata

find()

find(options): Promise<RxDBChange[]>;

Defined in: packages/rxdb/src/system/types.remote.ts:72

find 查询

Parameters

Parameter	Type	Description
`options`	`FindOptions`<typeof `RxDBChange`, `RxDBChangeRuleGroup`, `RxDBChangeOrderByField`>	查询选项

Returns

Promise<RxDBChange[]>

返回查询结果数组

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 的错误。

Inherited from

RxDBAdapterRemoteBase.findByIds

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

Inherited from

RxDBAdapterRemoteBase.getChangeCount

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

Remarks

返回的是适配器轴的仓储（见 AdapterRepositoryConstructor），与用户通常拿到的门面仓储 RxDB.getRepository() 不是同一个对象。

Inherited from

RxDBAdapterRemoteBase.getRepository

isTableExisted()

isTableExisted(EntityType): Promise<boolean>;

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

该实体对应的表在库里是否已存在。

Parameters

Parameter	Type
`EntityType`	`EntityType`

Returns

Promise<boolean>

Remarks

问的是物理表，不是元数据里有没有登记这个实体。

Inherited from

IRxDBAdapter.isTableExisted

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。

Inherited from

RxDBAdapterRemoteBase.mergeChanges

mutations()

mutations<T>(options): Promise<InstanceType<T>[]>;

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

批量修改实体（创建/更新/删除）

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type
`options`	`RxDBMutationsMap`<`T`>

Returns

Promise<InstanceType<T>[]>

Inherited from

IRxDBAdapter.mutations

pullBranches()?

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

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

Returns

Promise<RemoteBranchInfo[]>

Inherited from

RxDBAdapterRemoteBase.pullBranches

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 实体表并应用过滤条件，只返回满足条件的实体对应的变更记录。

Inherited from

RxDBAdapterRemoteBase.pullChanges

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 排序

Inherited from

RxDBAdapterRemoteBase.pullChangesBatch

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; }>

Inherited from

RxDBAdapterRemoteBase.pushBranches

rawQuery()?

optional rawQuery(sql, params?): Promise<RawQueryResult>;

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

执行原始 SQL 查询（条件 UPDATE 等绕过 ORM 的场景）

Parameters

Parameter	Type
`sql`	`string`
`params?`	`unknown`[]

Returns

Promise<RawQueryResult>

Remarks

可选方法，这一点有后果：核心包没法像四个写原语那样替适配器包住它，于是启用提交能力的库上，raw 写的门禁只能由各适配器自己的实现调用 gateRawWrite(sql, ctx, …) 来完成（ctx 取自 RxDBAdapterLocalBase.workingTreeRawWriteContext）。漏掉那一句等于这条路径上的写全部绕过变更捕获。

走这里的写不经过实体 Proxy，因此也不会产生实体事件，缓存里的实例不会自动刷新。

Inherited from

IRxDBAdapter.rawQuery

remove()

remove(entity): Promise<RxDBChange>;

Defined in: packages/rxdb/src/system/types.remote.ts:106

删除实体

Parameters

Parameter	Type	Description
`entity`	`RxDBChange`	要删除的实体

Returns

Promise<RxDBChange>

返回删除的实体

removeMany()

removeMany<T>(entities): Promise<InstanceType<T>[]>;

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

批量删除实体。

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type
`entities`	`InstanceType`<`T`>[]

Returns

Promise<InstanceType<T>[]>

被删除的实体

Inherited from

IRxDBAdapter.removeMany

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`<`RemoteRxDBChangeRepository`, `RT`>

Returns

void

Inherited from

RxDBAdapterRemoteBase.repository

saveMany()

saveMany<T>(entities): Promise<InstanceType<T>[]>;

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

批量写入实体（不存在则插入，存在则更新）。

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type
`entities`	`InstanceType`<`T`>[]

Returns

Promise<InstanceType<T>[]>

落库后的实体；主键、数据库端默认值等由库回填的字段在这里才有值

Inherited from

IRxDBAdapter.saveMany

update()

update(entity, patch): Promise<RxDBChange>;

Defined in: packages/rxdb/src/system/types.remote.ts:96

更新实体

Parameters

Parameter	Type	Description
`entity`	`RxDBChange`	要更新的实体
`patch`	`Partial`<`InstanceType`<typeof `RxDBChange`>>	更新数据

Returns

Promise<RxDBChange>

返回更新后的实体

version()

version(): Promise<string>;

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

底层数据库引擎的版本号（如 SQLite 的 3.45.0），用于诊断与能力判断。

Returns

Promise<string>

Remarks

与系统表水位号（RXDB_SYSTEM_SCHEMA_VERSION）无关，那是 RxDB 自己的号。

Inherited from

IRxDBAdapter.version

Extends​

Properties​

name​

Inherited from​

repository_cache​

Inherited from​

repository_map​

Inherited from​

rxdb​

Inherited from​

Methods​

branchExists()?​

Parameters​

Returns​

Inherited from​

connect()​

Returns​

Remarks​

Inherited from​

count()​

Parameters​

Returns​

create()​

Parameters​

Returns​

disconnect()​

Returns​

Remarks​

Inherited from​

fetchMetadata()​

Parameters​

Returns​

Example​

Remarks​

Inherited from​

find()​

Parameters​

Returns​

findByIds()​

Type Parameters​

Parameters​

Returns​

Example​

Remarks​

Inherited from​

getChangeCount()​

Parameters​

Returns​

Inherited from​

getRepository()​

Type Parameters​

Parameters​

Returns​

Remarks​

Inherited from​

isTableExisted()​

Parameters​

Returns​

Remarks​

Inherited from​

mergeChanges()​

Parameters​

Returns​

Remarks​

Inherited from​

mutations()​

Type Parameters​

Parameters​

Returns​

Inherited from​

pullBranches()?​

Returns​

Inherited from​

pullChanges()​

Parameters​

Returns​

Remarks​

Inherited from​

pullChangesBatch()?​

Parameters​

Extends

Properties

name

Inherited from

repository_cache

Inherited from

repository_map

Inherited from

rxdb

Inherited from

Methods

branchExists()?

Parameters

Returns

Inherited from

connect()

Returns

Remarks

Inherited from

count()

Parameters

Returns

create()

Parameters

Returns

disconnect()

Returns

Remarks

Inherited from

fetchMetadata()

Parameters

Returns

Example

Remarks

Inherited from

find()

Parameters

Returns

findByIds()

Type Parameters

Parameters

Returns

Example

Remarks

Inherited from

getChangeCount()

Parameters

Returns

Inherited from

getRepository()

Type Parameters

Parameters

Returns

Remarks

Inherited from

isTableExisted()

Parameters

Returns

Remarks

Inherited from

mergeChanges()

Parameters

Returns

Remarks

Inherited from

mutations()

Type Parameters

Parameters

Returns

Inherited from

pullBranches()?

Returns

Inherited from

pullChanges()

Parameters

Returns

Remarks

Inherited from

pullChangesBatch()?

Parameters