---
title: PGlite
description: Embedded PostgreSQL using WebAssembly
---

## Installation

```bash
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

```typescript
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](#extensions)) |
| `postgis` | `boolean` | Assert that the database has PostGIS (see [Extensions](#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](/docs/extensions/permissions#providers) |

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

### In-Memory Database

```typescript
import { createClient } from "viborm/pglite";

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

### Persistent Database

```typescript
import { createClient } from "viborm/pglite";

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

### Using Existing Instance

```typescript
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`.

```typescript
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:

```typescript
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](/docs/drivers/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

```bash
pnpm add @electric-sql/pglite@0.5.8 @electric-sql/pglite-postgis@0.2.8
```

```typescript
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:

```typescript
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

```typescript
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](/docs/schema/scalars/point#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](/docs/schema/scalars/point#how-each-database-reads-a-polygon).

## Transactions

PGlite supports full transactions with savepoints for nested transactions — see [Transactions](/docs/client/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`:

```ts
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:

```ts
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.
