VirtualDB

Appearance

Known Limitations ​

vdb-mysql is in active early-alpha development. This page is an honest accounting of the current boundaries so you can make an informed decision before building on it.

By design ​

These are deliberate architectural decisions, not bugs. They apply to all VirtualDB drivers, not just MySQL.

Writes never reach the source database ​

All INSERT, UPDATE, and DELETE statements are captured into VirtualDB's in-memory delta. They're reflected back to the client and visible to subsequent reads within the same process — but they never reach the source database.

This is intentional. VirtualDB is designed for use cases where you want isolation between what the application sees and what the source contains: development environments, test data overlays, read-model construction. If you need writes to flow through to the source, VirtualDB is not the right fit for that use case yet. Persisted write-through is on the roadmap.

See The Delta Model for the full picture.

The delta does not persist across restarts ​

All captured writes are lost when the process exits. There is no snapshot, replay, or export mechanism in this release.

MySQL-specific gaps ​

DDL support is limited to column and table operations ​

ADD COLUMN, DROP COLUMN, RENAME COLUMN, CREATE TABLE, DROP TABLE, RENAME TABLE, and TRUNCATE TABLE are all intercepted and captured in the schema delta. However, several gaps remain in this release:

  • ADD COLUMN ... AFTER <col> — column ordering is not respected. Added columns are always appended at the end of the virtual schema, regardless of the AFTER clause.
  • CREATE TABLE rows excluded from SHOW TABLES — tables created through VirtualDB do not appear in SHOW TABLES or INFORMATION_SCHEMA.TABLES. Direct table queries and SELECT work correctly; only schema enumeration is affected.
  • Index DDL is recorded but has no effect — CREATE INDEX, DROP INDEX, and ADD INDEX within ALTER TABLE are intercepted and stored in the schema delta, but they are not surfaced to the query planner. Queries that depend on index-based plans will not benefit from virtually-added indexes.
  • Other DDL — ALTER TABLE operations beyond column and index changes (e.g. constraint changes, engine modifications), and CREATE VIEW are not supported in this release.

vdb-mysql uses go-mysql-server as its SQL engine. It covers a broad subset of MySQL 8 SQL, but it is not a complete implementation. You may hit differences with:

  • Stored procedures and complex user-defined functions
  • Certain window functions or advanced analytical queries
  • Edge cases in type coercion and implicit conversions

If a query works against MySQL directly but fails against vdb-mysql, check the go-mysql-server issue tracker before filing a VirtualDB bug.

One database per instance ​

vdb-mysql exposes one database name to clients, set via VDB_DB_NAME. Multi-database routing within a single instance is not supported.

TCP connections only ​

vdb-mysql accepts TCP connections only. Unix domain sockets are not supported.

Prepared statement parameter metadata ​

COM_STMT_PREPARE returns no column or parameter metadata. Clients that rely on this metadata before executing a statement may behave unexpectedly.

Pre-built binary is linux/amd64 only ​

The binary attached to each GitHub release targets linux/amd64. The official Docker image supports both linux/amd64 and linux/arm64. To run on other platforms (macOS, linux/arm64 binary only), build from source — see Installation.

Alpha stability ​

All of the following are subject to change before a stable v1:

  • Environment variable names
  • The JSON-RPC plugin protocol and message shapes
  • Pipeline and event names and payload schemas

Pin to a specific release tag rather than latest to avoid surprises.

Released under the Elastic License 2.0.

Copyright © 2026 Anqor LLC