Skip to content
VibORM
Esc
↑↓navigate↵open⌘Jpreview
On this page

PGlite

Embedded PostgreSQL using WebAssembly

Installation

pnpm add @electric-sql/pglite

VibORM accepts @electric-sql/pglite 0.3, 0.4 and 0.5, and its test estate runs 0.5.8 (PostgreSQL 18.3). A persistent dataDir written by one PostgreSQL major does not open under another, so moving an existing database from 0.3 (PostgreSQL 17) to 0.5 is a dump and restore, not a package bump. The PostGIS and pgvector extension packages below pin their exact PGlite version.

Configuration

import { createClient } from "viborm/pglite";

const client = createClient({
  schema,
});

Options

Option Type Description
client PGlite Existing PGlite instance
dataDir string Data directory for persistence
options PGliteOptions PGlite configuration
namespace string PostgreSQL schema for VibORM-owned objects (default public)
pgvector boolean Assert that the database has pgvector (see Extensions)
postgis boolean Assert that the database has PostGIS (see Extensions)
sharedRelationBodies boolean State each relation-filter body a statement repeats once, in a WITH (default true; false keeps the bodies inline)
relationsPerStatement number The most relations (FROM items) one statement may reference (PlanetScale Neki: 256); a statement over it is rewritten to fit. See Neki

createClient refuses any other key with a ClientInitializationError that names it.

In-Memory Database

import { createClient } from "viborm/pglite";

// Default is in-memory
const client = createClient({
  schema,
});

Persistent Database

import { createClient } from "viborm/pglite";

const client = createClient({
  dataDir: "./pglite-data",
  schema,
});

Using Existing Instance

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

const pg = new PGlite();

const client = createClient({
  client: pg,
  schema,
});

The instance may come from another copy of @electric-sql/pglite than the one VibORM imports, such as its CommonJS build beside the ESM one, or a second installed version: VibORM recognizes a database by its transaction method, not by its class.

Namespace

namespace selects the PostgreSQL schema holding this driver’s tables, junctions, indexes, ORM-managed enums, and migration tracking table. Omitted, it is public.

import { createClient } from "viborm/pglite";

const db = createClient({
  namespace: "billing",
  schema,
});

PGlite is a real PostgreSQL server, so the schema must already exist. VibORM never creates or drops one:

await db.$executeRawUnsafe('CREATE SCHEMA IF NOT EXISTS "billing"');

That makes PGlite a convenient place to exercise multi-schema behavior locally: two clients over two namespaces in one in-memory database stay isolated in SQL names, migration estate, and official cache scope. PGlite pins a session, so it supports the full migration verb set.

Raw SQL is never rewritten and keeps ordinary search_path semantics — see Namespaces.

Use Cases

  • Local development: Full PostgreSQL without Docker
  • Testing: Fast, isolated database per test
  • Browser: PostgreSQL in the browser via WASM
  • Edge: Serverless functions with embedded database

Extensions

An extension takes three steps, and each has one owner:

  1. PGlite loads the extension’s code. It is PGlite’s own extensions option — passed through options when the driver makes the database, or given to the PGlite you construct yourself.
  2. You install it in the database, with CREATE EXTENSION. VibORM never installs an extension.
  3. The driver option tells VibORM it is there — postgis: true or pgvector: true. The option is an assertion, not an installer. For PostGIS, live migrations prove the extension’s types and functions before their first effect, and refuse when they are missing.

PostGIS

pnpm add @electric-sql/pglite@0.5.8 @electric-sql/pglite-postgis@0.2.8
import { postgis } from "@electric-sql/pglite-postgis";
import { createClient } from "viborm/pglite";

const client = createClient({
  schema,
  options: { extensions: { postgis } },
  postgis: true,
});
await client.$executeRawUnsafe("CREATE EXTENSION IF NOT EXISTS postgis");

Or over a database you construct:

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

const pg = new PGlite({ extensions: { postgis } });
await pg.exec("CREATE EXTENSION IF NOT EXISTS postgis");

const client = createClient({ client: pg, postgis: true, schema });

@electric-sql/pglite-postgis 0.2.8 is PostGIS 3.6 and requires @electric-sql/pglite 0.5.8 exactly. The PostGIS build is a large Wasm bundle (about 20 MB unpacked): a database with it loaded takes a few seconds to open.

pgvector

import { vector } from "@electric-sql/pglite-pgvector";
import { createClient } from "viborm/pglite";

const client = createClient({
  schema,
  options: { extensions: { vector } },
  pgvector: true,
});
await client.$executeRawUnsafe("CREATE EXTENSION IF NOT EXISTS vector");

From PGlite 0.5 pgvector is its own package, @electric-sql/pglite-pgvector; PGlite 0.3 and 0.4 ship it as @electric-sql/pglite/vector.

GeoPoint

With PostGIS loaded as above and postgis: true, PGlite is in the full GeoPoint tier: bounds, polygons, meter distance filtering, _distance selection and ordering, and GiST spatial indexes, on the same geography(Point,4326) column the server PostgreSQL drivers use. The same behavior contracts that qualify pg and postgres.js run on PGlite 0.5.8 with @electric-sql/pglite-postgis 0.2.8 in VibORM’s credential-free test estate. Without postgis: true a schema with s.point() is refused at client construction, as on any PostgreSQL driver; with the option but without CREATE EXTENSION, live migrations refuse before their first effect. See GeoPoint provider tiers.

PGlite runs the same PostGIS, so it answers polygons as PostGIS does, including where PostGIS departs from VibORM’s reading: a ring reaching across the equator, the 0/180 meridian and the 90/-90 meridian at once (every ring of half the globe or more) can be misread, in some cases inside out. PostGIS misread 23 of 372 random such rings; the band from -170 to 170 at latitude ±30 answered 38 of 394 sample points wrongly, and a band with two 175-degree edges on each side all 398 (inside out). VibORM admits such a polygon; see How each database reads a polygon.

Transactions

PGlite supports full transactions with savepoints for nested transactions — see Transactions.

Check enable_seqscan before benchmarking query plans

PGlite 0.3 starts with enable_seqscan = off. It is set on the server’s command line, not by viborm, and it is not the default a real PostgreSQL server runs with. PGlite 0.5.8 starts with the ordinary default, on:

await client.$queryRawUnsafe(
  "SELECT setting, source FROM pg_settings WHERE name = 'enable_seqscan'"
);
// [{ setting: "off", source: "command line" }]   ← PGlite 0.3 (PostgreSQL 17.4)
// [{ setting: "on", source: "default" }]         ← PGlite 0.5.8 (PostgreSQL 18.3)

With it off the planner charges a sequential scan an enormous cost, so it takes an index whenever one can answer the query — whether or not the index is the cheaper plan. That makes PGlite the wrong place to ask “does my index get used”, because the answer is almost always yes.

If you are measuring a plan rather than a result, either turn it back on for the session and check that the setting took:

await client.$executeRawUnsafe("SET enable_seqscan = on");
const [{ enable_seqscan }] = await client.$queryRawUnsafe("SHOW enable_seqscan");
// assert it is "on" before trusting the EXPLAIN below

or run the measurement against a real PostgreSQL server. Correctness results are unaffected — a plan choice changes the cost, never the rows.

Limitations

  • WASM-based: may have performance overhead for heavy workloads
  • Some PostgreSQL extensions not available
  • enable_seqscan is off at startup on PGlite 0.3 — see the section above before reading any EXPLAIN taken there as a statement about production

Interactive transactions serialize work on their connection. In Node and Bun, originating-client reentry is detected immediately; use the callback transaction client. In a browser without async-context support, unrelated work still queues, while originating-client reentry reaches a 5-second queue timeout. An explicit transaction maxWait overrides that wait. Timeout cleanup closes nested scopes and drains in-flight provider statements before releasing the connection.

Was this page helpful?