PGlite v0.4 发布详解：PostGIS 地理空间支持、连接多路复用与新架构重构

PGlite v0.4 发布详解：PostGIS 地理空间支持、连接多路复用与新架构重构

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric

PGlite v0.4 是嵌入式 Postgres 的一个重要里程碑版本，带来了 PostGIS 地理空间扩展、连接多路复用（connection multiplexing）以及将initdb从主 WASM 二进制中解耦的重大架构重构。本文基于 官方网站发布公告 的原始内容，结合本仓库中的源码与示例，为你完整解读 v0.4 的技术细节、升级要点与使用方式，读完后你将掌握 PGlite 的架构演进逻辑、PostGIS 与多连接能力的实际用法，以及 PGlite 在 CI 测试、浏览器沙箱、AI 应用等场景下的落地路径。

什么是 PGlite

PGlite 是 Postgres 的 WASM 构建版本，运行在你的 JavaScript 环境中——浏览器、Node.js、Bun 和 Deno 都支持。与以往"浏览器里的 Postgres"项目不同，PGlite 不依赖 Linux 虚拟机，而是将 Postgres 直接编译为 WASM，以单用户模式运行。打包体积小于 3MB（gzipped），无需安装任何额外依赖即可在 JavaScript 中运行 Postgres。

在 PGlite 产品页 中可以确认它的定位：一个轻量级 WASM Postgres 构建，打包成 TypeScript 库，可用于：

• 临时性的内存数据库（in-memory）
• 持久化到文件系统（Node/Bun 的 node fs）
• 浏览器端持久化到IndexedDB
• 支持动态扩展加载，包括 pgvector
• 内置响应式查询（live query）与同步（sync）原语

import { PGlite } from '@electric-sql/pglite' const db = new PGlite() await db.query("select 'Hello world' as message;") // -> { rows: [ { message: "Hello world" } ] }

v0.4 更新概览

v0.4 的三大核心变化：

1. 更干净的架构：将initdb从主 WASM 可执行文件中解耦为独立进程
2. PostGIS 支持：地理空间数据存储、索引与查询能力进入嵌入式 Postgres
3. 连接多路复用：在单连接约束下兼容期待多连接的客户端工具

此外还有一批社区贡献的扩展正式可用，包括pg_uuidv7、pgTAP、pg_hashids和 Apache AGE 等。

更干净的架构：initdb 独立成进程

PGlite 的一个指导原则是让 Postgres fork 尽可能贴近上游。改动越少，升级、维护和接受社区贡献就越容易。PGlite 依赖原生的 Emscripten 进行构建，外部构建依赖放在一个 Docker builder 镜像中，从而在任何主机上都能可复现构建环境。

v0.4 最大的架构成果是重构了initdb的工作方式。此前，initdb被嵌入最终的 WASM 可执行文件内部，这要求维护一些需要跨 fork 更新才能保持工作的 hack。现在：

• initdb以独立的 WASM 进程运行
• PGlite 拦截其系统调用，提供必要的管道（plumbing）：stdin/stdout 重定向，以及通过 Emscripten 的 PROXYFS 进行文件系统共享
• 完全不修改initdb的任何代码

这镜像了原生 PostgreSQL 部署的工作方式，让新贡献者更容易理解代码库。同样的模式可以扩展到其他 Postgres 客户端工具，无需改动它们自身的代码。

图中清晰地展示了这个新架构：左侧的initdb进程通过PGlite "libc"层发出popen()、pclose()、system()等系统调用，PGlite 拦截这些调用并通过callmain()协调右侧的 Postgres 主进程；同时，initdb通过 PROXYFS、Postgres 通过 MEMFS 与底部的文件系统交互，实现数据在两者之间的共享。

PostGIS：地理空间能力进入嵌入式 Postgres

PostGIS 为 Postgres 增加了地理空间数据的存储、索引和查询能力。对很多开发者来说，这正是他们选择 Postgres 的原因。现在它在 PGlite 中也能运行了。

实现这一点的难度不小：PostGIS 有大量依赖，所有这些依赖都需要 WASM 构建。Chrome 对同步加载动态库的 8MB 限制又增加了一道约束。社区成员 @StachowiakDawid 和 @larsmennen 为这项工作做出了贡献。

在 10M 下载里程碑文章 中，展示了 PostGIS 的安装与使用方式：

npm install @electric-sql/pglite-postgis

import { PGlite } from '@electric-sql/pglite' import { postgis } from '@electric-sql/pglite-postgis' const pg = new PGlite({ extensions: { postgis, }, }) await pg.exec('CREATE EXTENSION IF NOT EXISTS postgis;')

连接多路复用：突破单连接限制

PGlite 运行在 Postgres 的单用户模式下，这意味着只有一个连接。许多客户端工具期望能打开多个连接，这曾是 PGlite 的一个痛点。

社区成员 @nickfujita 提交了一个 PR，在 PGlite 的单连接之上多路复用并发连接。这解除了此前无法与 PGlite 单连接约束兼容的工具的限制。

社区扩展

社区基于 PGlite 的扩展构建文档，贡献了更多生产级扩展：

• pg_uuidv7：UUIDv7 生成
• pgTAP：Postgres 单元测试框架
• pg_hashids：hashids 编解码
• Apache AGE：图数据库扩展
• pgcrypto（由 @loredanacirstea 协助引入）：加密函数

这些扩展叠加在 PGlite 默认捆绑的 contrib 扩展之上。完整清单可查看扩展目录（pglite.dev/extensions/）。

增长态势

过去一年，PGlite 的全包周下载量从约 50 万增长到超过 1300 万。Prisma 现在将 PGlite 捆绑进他们的 CLI 用于本地开发，可用npx prisma dev体验。社区在 Hacker News 上的讨论更活跃，GitHub 上的外部 PR 更多，CI/CD 管道、浏览器 IDE 和开发者工具中的采用率也在上升。

在本仓库的 linearlite 示例 中，可以看到 PGlite 生态的真实落地——该项目使用@electric-sql/pglite、@electric-sql/pglite-react、@electric-sql/pglite-repl和@electric-sql/pglite-sync构建了一个本地优先的 Linear 克隆。其 worker 初始化代码 展示了 PGlite 在 Web Worker 中的典型用法：

import { worker } from '@electric-sql/pglite/worker' import { PGlite } from '@electric-sql/pglite' import { migrate } from './migrations' worker({ async init() { const pg = await PGlite.create({ dataDir: `idb://linearlite2`, relaxedDurability: true, }) // Migrate the database to the latest schema await migrate(pg) return pg }, })

快速上手

安装 PGlite：

npm install @electric-sql/pglite

基本用法：

import { PGlite } from '@electric-sql/pglite' const db = new PGlite() await db.exec('CREATE TABLE test (id serial PRIMARY KEY, name text)') await db.exec("INSERT INTO test (name) VALUES ('hello')") const result = await db.query('SELECT * FROM test')

在 Electric 生态中同步数据到 PGlite

PGlite 不只是独立的嵌入式数据库——在 Postgres 同步文档 和 PGlite 产品页 中，展示了如何将云端 Postgres 的 Shape 同步进本地的 PGlite 实例。参考 sync-into-pglite.tsx 片段：

import { PGlite } from '@electric-sql/pglite' import { live } from '@electric-sql/pglite/live' import { electricSync } from '@electric-sql/pglite-sync' import { useLiveQuery } from '@electric-sql/pglite-react' // 创建一个持久的本地 PGlite 数据库 const pg = await PGlite.create({ dataDir: `idb://my-database`, extensions: { electric: electricSync(), live, }, }) // 设置本地数据库 schema await pg.exec(` CREATE TABLE IF NOT EXISTS items ( id SERIAL PRIMARY KEY, ); `) // 建立一个持久的 shape 订阅 await pg.electric.syncShapeToTable({ shape: { url: `${BASE_URL}/v1/shape` }, table: `items`, primaryKey: [`id`], }) // 使用针对本地嵌入式数据库的 live query 将数据绑定到组件 const Component = () => { const items = useLiveQuery(`SELECT * FROM items;`) return <pre>{JSON.stringify(items)}</pre> }

通过 Postgres socket 暴露给传统工具

对于那些期望标准数据库连接的工具，PGlite 也可以跑在 Postgres socket 后面：

npm install @electric-sql/pglite @electric-sql/pglite-socket

import { PGlite } from '@electric-sql/pglite' import { PGLiteSocketServer } from '@electric-sql/pglite-socket' const db = await PGlite.create() const server = new PGLiteSocketServer({ db, host: '127.0.0.1', port: 5432, }) await server.start()

pglite-socket包还附带一个pglite-serverCLI，可以用DATABASE_URL直接指向 PGlite 的方式启动你的应用。

接下来

PGlite 团队公布了三个后续方向：

• libpglite—— 直接从 Postgres 源码构建的原生库，提供多种语言的绑定。这将解锁移动端和桌面端用例，从 React Native 开始。
• 多实例（Multi-instance）—— 真正的多连接支持，同时探索协作式和多线程（WebWorker）两种方案。团队也在关注 Postgres 社区的多线程工作作为长期路径。
• 复制（Replication）—— 启用 Postgres 逻辑复制，扩展 PGlite 可以参与的场景。

值得注意的是，本仓库 10M 下载里程碑文章 中进一步说明了这些方向的最新进展：多线程 Postgres 分支正在探索在不牺牲进程级隔离语义的前提下支持更多并发客户端会话；逻辑复制可以让 PGlite 进入 Postgres 拓扑内部；长期愿景则是让 Postgres 像 SQLite 一样可被广泛嵌入。

结语

PGlite v0.4 通过解耦initdb、引入 PostGIS 和支持连接多路复用，让嵌入式 Postgres 更接近"第一公民"的地位。它从一个小巧的 Postgres-in-WASM 实验，成长为被 Prisma、Drizzle、Supabase 等生态广泛采用的嵌入式数据库。无论你是想在 CI 中跑真实 Postgres 测试、在浏览器沙箱中构建 AI 应用，还是让 ORM 无缝指向本地数据库，PGlite 都值得一试。

【免费下载链接】electricThe agent platform built on sync.项目地址: https://gitcode.com/GitHub_Trending/el/electric