RxDBAdapterPGlite

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:76

RxDB PGlite 适配器

基于 PGlite（WebAssembly PostgreSQL）的本地存储适配器提供完整的关系型数据库功能，包括：

实体持久化和查询
事务管理
分支管理（用于多版本数据管理）
变更历史追踪

Extends

RxDBAdapterLocalBase

Implements

IRxDBAdapter

Constructors

Constructor

new RxDBAdapterPGlite(rxdb, options): RxDBAdapterPGlite;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:155

构造函数

Parameters

Parameter	Type	Description
`rxdb`	`RxDB`	RxDB 实例
`options`	`PGliteClientOptions`	PGlite 客户端配置选项

Returns

RxDBAdapterPGlite

Overrides

RxDBAdapterLocalBase.constructor

Properties

name

name: string = ADAPTER_NAME;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:117

适配器名称

Implementation of

IRxDBAdapter.name

repository_cache

protected readonly repository_cache: Map<EntityType, IRepository<any>>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:112

Inherited from

RxDBAdapterLocalBase.repository_cache

repository_map

protected readonly repository_map: Map<string, RepositoryConstructor<any>>;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:111

Inherited from

RxDBAdapterLocalBase.repository_map

rxdb

readonly rxdb: RxDB;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:110

Inherited from

RxDBAdapterLocalBase.rxdb

Accessors

encryption

Get Signature

get encryption(): AdapterEncryptionFacade;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:123

Returns

AdapterEncryptionFacade

encryptionContext

Get Signature

get encryptionContext(): EncryptionContext;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:119

Returns

EncryptionContext

Methods

connect()

connect(): Promise<IRxDBAdapter>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:398

连接到数据库

Returns

Promise<IRxDBAdapter>

适配器实例

Implementation of

IRxDBAdapter.connect

createBranch()

createBranch(branchId, fromChangeId?): Promise<RxDBBranch>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:455

创建分支

分支用于管理数据的不同版本，类似 Git 分支：

验证分支 ID 不存在
确定源分支（从当前活跃分支或指定变更点）
创建新分支记录

Parameters

Parameter	Type	Description
`branchId`	`string`	新分支 ID
`fromChangeId?`	`number`	从指定变更 ID 创建分支（可选，默认从当前分支的最新状态）

Returns

Promise<RxDBBranch>

Throws

分支 ID 已存在或源分支未找到

createTables()

createTables<T>(EntityTypes, entities?): Promise<boolean>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:549

创建数据库表

分三阶段创建表结构：

创建表和列（不含外键约束）
添加外键约束
创建触发器（用于变更追踪）

这样可以避免因表创建顺序导致的外键约束失败

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`EntityTypes`	`T`[]	实体类型数组
`entities?`	`InstanceType`<`T`>[]	初始化数据（可选）

Returns

Promise<boolean>

是否成功创建

Overrides

RxDBAdapterLocalBase.createTables

deleteByIds()

deleteByIds(entityName, ids): Observable<void>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:251

批量删除实体（QueryCache 专用）

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名称（不含 schema）
`ids`	`string`[]	要删除的 ID 列表

Returns

Observable<void>

Observable<void>

Overrides

RxDBAdapterLocalBase.deleteByIds

disconnect()

disconnect(): Promise<void>;

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

断开数据库连接

清理资源并发送销毁信号

Returns

Promise<void>

Implementation of

IRxDBAdapter.disconnect

getMetadataByIds()

getMetadataByIds(entityName, ids): Observable<Map<string, string>>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:171

批量获取实体元数据（QueryCache 专用）

返回 id → updatedAt 的映射，用于 diffMetadata 对比。

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名称（不含 schema）
`ids`	`string`[]	要查询的 ID 列表

Returns

Observable<Map<string, string>>

Observable<Map<string, string>> - id → updatedAt 映射

Overrides

RxDBAdapterLocalBase.getMetadataByIds

getRepository()

getRepository<T, RT>(entity): RT;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:514

获取实体类型的仓库实例

根据实体元数据中的仓库类型创建相应的仓库实例：

Repository: 通用仓库
TreeRepository: 树形仓库（用于层级数据）

仓库实例会被缓存，避免重复创建

Type Parameters

Type Parameter	Default type
`T` extends `EntityType`	-
`RT`	`IRepository`<`T`>

Parameters

Parameter	Type	Description
`entity`	`T`	实体类型

Returns

RT

仓库实例

Throws

不支持的仓库类型

Implementation of

IRxDBAdapter.getRepository

Overrides

RxDBAdapterLocalBase.getRepository

getRxDBChangeSequence()

getRxDBChangeSequence(): Promise<number>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:299

获取 RxDBChange 表当前序列值

用于同步时获取本地变更序列的当前值，以便确定需要推送到远程的变更范围。

Returns

Promise<number>

当前序列值

Overrides

RxDBAdapterLocalBase.getRxDBChangeSequence

getTableColumns()

getTableColumns<T>(EntityType): Promise<PgliteTableColumn[]>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:684

获取表的列信息

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`EntityType`	`T`	实体类型

Returns

Promise<PgliteTableColumn[]>

列信息数组

internalQuery()

internalQuery(sql, params?): Promise<Results<any>>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:807

内部查询方法 (Public Alias) 供核心同步逻辑使用，绕过队列直接查询

Parameters

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

Returns

Promise<Results<any>>

isTableExisted()

isTableExisted(EntityType): Promise<boolean>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:665

判断表是否存在

Parameters

Parameter	Type	Description
`EntityType`	`EntityType`	实体类型

Returns

Promise<boolean>

表是否存在

Implementation of

IRxDBAdapter.isTableExisted

Overrides

RxDBAdapterLocalBase.isTableExisted

liveQuery()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:859

创建 PGlite live query（PGlite 独有特性）

在底层查询结果变化时自动回调，避免 NOTIFY 触发器 + 手动 refetch 的额外逻辑。适合用户自定义 SQL 场景（聚合、JSONB、全文检索等）。

Type Parameters

Type Parameter	Default type
`T`	`Record`<`string`, `unknown`>

Parameters

Parameter	Type	Description
`sql`	`string`	查询语句
`params?`	`unknown`[]	查询参数
`callback?`	(`results`) => `void`	初始化以及后续结果变更时的回调

Returns

Promise<LiveQuery<T>>

LiveQuery 对象（含 subscribe/unsubscribe/refresh），由调用方负责 unsubscribe

Example

const handle = await adapter.liveQuery(
  'SELECT count(*)::int AS total FROM "public"."todo" WHERE completed = $1',
  [false],
  res => console.log(res.rows[0].total)
);
// 不再使用时：
await handle.unsubscribe();

localRxDBBranch()

localRxDBBranch(): PGliteRepository<typeof RxDBBranch>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:701

获取本地分支仓库

Returns

PGliteRepository<typeof RxDBBranch>

分支仓库实例

localRxDBChange()

localRxDBChange(): PGliteRepository<typeof RxDBChange>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:710

获取本地变更仓库

Returns

PGliteRepository<typeof RxDBChange>

变更仓库实例

mergeChanges()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:283

合并远程变更到本地实体表

用于同步时应用远程变更到本地数据库，支持禁用触发器以避免产生本地变更记录

Parameters

Parameter	Type	Default value	Description
`actions`	`SwitchVersionActions`	`undefined`	需要执行的变更操作（插入、更新、删除）
`localChanges?`	`Omit`<`RxDBChange`, `"id"`>[]	`undefined`	（已废弃）不再使用，Pull 来的数据不应该生成 RxDBChange 记录
`disableTriggers?`	`boolean`	`false`	是否禁用触发器（用于 pull 等操作，避免创建 RxDBChange）

Returns

Promise<void>

Deprecated

localChanges 参数已废弃，将在未来版本中移除

Overrides

RxDBAdapterLocalBase.mergeChanges

mutations()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:265

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

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`mutations`	`RxDBMutationsMap`<`T`>	批量修改选项

Returns

Promise<InstanceType<T>[]>

Implementation of

IRxDBAdapter.mutations

query()

query(sql, bindings?): Promise<Results<any>>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:787

执行 SQL 查询

查询执行策略：

在事务中：直接在事务上下文中执行
非事务中：加入队列按顺序执行，避免并发冲突

Parameters

Parameter	Type	Description
`sql`	`string`	SQL 语句
`bindings?`	`any`[]	参数绑定

Returns

Promise<Results<any>>

查询结果

rawQuery()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:821

执行原始 SQL（IRxDBAdapter 可选方法）

用于条件 UPDATE、INSERT 等需要绕过 ORM 的场景。使用 rowMode: 'array' 让 rows 以数组形式返回，对齐 RawQueryResult 结构。

Parameters

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

Returns

Promise<RawQueryResult>

原始查询结果（行数、行数据、列名）

Implementation of

IRxDBAdapter.rawQuery

removeMany()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:332

批量删除实体

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`entities`	`InstanceType`<`T`>[]	要删除的实体数组

Returns

Promise<InstanceType<T>[]>

已删除的实体数组

Implementation of

IRxDBAdapter.removeMany

repository()

protected repository<RT>(repositoryName, RepositoryClass): void;

Defined in: packages/rxdb/dist/rxdb-adapter.d.ts:120

注册适配器的仓库

Type Parameters

Type Parameter
`RT` extends `RepositoryBase`<`any`>

Parameters

Parameter	Type
`repositoryName`	`string`
`RepositoryClass`	`RepositoryConstructor`<`RT`>

Returns

void

Inherited from

RxDBAdapterLocalBase.repository

restoreEntity()

restoreEntity<T>(_entity, _options): Promise<InstanceType<T>>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:482

恢复实体到指定状态

从变更历史中恢复实体到指定的版本

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`_entity`	`InstanceType`<`T`>	要恢复的实体
`_options`	`RestoreEntityOptions`	恢复选项

Returns

Promise<InstanceType<T>>

恢复后的实体

Throws

此功能尚未实现

saveMany()

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

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:362

批量保存实体

将实体持久化到数据库：

按实体类型分组（避免混合不同表的数据）
为每个类型生成批量插入 SQL（使用 UPSERT）
在事务中执行（如果尚未在事务中）
更新实体状态标记

Type Parameters

Type Parameter
`T` extends `EntityType`

Parameters

Parameter	Type	Description
`entities`	`InstanceType`<`T`>[]	要保存的实体数组

Returns

Promise<InstanceType<T>[]>

已保存的实体数组

Implementation of

IRxDBAdapter.saveMany

setRxDBChangeSequence()

setRxDBChangeSequence(sequence): Promise<void>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:320

设置 RxDBChange 表序列值

用于同步时调整本地变更序列值，通常在 pull 操作后更新序列以避免与远程冲突。

Parameters

Parameter	Type	Description
`sequence`	`number`	要设置的序列值

Returns

Promise<void>

switchBranch()

switchBranch(options): Promise<void>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:467

切换到指定分支

切换数据库分支，包括更新触发器、执行数据迁移操作和更新分支状态

Parameters

Parameter	Type	Description
`options`	`SwitchBranchOptions`	分支切换选项，包含目标分支 ID 和可选的数据迁移操作

Returns

Promise<void>

Throws

分支切换失败

Overrides

RxDBAdapterLocalBase.switchBranch

transaction()

transaction<T>(transactionFun, transactionLog?): Promise<Awaited<ReturnType<T>>>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:729

执行事务

事务管理策略：

使用手动 BEGIN/COMMIT/ROLLBACK 控制事务边界
使用 SET CONSTRAINTS ALL DEFERRED 延迟外键约束检查到提交时
动态重建触发器以注入 transactionId（与 SQLite 方案一致）
PostgreSQL 不允许在有 pending trigger events 时修改表结构，因此无法使用列默认值方案，必须重建触发器

Type Parameters

Type Parameter
`T` extends `TransactionFun`

Parameters

Parameter	Type	Default value	Description
`transactionFun`	`T`	`undefined`	事务函数
`transactionLog`	`boolean`	`true`	是否启用事务日志（默认 true）

Returns

Promise<Awaited<ReturnType<T>>>

事务函数的返回值

Throws

事务执行失败

Overrides

RxDBAdapterLocalBase.transaction

upsertMany()

upsertMany<T>(entityName, data): Observable<void>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:202

批量更新或插入实体（QueryCache 专用）

使用 INSERT ... ON CONFLICT DO UPDATE 实现 upsert 语义。

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type	Description
`entityName`	`string`	实体名称（不含 schema）
`data`	`T`[]	要写入的数据数组

Returns

Observable<void>

Observable<void>

Overrides

RxDBAdapterLocalBase.upsertMany

version()

version(): Promise<string>;

Defined in: packages/rxdb-adapter-pglite/src/RxDBAdapterPGlite.ts:496

获取 PostgreSQL 版本

Returns

Promise<string>

PostgreSQL 版本字符串

Implementation of

IRxDBAdapter.version

Extends​

Implements​

Constructors​

Constructor​

Parameters​

Returns​

Overrides​

Properties​

name​

Implementation of​

repository_cache​

Inherited from​

repository_map​

Inherited from​

rxdb​

Inherited from​

Accessors​

encryption​

Get Signature​

Returns​

encryptionContext​

Get Signature​

Returns​

Methods​

connect()​

Returns​

Implementation of​

createBranch()​

Parameters​

Returns​

Throws​

createTables()​

Type Parameters​

Parameters​

Returns​

Overrides​

deleteByIds()​

Parameters​

Returns​

Overrides​

disconnect()​

Returns​

Implementation of​

getMetadataByIds()​

Parameters​

Returns​

Overrides​

getRepository()​

Type Parameters​

Parameters​

Returns​

Throws​

Implementation of​

Overrides​

getRxDBChangeSequence()​

Returns​

Overrides​

getTableColumns()​

Type Parameters​

Parameters​

Returns​

internalQuery()​

Parameters​

Returns​

isTableExisted()​

Parameters​

Returns​

Implementation of​

Overrides​

liveQuery()​

Type Parameters​

Parameters​

Returns​

Example​

localRxDBBranch()​

Returns​

localRxDBChange()​

Returns​

mergeChanges()​

Parameters​

Extends

Implements

Constructors

Constructor

Parameters

Returns

Overrides

Properties

name

Implementation of

repository_cache

Inherited from

repository_map

Inherited from

rxdb

Inherited from

Accessors

encryption

Get Signature

Returns

encryptionContext

Get Signature

Returns

Methods

connect()

Returns

Implementation of

createBranch()

Parameters

Returns

Throws

createTables()

Type Parameters

Parameters

Returns

Overrides

deleteByIds()

Parameters

Returns

Overrides

disconnect()

Returns

Implementation of

getMetadataByIds()

Parameters

Returns

Overrides

getRepository()

Type Parameters

Parameters

Returns

Throws

Implementation of

Overrides

getRxDBChangeSequence()

Returns

Overrides

getTableColumns()

Type Parameters

Parameters

Returns

internalQuery()

Parameters

Returns

isTableExisted()

Parameters

Returns

Implementation of

Overrides

liveQuery()

Type Parameters

Parameters

Returns

Example

localRxDBBranch()

Returns

localRxDBChange()

Returns

mergeChanges()

Parameters