Skip to content

README.md

Latest commit

 

History

History
62 lines (45 loc) · 2.27 KB

README.md

File metadata and controls

62 lines (45 loc) · 2.27 KB

MariaDB Component

The mariadb component implements the MariaDB wire protocol, allowing TQDBProxy to act as a transparent or intelligent proxy for MariaDB databases.

Features

  • Protocol Handshake: Handles the initial connection and authentication between the client and the backend MariaDB server.
  • Command Interception: Intercepts COM_QUERY, COM_STMT_PREPARE, and COM_STMT_EXECUTE commands.
  • Caching Integration:
    • Checks the cache for SELECT queries with a TTL hint.
    • Automatically caches results returned from the backend if the query is cacheable.
    • Thundering Herd Protection: Serves stale data to concurrent requests while one request refreshes the cache.
    • Cold Cache Single-Flight: Prevents concurrent DB queries for the same uncached key.
  • Prepared Statements: Tracks statement IDs and handles caching for executed prepared statements by combining the query template and parameters into a cache key.
  • Database Sharding: Supports transparent mid-connection shard switching via USE statements or COM_INIT_DB packets, with automatic re-authentication.
  • Transaction Support: Full BEGIN, COMMIT, ROLLBACK support with cache bypass during transactions.

Query Status

Use SHOW TQDB STATUS to see which backend served the last query:

mariadb> SHOW TQDB STATUS;
+---------------+---------+
| Variable_name | Value   |
+---------------+---------+
| Shard         | main    |
| Backend       | primary |
+---------------+---------+

Values: Backend = primary, replicas[n], cache, cache (stale) or none;

Unix Socket Support

The MariaDB proxy can listen on both TCP and a Unix socket simultaneously. Use the socket option to specify a Unix socket path:

[mariadb]
listen = :3307
socket = /var/run/tqdbproxy/mysql.sock
default = main

[mariadb.main]
primary = 127.0.0.1:3306

Connect via TCP or Unix socket:

# TCP
mariadb -u tqdbproxy -p -P 3307 tqdbproxy --comments

# Unix socket
mariadb -u tqdbproxy -p -S /var/run/tqdbproxy/mysql.sock tqdbproxy --comments

Metrics Integration

The MariaDB component records detailed metrics for every query, including latency and cache status, labeled with source file and line number information extracted from SQL hints.

Back to Index