PGlite

PGlite is an embeddable Postgres database that runs locally in WASM. It is designed to be lightweight, extendable, and reactive, making it suitable for running full Postgres instances directly in the browser or in environments like Node, Bun, and Deno.

Key features include:

• Lightweight: A complete WASM build of Postgres under 3MB Gzipped.
• Extendable: Supports a dynamic extension loading mechanism, including popular extensions like pgvector and PostGIS.
• Reactive: Built-in support for data loading, synchronization, and live query primitives.

PGlite is a Postgres build compiled to WebAssembly (WASM) and packaged as a TypeScript/JavaScript client library. It allows running Postgres directly in the browser, Node.js, Bun, or Deno without external dependencies.

Key characteristics:

• Lightweight: Under 3MB Gzipped.
• No VM required: Unlike other browser-based Postgres projects, it runs Postgres directly in WASM rather than inside a Linux virtual machine.
• Extensible: Supports various Postgres extensions, including pgvector for vector similarity search.
• Flexible Storage: Supports ephemeral in-memory mode, IndexedDB persistence (browser), or file system persistence (Node/Bun).

The @electric-sql/pglite-react package provides several hooks and components to integrate PGlite with React, leveraging the live query plugin.

Core features include:

• Context Management: Use PGliteProvider to make a PGlite instance available to your component tree, and usePGlite to access that instance.
• Reactive Queries: Use useLiveQuery to trigger component re-renders when query results change, or useLiveIncrementalQuery to offload diffing to PGlite for optimized reactive updates.
• Type Safety: Use makePGliteProvider to generate typed versions of the provider and hook.

The PGlite React integration provides several hooks and components to manage database state and reactivity:

• PGliteProvider: A provider component used to wrap your application and make the PGlite instance available to the component tree.
• usePGlite: A hook to access the PGlite instance within a component.
• useLiveQuery: A hook that watches for changes in the database. It automatically re-renders components when the results of a specific query change, making it ideal for real-time UI updates.

In a typical workflow, you create a database on page load, use usePGlite to interact with it (e.g., inserting rows), and use useLiveQuery to display the data reactively.

Because PGlite is single-connection only, running it in multiple browser tabs can cause conflicts. PGliteWorker solves this by using a Web Worker to run PGlite off the main thread and implementing a leader election mechanism to proxy multiple tabs to a single PGlite instance.

How it works:

1. Each tab starts its own worker process.
2. The workers run an election to nominate one as the leader.
3. Only the leader calls the init function to start the actual PGlite instance and handles all queries.
4. If the leader tab is closed, a new election is triggered, and a new leader starts a new PGlite instance.

PGlite is fundamentally a single-connection database. To support multiple simultaneous connections, pglite-server uses a multiplexer that routes multiple client connections over the single underlying PGlite connection.

Key implications:

• Use the -m, --max-connections=N flag to allow up to N concurrent connections.
• Because of the multiplexing, not all complex PostgreSQL use cases are guaranteed to work as they would on a full Postgres installation.
• By default, concurrency is set to 1 (no concurrent connections).

PGlite provides extensions for reactive data handling. You can use the following methods to observe changes in real-time:

• .live.query(): For reactive queries.
• .live.changes(): To listen for changes.
• .live.incrementalQuery(): For incremental updates to queries.

PGlite provides three distinct ways to handle live data updates via the live namespace, depending on your performance and complexity needs:

1. live.query(): Best for small result sets and narrow rows. It re-runs the query and sends the full result set to a callback whenever dependencies change.
2. live.incrementalQuery(): Best for large result sets and wide rows (e.g., feeding React state). It maintains a temporary table in Postgres to diff the new state against the previous state, sending only the changes from WASM to JS.
3. live.changes(): A low-level API that emits raw INSERT, UPDATE, or DELETE operations. This is ideal for implementing highly efficient in-place UI updates (like DOM mutations) by mapping changes directly to the view.