PGlite - 来自 Electric 的 Postgres WASM 构建版本。
直接基于 Postgres 构建响应式、实时、本地优先的应用。

PGlite - Postgres in WASM

PGlite 是一个打包为 TypeScript 客户端库的 WASM Postgres 构建版本，让你能够在浏览器、Node.js、Bun 和 Deno 中运行 Postgres，无需安装任何其他依赖。它的 gzip 压缩后大小仅为 3mb，并支持众多 Postgres 扩展，包括 pgvector 和 PostGIS。

import { PGlite } from "@electric-sql/pglite";

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

它可用作临时内存数据库，也可通过文件系统（Node/Bun/Deno）或indexedDB（浏览器）实现持久化存储。

与以往的“浏览器中的Postgres”项目不同，PGlite不使用Linux虚拟机——它就是WebAssembly格式的Postgres。

完整文档和用户指南请参见pglite.dev。

浏览器

可使用常用的包管理器安装并导入：

import { PGlite } from "@electric-sql/pglite";

或使用 CDN（如 JSDeliver）：

import { PGlite } from "https://cdn.jsdelivr.net/npm/@electric-sql/pglite/dist/index.js";

然后对于内存中的 Postgres：

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

或用于将数据库持久化到 indexedDB：

const db = new PGlite("idb://my-pgdata");

Node/Bun/Deno

安装到你的项目中：

NodeJS

npm install @electric-sql/pglite

Bun

bun install @electric-sql/pglite

Deno

deno add npm:@electric-sql/pglite

要使用内存中的 Postgres：

import { PGlite } from "@electric-sql/pglite";

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

或持久化到文件系统：

const db = new PGlite("./path/to/pgdata");

工作原理

PostgreSQL 通常采用进程分叉模型运行；每当客户端发起连接时，就会分叉一个新进程来管理该连接。然而，使用 Emscripten（一款 C 到 WebAssembly [WASM] 的编译器）编译的程序无法分叉新进程，只能严格在单进程模式下运行。因此，PostgreSQL 无法直接编译为 WASM 以进行常规操作。

幸运的是，PostgreSQL 包含一种“单用户模式”，主要用于引导和恢复过程中的命令行操作。基于此功能，PGlite 引入了一条输入/输出路径，以便在 JavaScript 环境中将 PostgreSQL 编译为 WASM 后与之进行交互。

局限性

• PGlite 仅支持单用户/单连接。

如何构建 PGlite 并参与贡献

PGlite 的构建过程分为两部分：

1. 构建 Postgres WASM 模块。
2. 构建 PGlite 客户端库及其他 TypeScript 包。

构建 WASM 模块需要 Docker，同时还需要 Node（v20 或更高版本）和 pnpm 来进行包管理和 TypeScript 包的构建。

首先，请检出代码仓库并安装依赖：

git clone --recurse-submodules https://github.com/electric-sql/pglite
cd pglite
pnpm install

要构建所有内容，我们在仓库根目录提供了便捷的 pnpm build:all 命令。该命令将：

1. 使用 Docker 构建 Postgres WASM 模块。此步骤生成的产物随后会复制到 /packages/pglite/release。
2. 构建 PGlite 客户端库及其他 TypeScript 包。

若要仅构建 Postgres WASM 模块（即上述第 1 点），请运行

pnpm wasm:build

如果您不想从头构建 WASM 模块及各种配套的 WASM 二进制文件，它们会在每次 PR 成功合并后在 Github 上自动生成。您可以通过以下方式下载最新的二进制文件：找到最后一个成功合并的 PR，然后点击评论“Interim build files:”下方的链接。解压文件并将其放置在本地仓库副本的 packages/pglite/release 目录下。

要构建所有 TypeScript 包（即上述第 2 点），请运行：

pnpm ts:build

这将根据依赖关系按正确顺序构建所有包。现在，你可以使用 build 和 test 脚本，以及 stylecheck 和 typecheck 脚本来开发任何单个包，以确保代码风格和类型的有效性。

或者，要构建单个包，可以进入该包的目录并运行：

cd packages/pglite
pnpm build

准备提交 PR 时，请在仓库根目录运行以下命令：

pnpm changeset

并按照说明创建适当的变更集。请确保任何涉及代码的贡献都附有变更集。

致谢

PGlite 基于 Neon 的 Stas Kelvich 在这个 Postgres 分支 中的工作构建而成。

赞助商

特别感谢所有支持我们的人！

Blacksmith

许可协议

PGlite 采用双重许可协议，您可以选择 Apache License 2.0 或 PostgreSQL License。

对 Postgres 源代码 的修改采用 PostgreSQL 许可协议。