LocalRxDBChangeRepository
Defined in: packages/rxdb/src/system/types.local.ts:68
RxDBChange 本地仓库接口
Extends
Properties
name
readonly name: string;
Defined in: packages/rxdb/src/rxdb-adapter.ts:216
适配器名,与 RxDB.adapter() 登记时用的键同值;错误消息与 getAdapter() 都按它认人
Inherited from
repository_cache
protected readonly repository_cache: Map<EntityType, RepositoryInstance<EntityType>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:326
Inherited from
RemoteRxDBChangeRepository.repository_cache
repository_map
protected readonly repository_map: Map<string, AdapterRepositoryConstructor<LocalRxDBChangeRepository, RepositoryInstance<EntityType>>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:325
Inherited from
RxDBAdapterLocalBase.repository_map
rxdb
readonly rxdb: RxDB;
Defined in: packages/rxdb/src/rxdb-adapter.ts:328
Inherited from
RemoteRxDBChangeRepository.rxdb
Accessors
workingTreeCaptureHook
Get Signature
get workingTreeCaptureHook(): WorkingTreeCaptureHook | undefined;
Defined in: packages/rxdb/src/rxdb-adapter.ts:390
Internal
捕获运行时;未启用提交能力的库上恒为 undefined。
Returns
WorkingTreeCaptureHook | undefined
Inherited from
LocalRxDBChangeRepository.workingTreeCaptureHook
workingTreeRawWriteContext
Get Signature
get workingTreeRawWriteContext(): RawWriteContext;
Defined in: packages/rxdb/src/rxdb-adapter.ts:416
Internal
本适配器当前的 raw 写判定上下文(adapter-contract.md §2)
Remarks
rawQuery?() 是这张接口上的可选方法(见上方 IRxDBAdapter),核心包没法像四个挂载点
那样替适配器包住它——判定只能由各适配器自己的 rawQuery 实现调用 gateRawWrite(sql, ctx, …)。
那句调用要的 ctx 由这里交出来,于是六个适配器需要写对的只有「把它转给判定」这一句,
「能力位怎么算」「域从哪来」两个真正容易写歪的问题一次都不会落到它们头上。
能力位直接由捕获运行时装没装上决定,不另存一个布尔:运行时只在能力位为真时被装上
(RxDB.connect() 读到真、或 workingTree.enable() 刚翻开)。再存一份就是第二份真相,
而两份不同步的后果是单向的——门禁以为没开,raw 写全部放行。上下文对象本身在
setWorkingTreeCaptureHook() 里与运行时同一句赋值建好,不是每次取值新建:取值器在每条
raw 语句上都被调用,而它不含 per-call 状态。两个字段只在那一处一起变,「装了新运行时却
交出绑着旧运行时的闭包」因此不是一种可达状态。
交出去的是判定入口本身,不是判定要看的那些东西(域、列集、受信意图)。核心因此不必 复述捕获认什么,也就不存在「拷了一份域出来、插件后续登记的派生索引列只落进其中一份」这类 双份清单——判定自始至终在运行时手上那一份上跑。
Returns
Inherited from
RxDBAdapterLocalBase.workingTreeRawWriteContext
Methods
bootstrapTransaction()
bootstrapTransaction<T>(fun, transactionLog?): Promise<Awaited<ReturnType<T>>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:535
Internal
执行 引导期(表结构尚未就绪)的事务。
Type Parameters
| Type Parameter |
|---|
T extends TransactionFun |
Parameters
| Parameter | Type | Description |
|---|---|---|
fun | T | 事务回调函数 |
transactionLog? | boolean | 是否写事务日志。默认 true;纯 DDL / 元数据引导应显式传 false |
Returns
Promise<Awaited<ReturnType<T>>>
Remarks
与 transaction 的唯一区别是跳过「引导已完成」就绪门。适配器的就绪门等的正是
RxDB.connect(),而引导期的调用方就在那个 promise 里面 —— 走 transaction 会等自己,
永久挂起。此时表可能尚未建出,调用方自己负责顺序。
调用方限于两类:RxDB.connect() 自身的引导链路(水位线、建表、迁移),以及
在 connect() 内部被安装的插件(它们的 install() 同样跑在那条 promise 里,
见 @aiao/rxdb-plugin-search 的 FTS 安装)。业务代码一律用 transaction。
transactionLog 必须在这里就能传:引导期的 DDL 不属于任何用户变更,写日志会白白触发
一次分支号读取与全量触发器重建。默认实现直接委托 transaction,
只有自带就绪门的适配器需要覆写。
Inherited from
RxDBAdapterLocalBase.bootstrapTransaction
completeBootstrap()
completeBootstrap(): void;
Defined in: packages/rxdb/src/rxdb-adapter.ts:571
Internal
关闭引导窗:RxDB.connect() 完成建表后调用一次。
Returns
void
Remarks
自带就绪门的适配器(SQLite family / PGlite)在引导窗内让 query() / rawQuery() /
createTables() 跳过就绪门 —— 那道门等的正是尚未 settle 的 RxDB.connect()。
本方法把状态翻到 ready,此后所有入口一律走正常的就绪等待。
没有就绪门的 adapter 保持默认的 no-op 实现。
Inherited from
RxDBAdapterLocalBase.completeBootstrap
connect()
connect(): Promise<IRxDBAdapter>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:227
建立连接并把系统表补到当前水位。
Returns
Promise<IRxDBAdapter>
自身,便于链式使用
Remarks
建表与系统迁移都在这里发生(见 isCurrentRxDBSystemVersion),因此它可能很慢,
也可能因为库比本进程新而抛 UnsupportedRxDBSystemVersionError。
Inherited from
count()
count(options): Promise<number>;
Defined in: packages/rxdb/src/system/types.local.ts:83
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.local.ts:90
创建实体
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | RxDBChange | 要创建的实体 |
Returns
Promise<RxDBChange>
返回创建后的实体
createTables()
abstract createTables(EntityTypes, entities?): Promise<boolean>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:575
Parameters
| Parameter | Type |
|---|---|
EntityTypes | EntityType[] |
entities? | any[] |
Returns
Promise<boolean>
Inherited from
RxDBAdapterLocalBase.createTables
deleteByIds()
abstract deleteByIds(entityName, ids): Observable<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:653
按 ID 列表批量删除(QueryCache 专用)
用于清理本地缓存中已被远程删除的数据。
Parameters
| Parameter | Type | Description |
|---|---|---|
entityName | string | 实体名称 |
ids | string[] | 要删除的 ID 列表 |
Returns
Observable<void>
Observable<void>
Example
adapter.deleteByIds('Product', ['p1', 'p2']).subscribe();
Inherited from
RxDBAdapterLocalBase.deleteByIds
disconnect()
disconnect(): Promise<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:236
断开连接并释放底层句柄。
Returns
Promise<void>
Remarks
与 RxDB.destroy() 不同,断开是可逆的:同一个适配器实例之后还能再 connect()。
实现须幂等——未连接时调用是空操作而不是抛错。
Inherited from
find()
find(options): Promise<RxDBChange[]>;
Defined in: packages/rxdb/src/system/types.local.ts:74
find 查询
Parameters
| Parameter | Type | Description |
|---|---|---|
options | FindOptions<typeof RxDBChange, RxDBChangeRuleGroup, RxDBChangeOrderByField> | 查询选项 |
Returns
Promise<RxDBChange[]>
返回查询结果数组
getMetadataByIds()
abstract getMetadataByIds(entityName, ids): Observable<Map<string, string>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:621
获取指定 ID 列表的元数据(QueryCache 专用)
用于本地缓存新鲜度检查,返回 ID → updatedAt 映射。
Parameters
| Parameter | Type | Description |
|---|---|---|
entityName | string | 实体名称 |
ids | string[] | 实体 ID 列表 |
Returns
Observable<Map<string, string>>
Observable<Map<string, string>> - ID → updatedAt 映射
Example
adapter.getMetadataByIds('Product', ['p1', 'p2'])
.subscribe(map => {
// map: Map `{ 'p1' => '2026-01-12T10:00:00Z', 'p2' => '2026-01-12T09:30:00Z' }`
});
Inherited from
RxDBAdapterLocalBase.getMetadataByIds
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
RxDBAdapterLocalBase.getRepository
getRxDBChangeSequence()
abstract getRxDBChangeSequence(): Promise<number>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:582
Returns
Promise<number>
Inherited from
RxDBAdapterLocalBase.getRxDBChangeSequence
isEncryptedAtRest()?
optional isEncryptedAtRest(value): boolean;
Defined in: packages/rxdb/src/rxdb-adapter.ts:471
判定一个落库值是否已处于「加密后的 at-rest 形态」(FR-038)。
Parameters
| Parameter | Type | Description |
|---|---|---|
value | unknown | 落库列里的值;调用方保证它既非 null 也非 undefined |
Returns
boolean
是加密后的落库形态时为 true
Remarks
缺席是契约允许的形态,与 RxDBAdapterLocalBase.reconcileEntityIndexes 同一 口径:不支持列加密的适配器不实现它。缺席不等于放行——调用方(提交写路径)拿不到 判定器却确实有加密列要判时,fail-closed 地抛错,而不是跳过检查。
声明在这里、实现留给适配器,是因为权威判定器是 @aiao/rxdb-adapter-encrypted 的
isEnvelope,而 @aiao/rxdb 不能依赖它:后者 peer-depend 前者,依赖方向是反的。
一个 PropertyType.string 的加密列,明文与密文都是字符串,核心自己猜形状等于装一个
会看走眼的门卫。
与 RxDBAdapterLocalBase.setWorkingTreeCaptureHook 同属「可选能力槽位」:核心 只声明位置与语义,不替六个后端决定有没有。
Inherited from
RxDBAdapterLocalBase.isEncryptedAtRest
isTableExisted()
abstract isTableExisted(EntityType): Promise<boolean>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:509
该实体对应的表在库里是否已存在。
Parameters
| Parameter | Type |
|---|---|
EntityType | EntityType |
Returns
Promise<boolean>
Remarks
问的是物理表,不是元数据里有没有登记这个实体。
Inherited from
RxDBAdapterLocalBase.isTableExisted
mergeChanges()
abstract mergeChanges(
actions,
localChanges?,
disableTriggers?
): Promise<number | void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:598
应用压缩后的变更到本地实体表
实现策略(SQLite):
- 将 actions 转换为 SQL 操作
- 在事务中: a) 执行 SQL 操作实体表(INSERT/UPDATE/DELETE) b) 批量插入 localChanges 到 RxDBChange 表(用于历史追踪)
- 发送本地事件通知 UI 更新
Parameters
| Parameter | Type | Description |
|---|---|---|
actions | SwitchVersionActions | 压缩后的变更操作集合(从远程 pull 来的) |
localChanges? | Omit<RxDBChange, "id">[] | 需要保存到本地 RxDBChange 表的记录(可选) |
disableTriggers? | boolean | 是否禁用触发器(用于 pull 等操作,避免创建 RxDBChange) |
Returns
Promise<number | void>
Inherited from
RxDBAdapterLocalBase.mergeChanges
migrateSystemSchema()
migrateSystemSchema(): Promise<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:505
在应用迁移或仓储运行前升级 RxDB 拥有的表。 不需要持久化系统 schema 状态的 adapter 保持默认的 no-op 实现。
Returns
Promise<void>
Inherited from
RxDBAdapterLocalBase.migrateSystemSchema
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
physicalTableNames()
physicalTableNames(metadata): readonly string[];
Defined in: packages/rxdb/src/rxdb-adapter.ts:497
一张实体表在本适配器发出的 SQL 里可能被写成的全部名字。
Parameters
| Parameter | Type | Description |
|---|---|---|
metadata | EntityMetadata | 实体元数据;答案只由它决定,不读任何实例状态 |
Returns
readonly string[]
未归一化、不带 schema 限定的物理表名;至少一个
Remarks
命名规则归写表的那一方所有。 在这条能力之前,
@aiao/rxdb-plugin-working-tree 的版本化域自己按 '$' 把 sqlite 家族的折叠规则重拼了
一遍。抄来的规则不会因为原件改了而报错,它只是开始算错——而算错的后果是单向的:
raw 写门禁认不出某张受版本控制的表,于是静默放行一条绕过捕获的写。
默认实现交出逻辑名、一个字都不猜。替后端猜一个「常见」形态(比如把 sqlite 家族的
namespace$table 写成默认)只是把抄规则这件事从插件挪到核心,而且从此没有任何一个
后端会因为忘了覆写而被发现——它会一直拿着别人的规则算自己的表名。
有默认实现而不是 abstract,与 RxDBAdapterLocalBase.migrateSystemSchema
同一口径:这是一次对既有基类的扩展,abstract 会让仓外每一个自建适配器在升级时直接
编译不过,而它们里面不折叠命名空间的那一批本来就是对的。代价是「忘了覆写」与
「确实不需要」在类型上同形;折叠命名空间的后端(sqlite 家族)必须自己覆写。
不带 schema 限定:"public"."post" 这种形态在 raw 判定的限定剥离一步里已经被还原成
逻辑名了,这里再登记一遍只是同一个名字的第二种写法。要登记的是剥不掉的那一种。
Inherited from
RxDBAdapterLocalBase.physicalTableNames
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
reconcileEntityIndexes()?
optional reconcileEntityIndexes(EntityTypes): Promise<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:578
在用户迁移和缺表补建后幂等收敛实体索引。
Parameters
| Parameter | Type |
|---|---|
EntityTypes | EntityType[] |
Returns
Promise<void>
Inherited from
RxDBAdapterLocalBase.reconcileEntityIndexes
remove()
remove(entity): Promise<RxDBChange>;
Defined in: packages/rxdb/src/system/types.local.ts:108
删除实体
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
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<LocalRxDBChangeRepository, RT> |
Returns
void
Inherited from
RxDBAdapterLocalBase.repository
runInTransaction()
runInTransaction<T>(fun, transactionLog?): Promise<Awaited<ReturnType<T>>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:556
新开一个事务,或者复用调用方已经在的那个。
Type Parameters
| Type Parameter |
|---|
T extends TransactionFun |
Parameters
| Parameter | Type | Description |
|---|---|---|
fun | T | 事务工作,参数是本次事务的 executor |
transactionLog? | boolean | 是否写事务日志 |
Returns
Promise<Awaited<ReturnType<T>>>
fun 的返回值
Remarks
与 transaction 的差别不在这个方法体里,而在 this 是谁:真实适配器上两者同义,
都新开一个排队事务;而事务内的调用方拿到的是 executor 门面,门面把本方法特判成
executor.run()——复用当前事务且绝不重新入队。SQLite family 与 PGlite 各自的覆写只是
在这一句前面加了断连 / 只读断言,语义与此处逐字相同。
捕获运行时要写工作树行就必须有一个 executor,而「该新开还是该复用」只有调用宿主知道。
直接调 transaction() 的话,事务内的那一半调用会去排队等一个自己正占着的槽位——表现为
永久挂起而不是报错。
Inherited from
RxDBAdapterLocalBase.runInTransaction
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
setWorkingTreeCaptureHook()
setWorkingTreeCaptureHook(hook): void;
Defined in: packages/rxdb/src/rxdb-adapter.ts:437
Internal
装上或卸下捕获运行时(adapter-contract.md §1 的四个挂载点)。
Parameters
| Parameter | Type | Description |
|---|---|---|
hook | WorkingTreeCaptureHook | undefined | 接管四个挂载点的运行时;undefined 卸载 |
Returns
void
Remarks
挂载装在这里而不是让六个适配器各自在自己的 transaction() 里插一句:少写一次、
写晚一次(在业务写之后才校验 token)都没有任何东西能发现,而那正是 §2「判定实现只有
一份」要排除的形态。
调用方是 RxDB.connect()(确认能力位为真之后)与 workingTree.enable()(翻位成功
之后)。未启用的库上一次都不会被调用,于是四个写原语连一层转发都没有。
幂等:已经装过就先卸下再装,不会叠成两层。
Inherited from
RxDBAdapterLocalBase.setWorkingTreeCaptureHook
switchBranch()
abstract switchBranch(options): Promise<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:580
Parameters
| Parameter | Type |
|---|---|
options | SwitchBranchOptions |
Returns
Promise<void>
Inherited from
RxDBAdapterLocalBase.switchBranch
transaction()
Call Signature
abstract transaction<T>(fun, transactionLog?): Promise<Awaited<ReturnType<T>>>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:511
Type Parameters
| Type Parameter |
|---|
T extends TransactionFun |
Parameters
| Parameter | Type |
|---|---|
fun | T |
transactionLog? | boolean |
Returns
Promise<Awaited<ReturnType<T>>>
Inherited from
RxDBAdapterLocalBase.transaction
Call Signature
abstract transaction(fun, transactionLog?): Promise<unknown>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:512
Parameters
| Parameter | Type |
|---|---|
fun | TransactionFun |
transactionLog? | boolean |
Returns
Promise<unknown>
Inherited from
RxDBAdapterLocalBase.transaction
update()
update(entity, patch): Promise<RxDBChange>;
Defined in: packages/rxdb/src/system/types.local.ts:98
更新实体
Parameters
| Parameter | Type | Description |
|---|---|---|
entity | RxDBChange | 要更新的实体 |
patch | Partial<InstanceType<typeof RxDBChange>> | 更新数据 |
Returns
Promise<RxDBChange>
返回更新后的实体
upsertMany()
abstract upsertMany<T>(entityName, data): Observable<void>;
Defined in: packages/rxdb/src/rxdb-adapter.ts:637
批量 upsert 数据(QueryCache 专用)
执行 INSERT OR REPLACE 语义,用于缓存远程拉取的数据。
Type Parameters
| Type Parameter |
|---|
T |
Parameters
| Parameter | Type | Description |
|---|---|---|
entityName | string | 实体名称 |
data | T[] | 要写入的数据列表 |
Returns
Observable<void>
Observable<void>
Example
adapter.upsertMany('Product', [product1, product2]).subscribe();
Inherited from
RxDBAdapterLocalBase.upsertMany
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 自己的号。