---
title: Database Drivers
description: 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](/docs/drivers/namespaces). Production pool ownership, readiness,
timeouts and recovery are covered in [Production connections](/docs/drivers/production).

## PostgreSQL Drivers

| Driver | Package | Best For |
|--------|---------|----------|
| [pg](/docs/drivers/postgresql/pg) | `pg` | Traditional Node.js apps with connection pooling |
| [postgres](/docs/drivers/postgresql/postgres) | `postgres` | Modern apps using postgres.js |
| [pglite](/docs/drivers/postgresql/pglite) | `@electric-sql/pglite` | Local/embedded PostgreSQL (WASM) |
| [neon-http](/docs/drivers/postgresql/neon-http) | `@neondatabase/serverless` | Serverless/edge deployments |
| [bun-sql](/docs/drivers/postgresql/bun-sql) | `bun:sql` | Bun runtime applications |

## SurrealDB

| Driver | Package | Best For |
|--------|---------|----------|
| [surrealdb](/docs/drivers/surrealdb) | `surrealdb` | Graph relations, in SurrealDB's own language |

## MySQL Drivers

| Driver | Package | Best For |
|--------|---------|----------|
| [mysql2](/docs/drivers/mysql/mysql2) | `mysql2` | Traditional Node.js MySQL apps |
| [planetscale](/docs/drivers/mysql/planetscale) | `@planetscale/database` | PlanetScale serverless MySQL |

## SQLite Drivers

| Driver | Package | Best For |
|--------|---------|----------|
| [sqlite3](/docs/drivers/sqlite/sqlite3) | `better-sqlite3` | Node.js apps with local SQLite |
| [libsql](/docs/drivers/sqlite/libsql) | `@libsql/client` | Turso cloud or local libSQL |
| [bun-sqlite](/docs/drivers/sqlite/bun-sqlite) | `bun:sqlite` | Bun runtime with SQLite |
| [d1](/docs/drivers/sqlite/d1) | Cloudflare Workers | Cloudflare D1 in Workers |
| [durable-object](/docs/drivers/sqlite/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 |

:::info
**Dynamic Transactions** use the callback API: `$transaction(async (tx) => { ... })`

**Batch Mode** uses the array API: `$transaction([op1, op2, ...])`

Drivers marked "Unsupported" reject instead of running non-atomically. See
[Transactions](/docs/client/transactions) for the client API and
[Migrations](/docs/migration#atomicity) for what migration atomicity means
per driver.
:::

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](/docs/drivers/postgresql/neon-http#migrations)). 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](/docs/migration#atomicity),
[MySQL namespace rules](/docs/drivers/namespaces), and
[D1 read-only migration paths](/docs/drivers/sqlite/d1#migrations).

## 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.

:::info
A transport with an interactive transaction never leaves a partial nested
write behind. neon-http and d1 are the only routes where a write that needs
more than one batch can, and there the error carries how many segments
committed so the caller can decide what to do with them.

**What travels in one batch follows the work's own dependencies, not the verb.**
A `create` or `update` with everything nested under it, and a `createMany` or
`updateMany` of relation-bearing rows, at the root or nested, is dispatched as
ONE batch while no part of the write has to hear the database before the next
part can be written. The call knows the rows it creates: a later row's
`connectOrCreate` finds the row an earlier row created without a batch being
sent in between. A key the database generates reaches the
statements that need it inside the same batch. A part that must read what the
database alone can say after an earlier write — rows a cascade or a trigger may
have changed — takes the boundary: what is written so far is dispatched first
(on neon-http and d1 that dispatch is a committed segment, which is what
`committedSegments` counts) and the reading work follows in the next one.
:::

### 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](/docs/schema/scalars/point)
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:

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

:::info
**Type requirements.** Nothing here raises the compiler floor for code that
never writes `await using`: viborm's disposal member is declared so that it
degrades to nothing when `Symbol.asyncDispose` is not declared in your
`lib`/`@types`. The measured floor for consuming the package is `lib: ["es2022"]`
with `skipLibCheck` on and no `@types/node` required — the same floor as before
`await using` existed, verified by `pnpm test:package:consumer-floor`.

To *use* `await using` you need `Symbol.asyncDispose` declared — either a `lib`
including `esnext.disposable` (TypeScript ≥5.2) or `@types/node` ≥20, which
polyfills it — and a runtime that has the symbol (Node ≥18.18).
:::

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