PGlite 快速上手在浏览器与 Node/Bun/Deno 中运行嵌入式 Postgres【免费下载链接】pgliteEmbeddable Postgres with real-time, reactive bindings.项目地址: https://gitcode.com/GitHub_Trending/pg/pglitePGlite 是 PostgreSQL 的 WASM 构建版本被打包成一个 TypeScript 客户端库无需安装任何额外依赖即可在浏览器、Node.js、Bun 和 Deno 中运行真正的 Postgres。本篇指南以 docs/docs/index.md 为骨架带你完成安装、初始化、建表插入与参数化查询的完整流程并深入.query与.exec的底层差异最后梳理官方后续可深挖的进阶能力。PGlite 是什么PGlite 并不是模拟 Postgres 语法的玩具而是把 PostgreSQL 本体编译为 WebAssemblyWASM后在 JavaScript 环境中运行的嵌入式数据库项目位于本仓库 packages/pglite。与早期浏览器里的 Postgres方案不同PGlite 不依赖 Linux 虚拟机而是直接运行 Postgres 的 WASM 二进制并以单用户模式与 JavaScript 侧建立输入/输出通道来完成交互。由于其实现特性PGlite 默认只有一个独占连接因此非常适合用作浏览器中的本地优先local-first应用数据库Node/Bun/Deno 服务中的嵌入式单机数据库无需部署 PostgreSQL 服务的原型、测试与 CI 环境。它既可以作为纯内存的临时数据库使用也可以通过文件系统Node/Bun/Deno或 IndexedDB浏览器实现持久化。在 Node/Bun/Deno 中安装与启动安装PGlite 支持主流包管理器按你的环境选择其一npm install electric-sql/pglitepnpm install electric-sql/pgliteyarn add electric-sql/pglitebun install electric-sql/pglitedeno add npm:electric-sql/pgliteDeno 使用npm:前缀从 npm registry 拉取包与其它运行时保持同一份代码。内存模式不传任何参数即可得到一个完全在内存中运行的 Postgres 实例import { PGlite } from electric-sql/pglite const db new PGlite()这种模式下所有数据在进程结束或实例关闭后即消失适合临时计算、测试和演示。持久化到原生文件系统传入一个目录路径即可把数据库落盘到原生文件系统const db new PGlite(./path/to/pgdata)从源码看PGlite 会根据dataDir的前缀自动选择存储后端。在 packages/pglite/src/fs/index.ts 的parseDataDir中无前缀或以file://开头的路径走 Node 文件系统nodefsidb://走浏览器 IndexedDBmemory://或无参数走内存文件系统。因此./path/to/pgdata等价于file://./path/to/pgdata。在浏览器中安装与启动通过包管理器导入浏览器环境同样使用 npm 包配合 Vite、Webpack 等构建工具import { PGlite } from electric-sql/pglite通过 CDN 导入也可以直接使用 jsDelivr 这类 CDN无需任何构建步骤import { PGlite } from https://cdn.jsdelivr.net/npm/electric-sql/pglite/dist/index.js内存模式const db new PGlite()持久化到 IndexedDB浏览器端把数据库持久化到 IndexedDB只需使用idb://前缀const db new PGlite(idb://my-pgdata)my-pgdata是 IndexedDB 中用于存放该数据库的命名空间不同名称对应相互独立的数据库实例。执行第一条查询.exec与.queryPGlite 提供两种查询方法二者在协议层面对应不同的 Postgres wire protocol 消息.exec(sql)执行一条或多条 SQL 语句返回结果数组.query(sql, params?)执行单条语句并支持参数绑定返回单个结果对象。源码注释也印证了这一设计在 packages/pglite/src/base.ts 中query使用Extended Query协议消息需要 Parse/Bind/Execute 等步骤天然支持参数而exec使用Simple Query协议消息一次可携带多条语句。从返回类型看见 packages/pglite/src/interface.tsResults包含rows、fields等字段exec返回的则是Results[]。用.exec建表并批量插入await db.exec( CREATE TABLE IF NOT EXISTS todo ( id SERIAL PRIMARY KEY, task TEXT, done BOOLEAN DEFAULT false ); INSERT INTO todo (task, done) VALUES (Install PGlite from NPM, true); INSERT INTO todo (task, done) VALUES (Load PGlite, true); INSERT INTO todo (task, done) VALUES (Create a table, true); INSERT INTO todo (task, done) VALUES (Insert some data, true); INSERT INTO todo (task) VALUES (Update a task); )一次exec调用即可完成建表和批量插入.exec非常适合用于数据库迁移脚本和原始 SQL 批量写入。用.query查询单条记录const ret await db.query( SELECT * from todo WHERE id 1; ) console.log(ret.rows)输出;[ { id: 1, task: Install PGlite from NPM, done: false, }, ]注意done的默认值false会在 INSERT 时被应用但这里输出的done显示为false与建表时默认值一致。.exec与.query的选择建议方法支持多条语句支持参数典型场景.exec✅❌迁移、批量 DDL/DML.query❌✅单条查询、带参数的读写二者都在内部通过互斥锁mutex串行化执行保证同一时刻只有一个查询在运行这也与 PGlite 单连接的工作模型一致。使用参数化查询处理用户输入时务必使用参数化查询以避免 SQL 注入。.query的第二个参数是参数数组SQL 中用$1、$2……占位const ret await db.query( UPDATE todo SET task $2, done $3 WHERE id $1, [5, Update a task using parameterized queries, true], )这里$1对应5$2对应新的 task 文本$3对应done布尔值。从 packages/pglite/src/base.ts 的实现可以看到参数值会先通过类型 OID 匹配对应的 serializer默认param.toString()再经bind消息发送给 WASM 中的 Postgres因此参数不会以字符串拼接方式进入 SQL杜绝了注入风险。对于更便捷的模板写法PGlite 还提供sql模板标签db.sql\...它会把模板插值自动当作参数处理例如const results await db.sqlSELECT * FROM todo WHERE id ${id}构造函数的更多选项new PGlite()除了接受dataDir字符串外还可以直接传入一个选项对象两种签名见 packages/pglite/src/pglite.ts常用配置包括dataDir数据库存储目录也可作为第一个参数传入debugPostgres 调试级别 1–5日志输出到控制台relaxedDurability为 true 时不在每次查询后等待存储 flush 完成再返回对 IndexedDB 文件系统尤为有用fs自定义Filesystem实例替代通过 dataDir 前缀选择存储后端loadDataDir启动时加载由.dumpDataDir()导出的 datadir tarballextensions要加载的 Postgres 扩展或 PGlite 插件username/database连接用户与目标数据库initialMemory初始分配的 WASM 内存字节数可减少大库场景下内存增长造成的停顿parsers/serializers按 Postgres 类型 OID 自定义结果解析与参数序列化startParams/initDbStartParams透传给 postgres / initdb 进程的启动参数postgresqlconf以字符串或字符串数组形式提供postgresql.conf配置。例如自定义参数解析器import { PGlite, types } from electric-sql/pglite const pg await PGlite.create({ parsers: { [types.TEXT]: (value) value.toUpperCase(), }, })完整的参数说明见 docs/docs/api.md。下一步官方推荐的进阶方向入门之后官方文档建议继续探索以下能力查询与事务 API.query、.transaction及其余方法与选项详见 PGlite API 文档 中的查询与事务章节实时查询扩展通过 live-queries 让查询具备响应式能力底层数据库变化时自动更新 UI虚拟文件系统PGlite 内置多种 文件系统memory、nodefs、idbfs 等用于持久化本文的idb://与文件路径即为其入口框架 HooksReact 与 Vue 的官方 hooks 可显著减少集成样板代码打包器配置与 Vite、Webpack 等打包器配合时的注意事项见 bundler support多标签页共享由于 PGlite 只有单个独占连接官方提供 multi-tab worker 实现多个浏览器标签页共享一个 PGlite 实例REPL 组件REPL 可嵌入 Web 应用用于调试开发或作为数据库应用本身的一部分ORM 与查询构建器官方维护了支持 PGlite 的 ORM 列表扩展与插件通过 extensions API 加载 Postgres 扩展与 PGlite 插件完整清单见 支持的扩展列表在线示例可在浏览器中直接试玩的 示例页面。仓库内还提供了大量可直接运行的示例例如 packages/pglite/examples/basic.html 与 packages/pglite/examples/query-params.html以及覆盖安装、查询、参数化与各文件系统的测试用例如 packages/pglite/tests/basic.test.ts、packages/pglite/tests/describe-query.test.ts可作为进一步学习的参照。小结本文从零开始完成了 PGlite 在 Node/Bun/Deno 与浏览器双端的安装启动掌握了.exec批量建表插入与.query参数化查询两种核心用法并了解了构造函数选项与官方推荐的进阶路线。现在你就可以在自己的项目中创建一个真正的嵌入式 Postgres并在此基础上继续探索实时查询、持久化文件系统与框架 hooks 等高级特性。【免费下载链接】pgliteEmbeddable Postgres with real-time, reactive bindings.项目地址: https://gitcode.com/GitHub_Trending/pg/pglite创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考