TransactionExecutor

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:41

一次事务的作用域句柄。

Remarks

持有它 = 有权在该事务内执行；未持有 = 必须重新排队。 事务身份由对象标识表示，不再由适配器实例上的布尔环境态（#transaction_lock）推断。

存在的理由：布尔环境态跨 await 无法区分两类调用 —— 事务体内的合法嵌套 （record.save() → entityManager.mutations → adapter.mutations）与外部并发写 （QueryCache / 远端同步在事务窗口内的独立写入）。两者走同一个入口，一律按「嵌套」处理 会让外部写入被卷进他人事务并跟着 ROLLBACK 一起丢失（SQLC-001 / PGL-001）， 一律按「外部」处理又会把启动流程锁死。

设计见 code-reviews/transaction-executor-design.md §4。

Example

await adapter.transaction(async executor => {
  // 走 executor 的读写归属本事务
  const repository = executor.getRepository(Todo);
  const todos = await repository.find({ where: { combinator: 'and', rules: [] } });
  await repository.update(todos[0], { done: true });
});

Properties

id

readonly id: string;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:48

事务标识，用于日志与断言。

Remarks

不要用它判断两个 executor 是否同一个事务 —— 用对象标识（a === b）。

---

state

readonly state: TransactionExecutorState;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:51

生命周期状态。

Methods

getRepository()

getRepository<T>(EntityType): IRepository<T>;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:99

在本事务内取仓库。

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
EntityType	T	实体类型

Returns

IRepository<T>

Remarks

由该仓库发出的读写一律归属本事务，读也一样 —— 事务体内经普通 adapter.query() 的读会排在自己这个事务后面，造成挂起（队列并发度为 1）。

该仓库创建或加载出的实体会被登记到本 executor 名下，因此这些实体的 entity.save() / entity.remove() 也自动走本事务；用 new X() 直接建的实体 不带这个身份，会走普通队列。

---

mergeChanges()

mergeChanges(
   actions, 
   localChanges?, 
   disableTriggers?
): Promise<void>;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:134

在本事务内应用压缩后的变更。

Parameters

Parameter	Type	Description
actions	SwitchVersionActions	压缩后的变更操作集合
localChanges?	Omit<RxDBChange, "id">[]	需要一并写入本地 RxDBChange 表的记录
disableTriggers?	boolean	是否禁用变更触发器（pull 等场景）

Returns

Promise<void>

Remarks

之所以放在 executor 上而不是给 adapter.mergeChanges() 加一个 executor 形参： 「持有 executor 才算在本事务内」这条判据必须只有一处。散成两处之后， 「传了 executor 形参」与「调的是 executor 的方法」会各自演化出不同的边界。

同步链路里 4 个事务体的主力写就是它（merge-branch / cleanup-expired / pull-batch / pull-repository）。

---

mutations()

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

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:84

在本事务内执行实体变更。

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
options	RxDBMutationsMap<T>	批量变更集合

Returns

Promise<InstanceType<T>[]>

---

query()

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

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:59

在本事务内执行原始查询，不再入队。

Parameters

Parameter	Type	Description
sql	string	SQL 语句
params?	readonly unknown[]	绑定参数

Returns

Promise<RawQueryResult>

---

removeMany()

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

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:117

在本事务内删除多个实体。

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
entities	InstanceType<T>[]	待删除的实体

Returns

Promise<InstanceType<T>[]>

---

run()

run<T>(fun): Promise<T>;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:149

嵌套内层工作：复用本事务，不新开，也不入队。

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
fun	(executor) => Promise<T>	内层工作，参数是同一个事务的 executor

Returns

Promise<T>

Remarks

取代旧的 runInTransaction() —— 后者靠环境态判断「是否已在事务中」， 拿它开一个语义上独立的并发事务会被静默并进当前事务。

---

saveMany()

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

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:110

在本事务内保存多个实体。

Type Parameters

Type Parameter
T extends EntityType

Parameters

Parameter	Type	Description
entities	InstanceType<T>[]	待保存的实体

Returns

Promise<InstanceType<T>[]>

Remarks

与 adapter.saveMany() 同语义，区别只在归属：这一份属于本事务。 事务体内调 adapter.saveMany() 是外部调用，会重新排队并排在本事务之后。

---

tableRef()

tableRef(EntityType): string;

Defined in: packages/rxdb/src/transaction/transaction-executor.interface.ts:77

把实体解析成本后端的物理表引用，已按方言加好引号，可直接拼进 SQL。

Parameters

Parameter	Type	Description
EntityType	EntityType	实体类型

Returns

string

可直接插入 SQL 的表引用

Remarks

metadata.tableName 是逻辑表名，不是任何后端的物理表名：PGlite 把 namespace 建成 schema（"rxdb"."rxdb_commit_capability"），SQLite 家族把它拼成表名前缀 （"rxdb$rxdb_commit_capability"）。拿 tableName 直接拼 SQL 在两边都找不到表。

命名规则属于适配器，不属于本包 —— 所以由 executor 回答，而不是在 packages/rxdb 里按后端分叉再抄一份。只服务 system/sql-literal.ts 说的那一类语句（单条、无占位符 的 CAS）；普通读写走 getRepository / mutations，那里的表名由适配器 自己解析，调用方不需要知道物理命名。