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

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, or sqlite3
  • Serverless/Edge: Use neon-http, planetscale, libsql, or d1
  • Bun runtime: Use bun-sql or bun-sqlite
  • Cloudflare D1: Use d1 with 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, or bun-sqlite

Was this page helpful?