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:
- PGlite loads the extension’s code. It is PGlite’s own
extensionsoption — passed throughoptionswhen the driver makes the database, or given to thePGliteyou construct yourself. - You install it in the database, with
CREATE EXTENSION. VibORM never installs an extension. - The driver option tells VibORM it is there —
postgis: trueorpgvector: 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_seqscanisoffat startup on PGlite 0.3 — see the section above before reading anyEXPLAINtaken 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.