pglite

PGlite

概述

PGlite 是轻量级的 PostgreSQL 17.4 WASM 构建版本，无需外部依赖即可直接在浏览器、Node.js 和 Bun 中运行。它提供完整的 Postgres 查询引擎，支持扩展、事务、COPY 和 listen/notify，压缩后不足 3MB。

适用场景： 需要真正 SQL 引擎的本地优先应用、基于浏览器的分析、支持离线的 PWA、用于测试的嵌入式 Postgres、无需服务端的原型开发。

不适用场景： 高并发服务端工作负载（请使用原生 Postgres）、需要完整 Postgres 复制的应用、Safari OPFS 存储（不支持）、未采用主节点选举的多标签页写入密集型场景。

快速参考

模式	API	要点
创建实例	PGlite.create(dataDir?, options?)	内部会等待就绪
内存数据库	PGlite.create()	默认，临时存储
IndexedDB 存储	PGlite.create('idb://dbname')	在浏览器中持久化
OPFS 存储	PGlite.create('opfs-ahp://dbname')	仅限 Worker，不支持 Safari
参数化查询	db.query<T>(sql, params)	返回 QueryResult<T>
标签模板	db.sql\SELECT ...``	自动参数化
多语句执行	db.exec(sqlString)	不接受参数，返回 void
事务	db.transaction(async (tx) => {})	完整 ACID，使用 tx.query
加载扩展	在 create 中设置 extensions: { vector }	在构造时加载
实时查询	db.live.query(sql, params, cb)	数据变更时重新运行
增量查询	db.live.incrementalQuery(sql, params, key, cb)	对大型结果集执行差异计算
实时变更	db.live.changes(sql, params, key, cb)	原始插入/更新/删除操作
React hook	useLiveQuery(sql, params)	响应式返回 { rows }
多标签页 Worker	PGliteWorker + 主节点选举	单写入者，多读取者
Electric 同步	syncShapeToTable(db, shape, table)	单向只读同步
转储数据	db.dumpDataDir('gzip')	返回 File blob
加载数据	PGlite.create({ loadDataDir: blob })	从转储恢复
Listen/notify	db.listen(channel, cb)	Postgres LISTEN/NOTIFY
放宽持久性	relaxedDurability: true	提升浏览器写入性能

常见错误

错误	正确做法
使用 new PGlite()，却没有等待其就绪	使用 PGlite.create()，它会在内部等待
在主线程中使用 OPFS	OPFS-AHP 需要 Web Worker 上下文
在 Safari 上使用 OPFS	Safari 缺少所需的 OPFS API；请使用 idb://
在事务回调之外执行查询	从事务回调传入 tx，并使用 tx.query()
忘记在创建选项中指定扩展	必须在 PGlite.create({ extensions }) 中声明扩展
多个标签页写入时未进行主节点选举	多标签页场景下使用带主节点选举的 PGliteWorker
认为 Electric 同步是双向的	Electric 同步是只读的，只能从服务端单向同步
对大型数据集使用 live.query()	对大型结果集使用 live.incrementalQuery()
未向增量查询提供 key	增量查询和变更查询需要唯一键列
导入扩展时未配置打包器支持	扩展是 WASM；请确保打包器能处理 .wasm 资源

委派

如果有 electricsql 技能，请将 Electric 同步模式、Shape 配置和实时复制委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s electricsql -a claude-code -y

如果有 drizzle-orm 技能，请将 Drizzle + PGlite 驱动设置和架构管理委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s drizzle-orm -a claude-code -y

如果有 local-first 技能，请将本地优先架构决策和同步引擎选择委派给它。 否则，建议使用：pnpm dlx skills add oakoss/agent-skills -s local-first -a claude-code -y

参考资料

• 安装、存储后端和配置
• 查询、事务、COPY、监听/通知和数据导入/导出
• 扩展：pgvector、pg_trgm、pgcrypto、全文搜索等
• 实时查询：响应式、增量式和变更跟踪
• React 集成：提供器、钩子和类型化模式
• 多标签页 Worker 架构和主节点选举
• Electric 同步：形状、事务同步和持久化