The Delta Model

The delta is the central idea behind VirtualDB. Everything else — plugins, TLS, configuration — builds on top of it. Understanding it makes the rest of the system obvious.

What the delta is

When your application runs an INSERT, UPDATE, or DELETE through VirtualDB, the change is captured in an in-memory delta private to that running VirtualDB instance. The change is never forwarded to the source database.

When your application then reads from the same table, VirtualDB fetches the current rows from the source and overlays the delta on top before returning results. Your application sees a fully consistent view that includes its own writes — as if the writes had actually landed in the database.

The delta is process-scoped. It lives entirely in memory for the lifetime of the VirtualDB process. When the process exits, the delta is gone. The source database is left exactly as it was found.

What the delta tracks

Data mutations

Operation	What is stored
INSERT	The complete new row, keyed by its primary key.
UPDATE	Only the changed column values, overlaid on the original source row.
DELETE	A tombstone — the row is excluded from future reads.

VirtualDB correctly handles chained mutations. An UPDATE followed by another UPDATE on the same row, or an UPDATE followed by a DELETE, resolves the stable source key so the delta always reflects the correct final state.

Schema mutations

DDL statements issued through VirtualDB are intercepted at the same layer as INSERT, UPDATE, and DELETE. No DDL is ever forwarded to the source database. The source schema is never altered — not even transiently.

Statement	What is stored
ADD COLUMN	A virtual column appended to the table's schema. Reads through VDB include the new column; the source does not know it exists.
DROP COLUMN	A dropped-column marker. Reads through VDB omit the column; the source column is untouched.
RENAME COLUMN	A column renamed in the virtual schema. The new name is used in all VDB queries; the old name is used by the source.
CREATE TABLE	A fully virtual table. It accepts inserts and serves reads entirely from the delta; the source has no such table.
DROP TABLE	A dropped-table marker. The table appears not to exist in VDB; the source table and all its data remain intact.

Schema mutations compose correctly with data mutations. After an ADD COLUMN, subsequent INSERT and UPDATE statements can read and write the new virtual column. After a DROP COLUMN, the delta automatically excludes that column from all reads and writes. A column that is added and then dropped within the same session is cleanly removed — it is never visible to the client at any point after the drop.

Like data mutations, schema mutations are process-scoped and in-memory. They do not persist across restarts, and they are invisible to any other VirtualDB instance.

The isolation boundary

The isolation boundary is the process boundary.

Each VirtualDB instance has its own completely independent delta. Two instances running simultaneously — even against the same source database — cannot see each other's writes. A write through one instance is invisible to every other instance.

This is what makes VirtualDB safe to use without coordination:

• Each developer runs their own instance. No one's test data touches anyone else's.
• 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.

Transaction isolation

Inside a transaction, writes go into a private per-transaction buffer first. On COMMIT, that buffer is merged into the shared process-level delta. On ROLLBACK, it is simply discarded — as if those writes never happened.

This means the isolation guarantee holds within transactions too: an in-progress transaction's writes are invisible to other connections on the same instance until the transaction commits.

The read path

When your application runs a SELECT:

1. The query arrives. Plugins may rewrite it before execution.
2. Rows are fetched from the source database.
3. The delta overlay is applied:
   • Rows with tombstones are dropped.
   • Rows with update overlays have their changed values applied.
   • Net-new inserts are appended.
4. Plugins may make final adjustments to the merged row set.
5. The result is returned to your application.

Your application always sees the merged view — live source data with your instance's writes layered on top.

The write path

When your application runs an INSERT, UPDATE, or DELETE:

1. The statement is parsed and planned.
2. Each affected row is written to the in-memory delta.
3. VirtualDB responds with an OK.

The source database is never contacted. No write ever reaches it through VirtualDB.

What this means for your application

Your application doesn't need to know any of this. It connects to VirtualDB exactly as it would any other database, issues queries as normal, and gets back correct results. The delta is completely transparent.

The one place this matters is if you expect writes to persist across process restarts or to be visible to other services connecting directly to the source — they won't be. VirtualDB is not a write-through proxy. See Known Limitations if that's relevant to your use case.

Related

• Plugins — hooking into the pipeline at the delta overlay point and other stages
• Pipelines & Events — the full list of pipeline points where the delta is applied