https://github.com/mevdschee/tqdbproxy
https://github.com/mevdschee/tqdbproxy
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/mevdschee/tqdbproxy
- Owner: mevdschee
- Created: 2026-01-22T11:49:06.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-01-23T01:25:15.000Z (4 months ago)
- Last Synced: 2026-01-23T05:53:22.811Z (4 months ago)
- Language: Go
- Size: 12.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# TQDBProxy
A high-performance MariaDB and PostgreSQL proxy with caching, read replica, metrics, and transaction support.
Blog post: https://www.tqdev.com/2026-tqdbproxy-mariadb-postgresql-proxy/
## Features
- **Query Caching**: Cache SELECT queries with configurable TTL and thundering herd protection
- **Caller Metadata**: Track queries by source file and line number
- **Metrics**: Prometheus metrics for cache hits/misses, query latency, and more
- **Read Replica Support**: Automatic routing of SELECT queries to replicas
- **Transaction Support**: Full BEGIN/COMMIT/ROLLBACK support
- **Interactive Mode**: Full interactive client support
## Performance
Cache hits are as fast as empty queries with 100 connections. Proxy overhead is minimal for queries ≥1ms.
## Quick Start
```bash
# Start the proxy
./tqdbproxy
# Connect via MariaDB client (interactive mode)
mariadb -u tqdbproxy -p -P 3307 tqdbproxy --comments
```
## Using Metadata Comments
Add caller metadata to your queries for better observability:
```sql
/* ttl:60 file:app.php line:42 */ SELECT * FROM users WHERE active = 1
```
NB: When using the MariaDB CLI, you **must** use the `--comments` flag to preserve metadata comments
## Transaction Support
Full transaction support with proper isolation:
```sql
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE id = 1;
UPDATE accounts SET balance = balance + 100 WHERE id = 2;
COMMIT;
```
All query types supported:
- SELECT queries (with optional caching)
- INSERT queries (returns last insert ID)
- UPDATE queries (returns affected rows)
- DELETE queries (returns affected rows)
## Query Status Inspection
Check which backend served the last query:
**MariaDB:**
```sql
mariadb> SHOW TQDB STATUS;
+---------------+---------+
| Variable_name | Value |
+---------------+---------+
| Backend | primary |
| Cache_hit | 0 |
+---------------+---------+
```
**PostgreSQL:**
```sql
tqdbproxy=> SELECT * FROM pg_tqdb_status;
variable_name | value
---------------+---------
Backend | primary
Cache_hit | 0
(2 rows)
```
Values: `Backend` = `primary`, `replicaN`, `cache`, or `none` (no query yet); `Cache_hit` = `0` or `1`.
This is useful for debugging cache behavior during development.
## Read Replicas
Configure replicas in `config.ini`:
```ini
[mariadb]
listen = :3307
primary = 127.0.0.1:3306
replica1 = 127.0.0.2:3306
replica2 = 127.0.0.3:3306
```
Select queries with a TTL hint are round-robin distributed across replicas.
## Thundering Herd Protection
The proxy implements single-flight for warmup and resfresh to prevent concurrent DB queries for the same key.
## Metrics
Access Prometheus metrics at `http://localhost:9090/metrics`:
```bash
curl http://localhost:9090/metrics | grep tqdbproxy_query_total
```
Metrics include file and line labels when metadata comments are used.
## Cluster Setup
DNS round-robin load balancing can be used to distribute queries across multiple proxies.
## Documentation
See [docs/README.md](docs/README.md) for more information.