Database Drivers
Overview of available database drivers for VibORM
VibORM supports multiple database drivers across four dialects: SurrealQL, PostgreSQL, MySQL, and SQLite.
Every PostgreSQL and MySQL driver takes one optional namespace — the
PostgreSQL schema or MySQL database its objects live in. See
Namespaces. Production pool ownership, readiness,
timeouts and recovery are covered in Production connections.
PostgreSQL Drivers
| Driver | Package | Best For |
|---|---|---|
| pg | pg |
Traditional Node.js apps with connection pooling |
| postgres | postgres |
Modern apps using postgres.js |
| pglite | @electric-sql/pglite |
Local/embedded PostgreSQL (WASM) |
| neon-http | @neondatabase/serverless |
Serverless/edge deployments |
| bun-sql | bun:sql |
Bun runtime applications |
SurrealDB
| Driver | Package | Best For |
|---|---|---|
| surrealdb | surrealdb |
Graph relations, in SurrealDB’s own language |
MySQL Drivers
| Driver | Package | Best For |
|---|---|---|
| mysql2 | mysql2 |
Traditional Node.js MySQL apps |
| planetscale | @planetscale/database |
PlanetScale serverless MySQL |
SQLite Drivers
| Driver | Package | Best For |
|---|---|---|
| sqlite3 | better-sqlite3 |
Node.js apps with local SQLite |
| libsql | @libsql/client |
Turso cloud or local libSQL |
| bun-sqlite | bun:sqlite |
Bun runtime with SQLite |
| d1 | Cloudflare Workers | Cloudflare D1 in Workers |
| durable-object | Cloudflare Workers | A Durable Object’s own SQLite storage |
Feature Matrix
| Driver | Dynamic Transactions | Batch Mode | Migration Atomicity | Environment |
|---|---|---|---|---|
| pg | ✅ Full | ✅ Full | ✅ Full | Node.js |
| postgres | ✅ Full | ✅ Full | ✅ Full | Node.js |
| pglite | ✅ Full | ✅ Full | ✅ Full | Any (WASM) |
| neon-http | ❌ Unsupported | ✅ Full | ⚠️ apply only, one request per transactional group |
Any |
| bun-sql | ✅ Full | ✅ Full | ✅ Full | Bun |
| mysql2 | ✅ Full | ✅ Full | ⚠️ DDL-limited | Node.js |
| planetscale | ✅ Single-shard atomic | ✅ Single-shard atomic | ❌ Effectful V1 commands refused | Any |
| sqlite3 | ✅ Full | ✅ Full | ✅ Full | Node.js |
| libsql | ✅ Local; hosted conditional | ✅ Local; hosted conditional | ❌ Effectful V1 commands refused | Any |
| bun-sqlite | ✅ Full | ✅ Full | ✅ Full | Bun |
| d1 | ❌ Unsupported | ✅ Full | ❌ Effectful V1 commands refused | Workers |
| durable-object | ✅ Full | ✅ Full | ✅ Full | Durable Objects |
Runtime transactions do not prove migration support. PlanetScale, LibSQL, and
D1 retain offline generation and admitted read-only paths, but effectful
push, apply, down, reset, and locked verify refuse before effects.
Neon HTTP is the same except for apply, which sends each transactional group
as one request (Neon HTTP). Admitted push({ dryRun: true }) paths remain available, subject to
the driver’s introspection limitations.
MySQL2 migrations additionally require a resolved namespace and the explicit
non-redirecting transport attestation. See the
migration capability table,
MySQL namespace rules, and
D1 read-only migration paths.
Nested writes and failures per driver
A nested write (create with nested create/connect/connectOrCreate,
update with nested writes, createMany of relation-bearing rows, upsert)
is one operation to the client. What the transport underneath guarantees
differs by driver, and these are the facts the engine relies on and verifies:
| Driver | A nested write runs as | A statement fails mid-way | Bind parameters per statement | Verified |
|---|---|---|---|---|
| pg | one interactive transaction | rolled back | 65 535 | real Neon PostgreSQL, owned and supplied pool, west-of-UTC timestamp and exact numeric/list cases |
| postgres | one interactive transaction | rolled back | 65 533 | real Neon PostgreSQL, owned and supplied configured client, same fidelity cases |
| pglite | one interactive transaction | rolled back | 32 767 | local PGlite provider tests |
| bun-sql | one interactive transaction | rolled back | 65 535 | Bun provider qualification is separate from the Node transports |
| mysql2 | one interactive transaction | rolled back | 65 535 | local MySQL qualification; see below |
| planetscale | one single-shard transaction | rolled back within the supported shard | 65 535 | controlled transport contracts; hosted qualification remains separate |
| sqlite3, libsql, bun-sqlite | one interactive transaction | rolled back | 32 766 | actual better-sqlite3 and local libSQL regressions; Bun uses its own provider tests |
| neon-http | one atomic batch; work that must read the database after an earlier write takes another committed batch | the failing batch rolls back; earlier acknowledged batches remain committed, reported through committedSegments; an uncertain outcome uses mayHaveCommittedSegment |
65 535 | actual Neon HTTP 1.2: failed-batch atomicity, Serializable batch options, durable commit notification, and post-commit result failure; credential-gated by NEON_DATABASE_URL or NEON_TEST_DATABASE_URL |
| d1 | one atomic batch, or one batch after another where a part must read between two writes; generated references use the ordinary emptied __viborm_batch_refs scratch table |
the failing batch rolls back; earlier acknowledged batches remain committed | 100 | local Workers D1 tests (provider-d1); no hosted Cloudflare D1 qualification |
| durable-object | one ctx.storage.transaction() |
rolled back | 100 | local workerd tests (provider-durable-object); no hosted Cloudflare qualification |
A scalar in / notIn list is one bound value on PostgreSQL (pg, postgres, pglite, bun-sql, neon-http), SQLite (sqlite3, libsql, bun-sqlite) and D1, so it does not count against these limits. On mysql2 and planetscale each member is one bound value. On every driver a mode: "insensitive" list binds one value per member. On SQLite, libSQL, bun-sqlite and D1 a list of non-integer numbers also binds one value per member.
createMany with skipDuplicates suppresses a relation-bearing member or
nested member inside an interactive savepoint. neon-http, d1, and explicit
array transactions cannot provide that member rollback region, so unsupported
suppression raises UnsupportedOperationError during preparation before writes.
Root scalar SQL conflict skipping remains supported. MySQL per-row suppression
also requires an interactive savepoint and is refused inside an array transaction.
Captured-set mutations, per route
A selected updateMany or deleteMany on a provider that cannot return the
rows it writes reads the rows it will write, then writes them. Both routes
give the same answer: a row that stopped matching between the read and the
write is not written. On an interactive transaction (pg, postgres,
pglite, bun-sql, mysql2, planetscale, the three SQLite drivers) the
rows are held from the read to the write. On the batch-only routes
(neon-http, d1) the batch first asks again for the rows the call read, and
the writing statement names those rows and repeats the call’s own filter. A
change seen before the batch writes makes the call plan again. When the write
itself takes fewer rows than were read, the answer is the
selected-row cardinality changed error.
What that error leaves behind is the transport’s. On a batch-only route the batch that carried the write has already been acknowledged when the count is checked, so the error reports the acknowledged effects alongside the result-phase failure rather than claiming a rollback that no longer exists. A check after dispatch cannot undo a committed batch.
A nested updateMany or deleteMany that writes nothing under the members it
names is one statement on every driver: its filter and the membership are read
when it runs, once. It holds the junction links it reads the membership from,
so a member that left the relation before it ran is not written, and one that
joined is. Where each member has writes of its own under it, the call reads the
members first; the unit that writes them asks for them again and holds them, so
a member that changed before the unit stops it before any write and the call
plans again once. SELECT … FOR UPDATE locks the rows it reads; it does not
exclude rows that appear afterwards, and no driver here claims that it does.
MySQL, locally qualified
mysql2 is qualified against a local MySQL 8.4 in its own right — schema push
and re-push, the migration and namespace boundaries, the read and nested-write
inventory, and concurrency — rather than inheriting its status from the shared
transport code the table above cites. A
database-selected deadlock victim is a failed transaction on this driver: the
normalized provider error is reported, the victim’s effects are not committed,
and it is neither treated as an eligible unique-key race nor replayed. The
recoverable unique-key race that upsert and connectOrCreate already
converge under is unchanged. planetscale (hosted MySQL) keeps the shared
transport-code qualification; hosted qualification is deferred.
GeoPoint tiers
| Driver | Tier |
|---|---|
| pg, postgres.js | Full only with postgis: true and a real PostGIS install |
| MySQL2 | Full |
| SQLite3, LibSQL, D1, Bun SQLite | CRUD, equality, inclusive bounds, nullability, cache |
| PlanetScale | Preview until hosted DDL/function/migration qualification |
| Neon HTTP | Conditional on a proven PostGIS target; not qualified by the local estate |
| PGlite | Full with @electric-sql/pglite-postgis loaded, CREATE EXTENSION postgis, and postgis: true |
| Bun SQL | Conditional; no real Bun/PostGIS contract was executed for this release |
Full tier adds polygon membership, meter distance filtering, _distance
selection/order, and spatial indexes. See GeoPoint
for exact operations, physical columns, and migration requirements.
Closing the Connection
await client.$disconnect() closes the client’s driver. Where the platform has
the explicit-resource-management protocol, await using does the same thing at
the end of the block — including when the block is left by a throw:
await using client = createClient({ driver, schema });
const users = await client.user.findMany();
// leaving this block closes `driver`, thrown or not
Disposal and $disconnect() are the same close path, so combining them in
either order closes once and throws nothing. Drivers are disposable too
(await using driver = new PgDriver({ ... })).
The interactive transaction client is deliberately not disposable: inside
$transaction(async (tx) => ...), the transaction owns its driver’s lifetime,
and a using block that tried to close it would be fighting the transaction.
Choosing a Driver
- Node.js traditional: Use
pg,mysql2, orsqlite3 - Serverless/Edge: Use
neon-http,planetscale,libsql, ord1 - Bun runtime: Use
bun-sqlorbun-sqlite - Cloudflare D1: Use
d1with a Workers binding. Static work uses one native atomic batch; supported dynamic record series use ordered committed segments with exact failure progress. - Local development: Use
pglite,sqlite3, orbun-sqlite