Configuration Reference

vdb-mysql is configured entirely through environment variables. There are no config files to manage.

All variables

Variable	Default	Required	Description
VDB_SOURCE_DSN	(empty)	Yes	Connection string for the source MySQL server. Must use a read-only account. Format: user:password@tcp(host:port)/dbname
VDB_AUTH_SOURCE_ADDR	(empty)	Yes	host:port of the source MySQL server. Used to verify credentials on every incoming client connection.
VDB_LISTEN_ADDR	:3306	No	TCP address and port that vdb-mysql listens on for client connections.
VDB_DB_NAME	appdb	No	Database name exposed to connecting clients. Should match the database in VDB_SOURCE_DSN.
VDB_PLUGIN_DIR	(none)	No	Directory scanned one level deep for plugin subdirectories. Leave unset to run without plugins.
VDB_TLS_CERT_FILE	(empty)	No	Path to a PEM-encoded TLS certificate. Enables TLS on the listener. Must be set together with VDB_TLS_KEY_FILE.
VDB_TLS_KEY_FILE	(empty)	No	Path to a PEM-encoded private key. Required when VDB_TLS_CERT_FILE is set.

The source database connection

VirtualDB opens two types of connections to your source MySQL server:

Connection type	Frequency	Purpose
Auth probe	Once per client connection	Opens briefly to verify the client's credentials against the source, then closes immediately.
Data pool	Persistent, shared	Fetches schema metadata and row data on behalf of queries.

Both connection types use the same MySQL server. VDB_AUTH_SOURCE_ADDR should point to the same host and port as the host in VDB_SOURCE_DSN.

Setting up the source account

The account in VDB_SOURCE_DSN is VirtualDB's own service account. It only needs SELECT access, which ensures VirtualDB can never modify your source data at the database level.

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

Your application users are separate. When an application user connects to vdb-mysql, their credentials are proxied to the source for verification — they don't need any special access on the VirtualDB side.

TLS

TLS on the listener is disabled by default. To enable it, set both certificate variables before starting vdb-mysql:

VDB_TLS_CERT_FILE=/etc/vdb/server.crt \
VDB_TLS_KEY_FILE=/etc/vdb/server.key \
./vdb-mysql

Setting one without the other causes vdb-mysql to exit with an error at startup.

TLS configured here applies only to client connections — the connection between your application and vdb-mysql. TLS on the leg from vdb-mysql to the source database is a separate concern governed by your source server's requirements.

See TLS Configuration for the full guide, including generating a self-signed certificate and connecting various clients.

Database name alignment

The database name your application uses in its connection string must match VDB_DB_NAME. If your application connects to myapp, set VDB_DB_NAME=myapp and use myapp as the database in VDB_SOURCE_DSN.

The default value (appdb) is intentionally generic. Most applications will want to override it.

Related

• Installation — getting vdb-mysql running
• TLS Configuration — securing client connections
• Plugins — the plugin system and VDB_PLUGIN_DIR