@vibeorm/adapter-pglite
v5.2.2
Published
PGlite (in-process Postgres) adapter for VibeORM v2
Maintainers
Readme
@vibeorm/adapter-pglite
Part of VibeORM — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
This adapter runs VibeORM on PGlite, real PostgreSQL compiled to WASM and running in-process. There is no server and no Docker, which makes it the zero-setup default for tests and demos; @electric-sql/pglite is a regular dependency, so nothing extra to install.
bun add @vibeorm/adapter-pgliteStable.
2.0.0, published under thelatestdist-tag. The v1 line stays installable asvibeorm@1.
Usage
import { VibeClient } from "./generated/vibeorm/index.js";
import { pgliteAdapter } from "@vibeorm/adapter-pglite";
// no dataDir → a fresh in-memory database
const db = VibeClient({ adapter: pgliteAdapter() });
const users = await db.user.findMany({ where: { email: { contains: "@example.com" } }, take: 10 });
await db.$disconnect();const persistent = pgliteAdapter({ dataDir: "./.pglite" }); // persisted on disk
const shared = pgliteAdapter({ pglite: existingInstance }); // reuse a warm instancedisconnect() ends the adapter for good: work that already started finishes, an instance the adapter created is closed, and every later call refuses with VIBE_ADAPTER_CLOSED. Create a new adapter to connect again; with no dataDir its instance is a new, empty database.
Options
pgliteAdapter(options?: PgliteAdapterOptions):
| Option | Type | Default | Meaning |
|---|---|---|---|
| dataDir | string | — (in-memory) | Directory to persist the database in. PGlite's own prefixes (idb://, memory://) work here too |
| pglite | PGliteInterface | — | An already-created PGlite instance to run on. The adapter never closes an instance it did not create; disconnect() then only ends the adapter |
There is no pool size and no connection URL: PGlite is a single embedded connection.
Runtime support
| Runtime | Supported | |---|---| | Bun ≥ 1.2 | yes | | Node | yes |
PGlite is WASM, so it needs no native build and no database server on either runtime.
Capabilities
PGlite speaks the postgres dialect, so the full capability set is available: RETURNING, scalar array columns, native enums, ILIKE, DISTINCT ON, partial indexes, transactional DDL, createManyAndReturn, a real JSON column type, native NULLS FIRST/NULLS LAST, and the "join" relation strategy (LEFT JOIN LATERAL plus JSON aggregation). The generated capability table lives in docs/dialects.md.
Two behaviours are specific to running in-process, and both are enforced rather than silent:
- Transaction
timeoutis refused. PGlite acceptsSET LOCAL statement_timeoutand even reports it back throughSHOW, but the single-threaded WASM build has no timer interrupt and never cancels a running statement. Passingtimeoutto$transactiontherefore throwsVIBE_UNSUPPORTED_CAPABILITYinstead of becoming a no-op.isolationLevelis applied for real. Use a PostgreSQL server adapter where the option is genuinely enforced. - One connection, one queue. Every operation is serialized through a single operation queue, and a whole transaction holds that queue until it commits or rolls back. Calling the root client from inside a transaction callback would queue behind the transaction it is running in, so it is refused with
VIBE_TRANSACTION; use thetxclient the callback receives.
Nested transactions become savepoints on the open transaction, named from a counter shared across the whole top-level transaction.
On PGlite's in-process class the adapter sends a transaction's control statements itself (BEGIN, COMMIT, ROLLBACK, SET TRANSACTION, the savepoint statements): each is the same Query + Sync pair PGlite's transaction() and exec() send, in one engine call, inside PGlite's transaction lock, with PGlite's error objects. A transaction costs about 60 µs less, a savepoint pair about 60 µs less. Code that observes execProtocolStream sees these calls; other instances (PGliteWorker, another copy of the module) keep PGlite's transaction().
Caller cancellation of reads
This adapter declares readCancellation: "before-dispatch" on root, transaction and savepoint handles. Execution options are separate from query arguments and apply only to known reads. An abort observed before dispatch, including after waiting for the operation queue, prevents SQL. If a statement has already started, it settles before successful rows are discarded with VIBE_CANCELLED and databaseCancelled: false. Unrelated driver failures keep their mapped codes.
cancellation: "running" refuses with VIBE_UNSUPPORTED_CAPABILITY before instance creation or SQL. The installed PGlite interface has no cancellation method, and its current in-process execution calls the synchronous WASM main loop on the same thread. This adapter does not use a worker interrupt transport or reimplement the PostgreSQL protocol. Writes and raw SQL are outside this contract. An injected PGlite instance is never closed just to service a read signal.
Error mapping
PGlite runs the real PostgreSQL error protocol in-process, so its errors carry the same SQLSTATE plus constraint / table / column, which end up in meta; the driver error is attached as cause. Table (PGLITE_SQLSTATE_ERROR_CODES, frozen and mirrored by tests):
| SQLSTATE | Condition | VibeError code | meta.reason |
|---|---|---|---|
| 23505 | unique_violation | VIBE_UNIQUE_VIOLATION | |
| 23503 | foreign_key_violation | VIBE_FK_VIOLATION | |
| 23502 | not_null_violation | VIBE_VALIDATION | |
| 23514 | check_violation | VIBE_VALIDATION | |
| 22P02 | invalid_text_representation | VIBE_VALIDATION | |
| 40001 | serialization_failure | VIBE_TRANSACTION | |
| 40P01 | deadlock_detected | VIBE_TRANSACTION | |
| 57014 | query_canceled | VIBE_TRANSACTION | "timeout" |
| anything else, including PGlite's own failures (closed database, WASM init) | | VIBE_ADAPTER | |
A transaction callback's own error propagates untouched; PGlite has already rolled the transaction back by then.
