Installation

vdb-mysql is the MySQL implementation of VirtualDB. It speaks the standard MySQL wire protocol, so your application connects to it exactly as it would any other MySQL server — no code changes required.

Requirements

• A running MySQL 8.x server (your source database)
• A read-only service account on the source with SELECT privileges only
• One of: a Linux/amd64 or arm64 system, Docker, or Go 1.23.3+ to build from source

Option 1: Docker (recommended)

Official multi-arch images for linux/amd64 and linux/arm64 are published to the GitHub Container Registry on every release.

docker pull ghcr.io/virtual-db/mysql:latest

Run it:

docker run --rm \
  -e VDB_SOURCE_DSN="vdb_user:secret@tcp(db.internal:3306)/myapp" \
  -e VDB_AUTH_SOURCE_ADDR="db.internal:3306" \
  -e VDB_DB_NAME="myapp" \
  -p 3306:3306 \
  ghcr.io/virtual-db/mysql:latest

Or with Docker Compose:

services:
  vdb:
    image: ghcr.io/virtual-db/mysql:latest
    restart: unless-stopped
    environment:
      VDB_SOURCE_DSN: "vdb_user:secret@tcp(db.internal:3306)/myapp"
      VDB_AUTH_SOURCE_ADDR: "db.internal:3306"
      VDB_DB_NAME: myapp
      VDB_LISTEN_ADDR: ":3306"
    ports:
      - "3306:3306"

Option 2: Pre-built binary

Linux/amd64 binaries are available on the GitHub releases page.

curl -Lo vdb-mysql https://github.com/virtual-db/mysql/releases/latest/download/vdb-mysql-linux-amd64
chmod +x vdb-mysql
./vdb-mysql

To pin to a specific version, replace latest/download with download/v0.x.x.

Option 3: Build from source

Requires Go 1.23.3 or later.

git clone https://github.com/virtual-db/mysql
cd mysql
CGO_ENABLED=0 go build -trimpath -o vdb-mysql .
./vdb-mysql

Required configuration

VirtualDB is configured entirely through environment variables — no config files needed.

Variable	Description
VDB_SOURCE_DSN	Connection string for your source MySQL server. Must use the read-only account. Format: user:password@tcp(host:port)/dbname
VDB_AUTH_SOURCE_ADDR	host:port of the source server. Used to verify credentials for every incoming client connection.

Recommended optional settings

Variable	Default	Description
VDB_DB_NAME	appdb	The database name VirtualDB exposes to clients. Should match the database in VDB_SOURCE_DSN.
VDB_LISTEN_ADDR	:3306	TCP address VirtualDB listens on.
VDB_PLUGIN_DIR	(none)	Directory containing plugin subdirectories. Omit to run without plugins.

Setting up the source database account

VirtualDB needs its own read-only account to read schema and row data. This is separate from your application users — your app users are proxied through to the source automatically.

CREATE USER IF NOT EXISTS 'vdb_user'@'%' IDENTIFIED BY '<password>';
GRANT SELECT ON myapp.* TO 'vdb_user'@'%';
FLUSH PRIVILEGES;

Use this account's credentials in VDB_SOURCE_DSN.

Example: full startup

export VDB_SOURCE_DSN="vdb_user:s3cr3t@tcp(prod-replica.internal:3306)/myapp"
export VDB_AUTH_SOURCE_ADDR="prod-replica.internal:3306"
export VDB_DB_NAME="myapp"
export VDB_LISTEN_ADDR=":3306"

./vdb-mysql

Verify it's working

Connect with any MySQL client:

mysql -h 127.0.0.1 -P 3306 -u your_user -p myapp

Run a SELECT — it returns live data from your source. Run an INSERT or UPDATE — it succeeds, but your source database is never touched. Disconnect and reconnect — the write is gone.

A note on TLS and client connections

By default, VirtualDB listens without TLS and uses mysql_clear_password authentication. Most MySQL clients refuse cleartext auth by default, so you'll need to pass an extra flag when connecting:

• MySQL CLI: add --ssl-mode=DISABLED --enable-cleartext-plugin
• Go DSN: append ?tls=false&allowCleartextPasswords=true

If your environment requires encrypted connections, see TLS Configuration for how to enable it.

Next steps

• How It Works — understand the delta model and isolation boundary
• Configuration Reference — all environment variables
• TLS Configuration — securing client connections