PGlite

Lightweight Postgres packaged as WASM into a TypeScript library for the bro...

DatabaseWeb AssemblySQL
electric-sql/pglite@electric-sql/pglite

README

ElectricSQL logo

PGlite - the WASM build of Postgres from ElectricSQL .Build reactive, realtime, local-first apps directly on Postgres.

PGlite - Postgres in WASM


PGlite

PGlite is a WASM Postgres build packaged into a TypeScript client library that enables you to run Postgres in the browser, Node.js and Bun, with no need to install any other dependencies. It is only 3.7mb gzipped.

  1. ``` js
  2. import { PGlite } from "@electric-sql/pglite";

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

It can be used as an ephemeral in-memory database, or with persistence either to the file system (Node/Bun) or indexedDB (Browser).

Unlike previous "Postgres in the browser" projects, PGlite does not use a Linux virtual machine - it is simply Postgres in WASM.

It is being developed at ElectricSQL in collaboration with Neon . We will continue to build on this experiment with the aim of creating a fully capable lightweight WASM Postgres with support for extensions such as pgvector.

Node/Bun


Install into your project:

  1. ``` shell
  2. npm install @electric-sql/pglite
  3. ```

To use the in-memory Postgres:

  1. ``` js
  2. import { PGlite } from "@electric-sql/pglite";

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

or to persist to the filesystem:

  1. ``` js
  2. const db = new PGlite("./path/to/pgdata");
  3. ```

Browser


It can be loaded via JSDeliver or your usual package manager, and for an in-memory Postgres:

  1. ``` xml
  2. <script type="module">
  3. import { PGlite } from "https://cdn.jsdelivr.net/npm/@electric-sql/pglite/dist/index.js";

  5. const db = new PGlite()
  6. await db.query("select 'Hello world' as message;")
  7. // -> [ { message: "Hello world" } ]
  8. </script>
  9. ```

or to persist the database to indexedDB:

  1. ``` js
  2. const db = new PGlite("idb://my-pgdata");
  3. ```

Deno


To use the in-memory Postgres, create a file server.ts:

  1. ``` ts
  2. import { PGlite } from "npm:@electric-sql/pglite";

  4. Deno.serve(async (_request: Request) => {
  5.   const db = new PGlite();
  6.   const query = await db.query("select 'Hello world' as message;");

  8.   return new Response(JSON.stringify(query));
  9. });
  10. ```

Then run the file with deno run --allow-net --allow-read server.ts.

How it works


PostgreSQL typically operates using a process forking model; whenever a client initiates a connection, a new process is forked to manage that connection. However, programs compiled with Emscripten - a C to WebAssembly (WASM) compiler - cannot fork new processes, and operates strictly in a single-process mode. As a result, PostgreSQL cannot be directly compiled to WASM for conventional operation.

Fortunately, PostgreSQL includes a "single user mode" primarily intended for command-line usage during bootstrapping and recovery procedures. Building upon this capability, PGlite introduces a input/output pathway that facilitates interaction with PostgreSQL when it is compiled to WASM within a JavaScript environment.

Limitations


PGlite is single user/connection.
Parameterized queries are not currently supported, but this will be added soon.

Roadmap


PGlite is Alphaand under active development, the current roadmap is:

Support parameterized queries #17
CI builds #19
Benchmarking #24
Support Postgres extensions, starting with:
pgvector #18
PostGIS #11

Use the Postgres wire protocol for input/output #31

Repository Structure


The PGlite project is split into two parts:

/packages/pgliteThe TypeScript package for PGlite
/postgres(git submodule)A fork of Postgres with changes to enable compiling to WASM:
/electric-sql/postgres-wasm

Please use the issues in this main repository for filing issues related to either part of PGlite. Changes that affect both the TypeScript package and the Postgres source should be filed as two pull requests - one for each repository, and they should reference each other.

Building


There are a couple of prerequisites:

the Postgres build toolchain - https://www.postgresql.org/download/
emscripten version 3.1.25 - https://emscripten.org/docs/getting_started/downloads.html

To build, checkout the repo, then:

  1. ``` null
  2. git submodule update --init
  3. cd ./pglite/packages/pglite
  4. emsdk install 3.1.25
  5. emsdk activate 3.1.25
  6. pnpm install
  7. pnpm build

  9. ```

Acknowledgments


PGlite builds on the work of Stas Kelvich of Neon in this Postgres fork .

License


PGlite is dual-licensed under the terms of the Apache License 2.0 and the PostgreSQL License , you can choose which you prefer.

Changes to the Postgres source are licensed under the PostgreSQL License.