PGlite

PGlite is a WebAssembly build of PostgreSQL packaged as a lightweight TypeScript client library, letting you run a real, single-connection Postgres instance directly inside the browser, Node.js, Bun, or Deno — with no server process, network socket, or native binary to install. At roughly 3MB gzipped, it ships as an npm package that persists to IndexedDB in the browser or the filesystem in server runtimes, and supports many of Postgres’ native extensions, including pgvector and PostGIS, making it well suited for local-first apps, embedded analytics, and fast test/CI databases.

Built by ElectricSQL, PGlite works by running Postgres’ built-in single-user mode — normally reserved for bootstrapping and recovery — inside an Emscripten-compiled WASM module, since regular multi-process Postgres can’t be compiled to WASM directly. The result is a genuine Postgres engine, not an emulation or subset, exposed through a small async query API, with companion packages for React/Vue bindings, live reactive queries, a Postgres wire-protocol socket server, and sync with ElectricSQL’s replication.

What You Get

• A ~3MB gzipped WASM build of real PostgreSQL runnable via new PGlite() with zero native dependencies
• Persistence adapters for IndexedDB (browser), the filesystem (Node/Bun/Deno), or in-memory ephemeral storage
• A TypeScript client with query, exec, transaction, listen/unlisten, and tagged-template sql helpers
• A live extension for reactive, auto-updating query subscriptions, plus a Worker adapter for running PGlite off the main thread
• Optional Postgres extensions (pgvector, PostGIS, pg_trgm, hstore, ltree, and dozens more) loadable as separate packages
• React and Vue binding packages, a browser REPL component, and a wire-protocol socket server for connecting regular Postgres clients like psql

Common Use Cases

• Local-first web apps - Ship a real Postgres database inside the browser so apps keep working offline and sync changes later via ElectricSQL.
• Fast, disposable test databases - Spin up an in-memory or file-backed Postgres instance per test run in CI without provisioning a database server.
• Embedded analytics and reporting - Run SQL queries, aggregations, and pgvector similarity search directly inside a Node.js service or edge function.
• Prototyping and demos - Give a browser-based playground or documentation site a fully queryable Postgres backend with no backend infrastructure.

Under The Hood

Architecture: PGlite centers on the PGlite class in src/pglite.ts (1,361 lines), which extends BasePGlite (src/base.ts) and drives an Emscripten-compiled Postgres binary through a manually-intercepted longjmp on Postgres’ main loop, letting a single WASM instance service one query at a time in Postgres’ “single user mode” (normally used only for bootstrap/recovery). Wire-protocol messages are built and parsed via the sibling @electric-sql/pg-protocol package rather than a socket, with #queryMutex/#transactionMutex/#listenMutex (from async-mutex) serializing access. A pluggable Filesystem abstraction (src/fs/) backs the data directory with IndexedDB (idbfs.ts), Node’s fs (nodefs.ts), OPFS (opfs-ahp.ts), or pure in-memory storage (memoryfs.ts), and src/extensionUtils.ts loads optional Postgres extensions (pgvector, PostGIS, etc.) as separate WASM/tarball bundles at init time. Companion packages in the same monorepo — pglite-sync, pglite-react, pglite-vue, pglite-repl, pglite-socket, and a live query layer (src/live/index.ts, 850 lines) — build on the core client via its public PGliteInterface.

Tech Stack: The core package is pure TypeScript compiled with tsup, published as dual ESM/CJS with per-entrypoint exports (., ./live, ./worker, ./nodefs, ./opfs-ahp, ./contrib/*). Runtime dependencies are minimal — the WASM Postgres binary itself, @electric-sql/pg-protocol and @electric-sql/pglite-utils (both workspace-internal), and async-mutex for concurrency control — keeping the client itself dependency-light while the WASM payload does the heavy lifting. The workspace uses pnpm workspaces, Changesets for versioned multi-package releases, and Docker to build the underlying Postgres WASM binary from a forked postgres-pglite submodule.

Code Quality: The packages/pglite test suite spans 30+ files under tests/ (basic, transactions via triggers/plpgsql, live, dump, array-types, exec-protocol, notify, templating, plus a tests/contrib/ subtree exercising individual Postgres extensions) run through Vitest across Node, Bun, Deno, and browser targets (test:runtimes, test:web). Error paths are explicit: src/errors.ts wraps raw Postgres DatabaseErrors with the originating query/params via makePGliteError, and throw new Error(...) appears deliberately across base.ts, pglite.ts, initdb.ts, and argsParser.ts rather than being swallowed. ESLint + Prettier are enforced via a stylecheck script, and @arethetypeswrong/cli checks published type exports don’t drift from runtime exports before publish.

API Design: The public surface centers on a handful of familiar, promise-based methods — query, exec, sql tagged templates, transaction, listen/unlisten — mirroring node-postgres idioms closely enough that existing Postgres-client mental models transfer directly. Getting started is a single line (const db = new PGlite()), with optional extensions, filesystem backend, and startup params all passed through one PGliteOptions object rather than scattered configuration calls. The README leads with runnable browser and Node/Bun/Deno snippets, and pglite.dev hosts a fuller docs site plus an in-browser REPL example, giving the library strong out-of-the-box discoverability for a fairly novel embedding model.