Architecture
vdb-mysql is assembled from three layers. You don't need to know this to use it, but understanding the stack helps you reason about where plugins fit, why authentication works the way it does, and what SQL is and isn't supported.
The three layers
Layer 1 — MySQL wire protocol
The outermost layer is powered by Vitess go/mysql. It handles raw TCP connections, the MySQL 8 handshake, and authentication. From the perspective of any MySQL client, driver, or ORM, vdb-mysql looks identical to a standard MySQL 8 server.
This layer is also responsible for authentication. See Authentication below.
Layer 2 — SQL engine
SQL parsing, planning, and execution are handled by go-mysql-server, an embeddable MySQL-compatible SQL engine. It sits behind the wire layer and receives each statement after it has been decoded.
For reads, go-mysql-server calls the VirtualDB storage backend to fetch rows from the source. For writes, it calls the same backend — which captures the change in the delta instead of forwarding it to the source.
go-mysql-server covers a broad subset of MySQL 8 SQL, but it is not a complete implementation. See Known Limitations for the gaps.
Layer 3 — VDB Core
The innermost layer is the pipeline-and-event bus provided by vdb-core. Every significant moment in a connection's lifecycle passes through a named pipeline point — a query arriving, rows being fetched, a row being written. This is where plugins attach.
The delta store itself lives here. When go-mysql-server calls the storage backend for a write, vdb-core records the change in the delta. When it calls for a read, vdb-core fetches source rows and applies the delta overlay before returning them.
See The Delta Model for a full explanation of how the delta works.
Authentication
vdb-mysql holds no user list and no passwords. Authentication is entirely delegated to your source MySQL server.
For every new client connection, vdb-mysql opens a short-lived credential probe — a TCP connection to VDB_AUTH_SOURCE_ADDR — and replays the client's credentials against it. If the source accepts them, the connection is allowed. If not, it's rejected.
After a successful probe, vdb-mysql runs SHOW GRANTS FOR CURRENT_USER() on the probe connection to capture the user's permissions, then closes the probe immediately. Those grants are carried on the session for its entire lifetime.
This means your existing MySQL users work with vdb-mysql automatically — no user management or synchronization needed.
How TLS affects authentication
The authentication mechanism vdb-mysql advertises depends on whether TLS is enabled on its listener:
| TLS enabled | TLS disabled | |
|---|---|---|
| Auth plugin advertised | caching_sha2_password | mysql_clear_password |
| Password delivery | Encrypted by TLS | Plaintext |
| Client opt-in required | No | Yes |
When TLS is enabled, every connection goes through the full authentication exchange — not the fast-auth shortcut — so that the plaintext password is available for the credential probe. TLS on the listener ensures it travels encrypted.
When TLS is not configured, mysql_clear_password is used instead. Most clients refuse this by default. See TLS Configuration for per-client setup instructions.
Related
- The Delta Model — how writes are captured and reads are merged
- Configuration — environment variables
- TLS Configuration — securing the listener
- Plugins — attaching handlers to pipeline points