rxdb-adapter-pglite
RxDB 适配器，使用 PGlite 在浏览器中运行 PostgreSQL。
功能特性
- 本地优先: 在浏览器中通过 WebAssembly 运行完整 PostgreSQL
- 零服务器: 无需后端服务器，数据存储在本地
- PostgreSQL 兼容: 支持标准 PostgreSQL 语法和功能
- 响应式: 数据变化自动触发更新
何时使用
- 需要 PostgreSQL 特性（如 JSONB、tsvector 全文搜索、高级索引）
- 计划未来迁移到 PostgreSQL 后端
- 需要更强的 SQL 标准兼容性
- 应用需要复杂查询和事务支持
与其他适配器对比
| 特性 | PGlite | wa-sqlite | sqlite-wasm |
|---|---|---|---|
| 数据库引擎 | PostgreSQL | SQLite | SQLite |
| WASM 大小 | ~3MB | ~500KB | ~800KB |
| 全文搜索 | tsvector | FTS5 | FTS5 |
| JSON 支持 | JSONB | JSON1 | JSON1 |
| 生态兼容 | PostgreSQL | SQLite | SQLite |
安装
npm install @aiao/rxdb-adapter-pglite
# 或
pnpm add @aiao/rxdb-adapter-pglite
使用
import { createRxdb } from '@aiao/rxdb';
import { createPgliteAdapter } from '@aiao/rxdb-adapter-pglite';
const db = await createRxdb({
adapter: createPgliteAdapter()
});
完整示例
参考 dev-rxdb-angular 中的集成示例。
@aiao/rxdb-adapter-pglite — RxDB 适配器（PGlite / WebAssembly PostgreSQL 后端）。
公开三层 API：
- 适配器与客户端：RxDBAdapterPGlite, PGliteClient
- 数据访问：通过 RxDBAdapterPGlite 获取的 Repository
- SQL 生成（纯函数）：
create_tables_sql,generate_trigger_sql,notify_function_sql，以及 PG 原生 FTS 模块（fts/）
测试工具单独从 @aiao/rxdb-adapter-pglite/testing 子路径导入，避免污染运行时包。
Enumerations
| Enumeration | Description |
|---|---|
| PGliteChangeType | PGlite 变更事件类型枚举 对应 PostgreSQL 的 TG_OP (trigger operation) |
Classes
| Class | Description |
|---|---|
| PGliteClient | 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） |
| PostgreSQLDialect | PostgreSQL 方言实现 |
| RxDBAdapterPGlite | RxDB PGlite 适配器 |
| RxdbAdapterPGliteError | PGlite 适配器错误类 |
Interfaces
| Interface | Description |
|---|---|
| AdapterEncryptionFacade | Developer-facing facade exposed at adapter.encryption. Forwards to the internal Keyring. If no entity in the database declares an encrypted column, every method throws EncryptedConfigurationError(code: 'no_encrypted_columns'). |
| EncryptionContext | Encryption context threaded through every PGlite helper that may touch an encrypted column. When no encrypted columns exist the keyring is null and the helpers fall through to their plaintext branches. Mirrors the sqlite-core EncryptionContext shape. |
| FtsField | FTS 字段描述符。 |
| FtsOptions | FTS DDL 生成选项。 |
| IPGliteClient | PGlite 客户端的最小公开契约。 |
| ISqlDialect | SQL 方言接口 定义数据库特定的 SQL 语法转换方法 |
| PGliteChangeEvent | PGlite 变更事件 触发器通过 NOTIFY 发送的数据库变更事件 |
| PGliteClientEvents | PGlite 客户端事件映射： 每个 PGliteChangeType 对应一个 PGliteChangeEvent， 用于 PGliteClient（基于 EventDispatcher）的 addEventListener 强类型推断。 |
| PGliteClientOptions | PGlite 客户端配置选项 扩展自 PGlite 原生配置 |
| PGliteNotifyPayload | PGlite 通知 payload 结构 从 NOTIFY 消息中解析的数据 |
| PgliteTableColumn | PGlite 数据库表列信息接口 包含 PostgreSQL information_schema.columns 视图的所有字段 |
Type Aliases
| Type Alias | Description |
|---|---|
| ForeignKey | 外键约束信息类型 描述表之间的外键关系 |
Variables
| Variable | Description |
|---|---|
| ADAPTER_NAME | PGlite 适配器名称常量 |
| DEFAULT_FTS_REGCONFIG | FTS 默认 PostgreSQL regconfig，决定 tokenizer / stopwords / stemmer。 |
| deserializeFromEnvelope | - |
| FTS_COLUMN | FTS 表的物理列名（tsvector 类型）。固定加在原表上，避免与业务列冲突。 |
| PG_MAX_PARAMS | PostgreSQL 协议单次查询最大参数数量（int16）。 按列数将大批量数据切片，避免 INSERT ... VALUES (...) 超限。 |
| pgDialect | 默认导出 PostgreSQL 方言实例 |
| serializeForEnvelope | - |
Functions
| Function | Description |
|---|---|
| buildCreateFtsTableSql | 生成 PostgreSQL FTS 物理结构 DDL：在原表追加 _fts tsvector 列 + GIN 索引。 |
| buildFtsTriggersSql | 生成 PostgreSQL FTS 同步 trigger（函数 + trigger）。 |
| chunkByPgParamLimit | 按参数数量上限把批量数据分片。 |
| create_tables_sql | 生成多张表的创建 SQL |
| generate_trigger_sql | 生成 PostgreSQL 触发器 SQL |
| generateNotifyFunctionSQL | 生成 NOTIFY 触发器函数 SQL |
| generateNotifyInfrastructureSQL | 生成完整的 NOTIFY 基础设施 SQL |
| generateNotifyTriggerSQL | 为指定表创建 NOTIFY 触发器 |
| getEntityObjectFromResult | 从 PGlite 结果行获取实体对象数据 PGlite 返回行作为对象，主要用于类型转换 |
| getMonotonicUpdatedAt | 保证 updatedAt 单调递增： 同一毫秒内多次 update 时递增 1ms，避免同步端按 updatedAt 比较失效。 |
| getSqlValue | - |
| getSqlWithParams | 将 PostgreSQL 参数占位符（$1、$2 等）替换为实际值 用于批量操作中无法使用参数化查询的情况 |
| getTableColumnIndexName | 获取表列索引名称 |
| getTableName | 拼出形如 "public"."users" 的完全限定表名（带双引号转义）。 |
| getTableNameByMetadata | 根据 EntityMetadata 得到完全限定表名，等价于 getTableName(metadata.tableName, metadata.namespace)。 |
| normalizeCreateEntity | 规范化创建实体的字段（过滤可写字段） |
| normalizeEntity | 规范化实体数据，过滤掉只读字段 |
| quoteIdentifier | - |
| quoteLiteral | - |
| remove_all_triggers_sql | 生成删除所有实体触发器的 SQL |
| remove_trigger_sql | 生成删除单个实体触发器的 SQL |
| removeNotifyTriggerSQL | 移除表的 NOTIFY 触发器 |
| resolvePGliteInitOptions | 把 PGliteClientOptions 规范化为 PGlite 构造函数能直接消费的形状。 |
| rxDBColumnTypeToPGliteType | 将 RxDB 属性类型转换为 PGlite 数据类型 |
| rxDBColumnTypeToPGliteTypeIndexName | 获取属性的索引操作符 http://www.postgres.cn/docs/current/indexes-opclass.html |
| shouldUsePGliteWorker | 判断是否需要为 PGlite 启用 Web Worker。 |
| transformEntityValuePGliteToJs | 将实体对象中的所有值从 PGlite 格式转换为 JS 类型 主要用于 RxDBChange 表的 patch/inversePatch 字段 |
| transformEntityValueToSql | 将实体值转换为 SQL 兼容格式 |
| transformValueJsToPGlite | 将 JavaScript 值转换为 PostgreSQL 兼容的值 |
| transformValuePGliteToJs | - |