PGliteClient

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:361

PGlite 客户端：封装 @electric-sql/pglite 实例，提供：

• 统一的 query/exec/transaction API（对齐 IPGliteClient）
• 系统表（rxdb_change/rxdb_branch/rxdb_migration）NOTIFY 监听 + 批量分发 （16ms trailing 防抖，另有 max-wait 与容量上限兜底，见 PGliteNotificationBatcher）
• 安全的 disconnect（先 syncToFs 再 close，避免 IDBFS 关闭后回调抛错）
• LiveQuery 支持（依赖 init 阶段注入的 live extension）

通过 addEventListener(PGliteChangeType.INSERT, fn) 订阅变更事件， 类型由 PGliteClientEvents 推导。

Extends

• EventDispatcher<PGliteClientEvents>

Implements

• IPGliteClient

Constructors

Constructor

new PGliteClient(): PGliteClient;

Returns

PGliteClient

Inherited from

EventDispatcher.constructor

Accessors

pendingNotificationCount

Get Signature

get pendingNotificationCount(): number;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:390

尚未分发的 NOTIFY 行事件数量。

Returns

number

尚未分发的 NOTIFY 行事件数量。

Implementation of

IPGliteClient.pendingNotificationCount

Methods

addEventListener()

addEventListener<T>(type, listener): void;

Defined in: packages/utils/dist/tools/event.d.ts:32

注册监听器。同一 listener 重复注册只保留一份（集合语义）。

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

Parameter	Type	Description
type	T	事件名
listener	EventListener<PGliteClientEvents[T]>	监听器

Returns

void

Inherited from

EventDispatcher.addEventListener

---

describeQuery()

describeQuery(query, options?): Promise<DescribeQueryResult>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:429

描述查询

Parameters

Parameter	Type	Description
query	string	要描述的查询
options?	QueryOptions	-

Returns

Promise<DescribeQueryResult>

查询结果类型的描述

Remarks

可选：DescribeQueryResult 里挂着解析器函数，跨不了结构化克隆，因此 US-208 的桌面 代理客户端提供不了它。适配器自身一处都没调用，声明成必需只会把「本地实现不了」 变成「必须编一个假的」。

Implementation of

IPGliteClient.describeQuery

---

disconnect()

disconnect(): Promise<void>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:526

安全断开 PGlite 连接：取消订阅、清空待处理事件、syncToFs 后 close。

在 relaxedDurability + IDBFS 后端下，必须先 syncToFs 把 cursor 写回， 否则关闭后 Emscripten 残余回调会抛 InvalidStateError。 durability flush 失败时仍会释放全部资源，随后抛出 DURABILITY_LOST。

Returns

Promise<void>

Implementation of

IPGliteClient.disconnect

---

dispatchEvent()

dispatchEvent<T>(type, data): void;

Defined in: packages/utils/dist/tools/event.d.ts:60

同步派发事件。

遍历的是快照而非实时集合：监听器在处理过程中 addEventListener 不会自喂 本轮迭代（否则单次同步派发可被第三方监听器无限延长，UTL-011）。

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

Parameter	Type	Description
type	T	事件名
data	PGliteClientEvents[T]	事件数据

Returns

void

Throws

监听器抛出的任意异常，原样向上冒泡；其后的监听器不再执行

Inherited from

EventDispatcher.dispatchEvent

---

exec()

exec(query, options?): Promise<Results[]>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:421

执行 SQL 查询，可以包含多个语句 使用 PostgreSQL 的"简单查询"协议消息

Parameters

Parameter	Type	Description
query	string	要执行的查询
options?	QueryOptions	-

Returns

Promise<Results[]>

查询的结果

Implementation of

IPGliteClient.exec

---

flushPendingNotifications()

flushPendingNotifications(): Promise<boolean>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:508

立即冲刷未发送的 NOTIFY 事件，绕过 16ms 防抖。

用于测试断言"事件已分发"的场景，或在关键路径（事务提交后）需要立即感知变更。

Returns

Promise<boolean>

调用时是否存在待处理事件

---

forceClose()

forceClose(): Promise<void>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:534

跳过 durability flush，直接取消订阅并关闭 runtime。 调用方必须显式接受尚未落盘的数据可能丢失。

Returns

Promise<void>

Implementation of

IPGliteClient.forceClose

---

hasEventListener()

hasEventListener<T>(type, listener): boolean;

Defined in: packages/utils/dist/tools/event.d.ts:40

查询监听器是否已注册。不会为未知事件名建立集合。

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

Parameter	Type	Description
type	T	事件名
listener	EventListener<PGliteClientEvents[T]>	监听器

Returns

boolean

是否已注册

Inherited from

EventDispatcher.hasEventListener

---

hasStoragePeer()

hasStoragePeer(): boolean;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:442

判断当前是否有其他存活客户端持有同一份持久化存储。

Returns

boolean

Implementation of

IPGliteClient.hasStoragePeer

---

init()

init(dbName, options): Promise<void>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:403

初始化 PGlite 运行时并订阅系统表 NOTIFY 频道。

必须在任何 query/exec 之前调用。重复调用会先完整关闭旧运行时， 并发调用共享同一个初始化任务。

Parameters

Parameter	Type	Description
dbName	string	数据库名（用于 IndexedDB 持久化与 Worker 命名）
options	PGliteClientOptions	PGlite 选项；store: 'memory' 用于测试，其他值持久化

Returns

Promise<void>

Implementation of

IPGliteClient.init

---

liveQuery()

liveQuery<T>(
   query, 
   params?, 
   callback?
): Promise<LiveQuery<T>>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:493

创建 live query，借助 @electric-sql/pglite/live 插件。 依赖 init() 时已加载的 live extension。

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
query	string
params?	unknown[] | null
callback?	(results) => void

Returns

Promise<LiveQuery<T>>

Implementation of

IPGliteClient.liveQuery

---

query()

query<T>(
   query, 
   params?, 
   options?
): Promise<Results<T>>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:425

执行单个 SQL 语句 使用 PostgreSQL 的"扩展查询"协议消息

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
query	string	要执行的查询语句
params?	unknown[]	查询的可选参数
options?	QueryOptions	-

Returns

Promise<Results<T>>

查询的结果

Implementation of

IPGliteClient.query

---

removeAllEventListeners()

removeAllEventListeners(): void;

Defined in: packages/utils/dist/tools/event.d.ts:62

清空所有事件名下的全部监听器。

Returns

void

Inherited from

EventDispatcher.removeAllEventListeners

---

removeEventListener()

removeEventListener<T>(type, listener): void;

Defined in: packages/utils/dist/tools/event.d.ts:49

移除监听器。未知事件名或未注册的监听器都是无操作，且不会建立空集合。

若在 dispatchEvent 过程中移除，被移除者仍会收到本次事件（快照语义）。

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

Parameter	Type	Description
type	T	事件名
listener	EventListener<PGliteClientEvents[T]>	监听器

Returns

void

Inherited from

EventDispatcher.removeEventListener

---

runExclusive()

runExclusive<T>(fn): Promise<T>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:437

独占运行函数，在函数运行期间不允许其他事务或查询 这在使用 execProtocol 方法时特别有用，因为它们不会被阻塞， 也不会阻塞事务和查询使用的锁

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
fn	() => Promise<T>	要运行的函数

Returns

Promise<T>

函数的结果

Remarks

可选，理由与 IPGliteClient.describeQuery 同类但更硬：fn 是调用方的闭包， 跨进程传不过去；真要代理，只能让 renderer 在整个 fn 期间扣住主进程那条唯一连接， 而 renderer 崩溃时这把锁就永远松不开了。

Implementation of

IPGliteClient.runExclusive

---

snapshotDataDir()

snapshotDataDir<T>(fn): Promise<T>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:471

独占运行时、做一次 CHECKPOINT，然后把 Emscripten 数据目录的遍历交给 fn。

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
fn	(items) => Promise<T>	读取数据目录的回调

Returns

Promise<T>

fn 的结果

Remarks

同时拿住 PGlite 的查询锁与事务锁：fn 运行期间没有任何语句能改动数据目录， 于是它看到的就是 checkpoint 之后的一致快照。fn 越慢，数据库被挡住越久。

这两把锁只管得住本运行时。IndexedDB 存储上每个连接各有一份内存文件系统，别的连接（同页面的 另一个实例、其他标签页或 Worker）提交后同步进 IndexedDB，却不会出现在本运行时的视图里， 所以存储还有别的持有者、或本连接打开时 / 打开之后有过别的持有者（哪怕它们已经关闭）时， 快照都不代表库的已提交状态，只能拒绝，重新连接后再备份。SQLite 各后端没有这个问题： 所有连接共享同一个数据库文件。

Throws

RxDBBackupError unsupported_combination 运行时不在当前线程（OPFS-AHP Worker），或当前 PGlite 版本缺少快照依赖的内部件； target_busy 同一份 IndexedDB 存储还有其他连接，或本连接打开以来有过其他连接； unsupported_combination IndexedDB 存储所在环境没有 navigator.locks.query()

Implementation of

IPGliteClient.snapshotDataDir

---

sql()

sql<T>(sqlStrings, ...params): Promise<Results<T>>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:417

执行单个 SQL 语句，类似于 query，但使用模板语句，其中模板值将被视为参数

使用 PostgreSQL 的"扩展查询"协议消息

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
sqlStrings	TemplateStringsArray
...params	unknown[]

Returns

Promise<Results<T>>

查询的结果

Example

const results = await db.sql`SELECT * FROM ${identifier`foo`} WHERE id = ${id}`

Implementation of

IPGliteClient.sql

---

transaction()

transaction<T>(callback): Promise<T>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:433

执行事务

Type Parameters

Type Parameter
T

Parameters

Parameter	Type	Description
callback	(tx) => Promise<T>	接收事务对象的回调函数

Returns

Promise<T>

事务的结果

Implementation of

IPGliteClient.transaction

---

version()

version(): Promise<string>;

Defined in: packages/rxdb-adapter-pglite/src/PGliteClient.ts:543

返回底层 PostgreSQL 版本字符串（执行 SELECT version()）。

主要用于诊断与日志，不要在热路径调用。

Returns

Promise<string>

Implementation of

IPGliteClient.version