PGliteClient

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

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

• 统一的 query/exec/transaction API（对齐 IPGliteClient）
• 系统表（rxdb_change/rxdb_branch/rxdb_migration）NOTIFY 监听 + 16ms 防抖批量分发
• 安全的 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

Methods

addEventListener()

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

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

添加事件监听器

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:242

描述查询

Parameters

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

Returns

Promise<DescribeQueryResult>

查询结果类型的描述

Implementation of

IPGliteClient.describeQuery

---

disconnect()

disconnect(): Promise<void>;

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

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

在 relaxedDurability + IDBFS 后端下，必须先 syncToFs 把 cursor 写回， 否则关闭后 Emscripten 残余回调会抛 InvalidStateError。

Returns

Promise<void>

Implementation of

IPGliteClient.disconnect

---

dispatchEvent()

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

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

分发事件

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

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

Returns

void

Inherited from

EventDispatcher.dispatchEvent

---

exec()

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

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

执行 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:269

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

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

Returns

Promise<boolean>

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

---

hasEventListener()

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

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

检查是否已添加指定的事件监听器

Type Parameters

Type Parameter
T extends keyof PGliteClientEvents

Parameters

Parameter	Type	Description
type	T	事件类型
listener	EventListener<PGliteClientEvents[T]>	事件监听器函数

Returns

boolean

如果已添加监听器则返回true，否则返回false

Inherited from

EventDispatcher.hasEventListener

---

init()

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

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

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

必须在任何 query/exec 之前调用一次。重复调用会创建新实例但不会清理旧的， 推荐通过 disconnect 释放后再重新 init。

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:258

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

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
query	string
params?	any[] | 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:238

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

Type Parameters

Type Parameter
T

Parameters

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

Returns

Promise<Results<T>>

查询的结果

Implementation of

IPGliteClient.query

---

removeAllEventListeners()

removeAllEventListeners(): void;

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

移除所有事件监听器

Returns

void

Inherited from

EventDispatcher.removeAllEventListeners

---

removeEventListener()

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

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

移除事件监听器

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:250

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

Type Parameters

Type Parameter
T

Parameters

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

Returns

Promise<T>

函数的结果

Implementation of

IPGliteClient.runExclusive

---

sql()

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

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

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

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

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
sqlStrings	TemplateStringsArray
...params	any[]

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:246

执行事务

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:324

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

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

Returns

Promise<string>

Implementation of

IPGliteClient.version