Introduction

VirtualDB is a database proxy. It sits in front of your existing database server and intercepts every connection, query, and write that your application makes.

It is not a new database. It does not store data permanently. It does not require you to migrate, seed, or manage a separate environment. Your database doesn't move.

The problem it solves

Every developer working against a shared database is a liability. A bad migration, a runaway DELETE, a forgotten WHERE clause — any of these can corrupt data that every other developer, every CI pipeline, and every test suite depends on. The standard responses are painful: spin up a full copy of the database per developer, maintain teardown scripts, or work against stale fixtures that drift from production.

VirtualDB takes a different approach. It gives every process its own private view of the database, with zero infrastructure overhead.

How it works

When your application sends a read, VirtualDB forwards it to the source database and streams the result back — exactly as if VirtualDB weren't there.

When your application sends a write, VirtualDB captures it in a private, in-memory delta. The write is never forwarded to the source. Subsequent reads are answered using the merged view of source data plus the delta, so your application sees a fully consistent result.

When the VirtualDB instance exits, the delta is discarded. The source database is left exactly as it was found.

The isolation boundary

The isolation boundary is the process boundary.

Each VirtualDB instance has its own delta. Two instances running at the same time — even against the same source database — have completely independent deltas. A write made through one instance is invisible to all others.

• Each developer runs their own instance. No one's changes affect anyone else.
• Each CI job runs its own instance. Jobs are isolated with no shared state to clean up.
• Each AI agent runs its own instance. Autonomous writes never reach the source.

Key concepts

Source database

The real database server that VirtualDB proxies. VirtualDB requires a read-only service account on the source. It never writes to the source directly.

Delta

The private, in-memory set of writes captured by a VirtualDB instance during its lifetime. It is local to the instance, never persisted, and never shared. See The Delta Model for a deep dive.

Wire protocol

VirtualDB speaks the native wire protocol of your database. Any client, ORM, or query builder that already works with your database works with VirtualDB — no SDK, no code changes, no adapter layer.

Driver

A driver is the protocol-specific component of VirtualDB. vdb-core is the protocol-agnostic framework; a driver implements the wire protocol boundary for a specific database. vdb-mysql is the MySQL driver and the first available implementation.

Plugin

Plugins are out-of-process executables that connect to VirtualDB over JSON-RPC 2.0 on Unix sockets. They can intercept and modify queries at well-defined pipeline points without touching VirtualDB's core. See Plugins.

Current status

VirtualDB is in Public Alpha. MySQL is the first supported database, available today as a pre-built Docker image and Linux/amd64 binary. Postgres and additional drivers are on the roadmap.

VirtualDB is licensed under the Elastic License 2.0 — free to self-host. A managed hosted offering is planned.

Next steps

• The Delta Model — understand exactly how writes are captured and reads are merged
• Plugins — extend VirtualDB without modifying it
• MySQL: Installation — get vdb-mysql running against your source database