{"id":41735411,"url":"https://github.com/mevdschee/tqdbproxy","last_synced_at":"2026-01-25T00:01:34.493Z","repository":{"id":334046851,"uuid":"1139770568","full_name":"mevdschee/tqdbproxy","owner":"mevdschee","description":null,"archived":false,"fork":false,"pushed_at":"2026-01-23T01:25:15.000Z","size":13508,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-23T05:53:22.811Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mevdschee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-22T11:49:06.000Z","updated_at":"2026-01-23T01:25:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mevdschee/tqdbproxy","commit_stats":null,"previous_names":["mevdschee/tqdbproxy"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mevdschee/tqdbproxy","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevdschee%2Ftqdbproxy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevdschee%2Ftqdbproxy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevdschee%2Ftqdbproxy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevdschee%2Ftqdbproxy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mevdschee","download_url":"https://codeload.github.com/mevdschee/tqdbproxy/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mevdschee%2Ftqdbproxy/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28739320,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-24T22:12:27.248Z","status":"ssl_error","status_checked_at":"2026-01-24T22:12:10.529Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-25T00:00:44.761Z","updated_at":"2026-01-25T00:01:34.475Z","avatar_url":"https://github.com/mevdschee.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TQDBProxy\n\nA high-performance MariaDB and PostgreSQL proxy with caching, read replica, metrics, and transaction support.\n\nBlog post: https://www.tqdev.com/2026-tqdbproxy-mariadb-postgresql-proxy/\n\n## Features\n\n- **Query Caching**: Cache SELECT queries with configurable TTL and thundering herd protection\n- **Caller Metadata**: Track queries by source file and line number\n- **Metrics**: Prometheus metrics for cache hits/misses, query latency, and more\n- **Read Replica Support**: Automatic routing of SELECT queries to replicas\n- **Transaction Support**: Full BEGIN/COMMIT/ROLLBACK support\n- **Interactive Mode**: Full interactive client support\n\n## Performance\n\n![TQDBProxy Benchmark](benchmarks/proxy/proxy_benchmark.png)\n\nCache hits are as fast as empty queries with 100 connections. Proxy overhead is minimal for queries ≥1ms.\n\n## Quick Start\n\n```bash\n# Start the proxy\n./tqdbproxy\n\n# Connect via MariaDB client (interactive mode)\nmariadb -u tqdbproxy -p -P 3307 tqdbproxy --comments\n```\n\n## Using Metadata Comments\n\nAdd caller metadata to your queries for better observability:\n\n```sql\n/* ttl:60 file:app.php line:42 */ SELECT * FROM users WHERE active = 1\n```\n\nNB: When using the MariaDB CLI, you **must** use the `--comments` flag to preserve metadata comments\n\n## Transaction Support\n\nFull transaction support with proper isolation:\n\n```sql\nBEGIN;\nUPDATE accounts SET balance = balance - 100 WHERE id = 1;\nUPDATE accounts SET balance = balance + 100 WHERE id = 2;\nCOMMIT;\n```\n\nAll query types supported:\n- SELECT queries (with optional caching)\n- INSERT queries (returns last insert ID)\n- UPDATE queries (returns affected rows)\n- DELETE queries (returns affected rows)\n\n## Query Status Inspection\n\nCheck which backend served the last query:\n\n**MariaDB:**\n```sql\nmariadb\u003e SHOW TQDB STATUS;\n+---------------+---------+\n| Variable_name | Value   |\n+---------------+---------+\n| Backend       | primary |\n| Cache_hit     | 0       |\n+---------------+---------+\n```\n\n**PostgreSQL:**\n```sql\ntqdbproxy=\u003e SELECT * FROM pg_tqdb_status;\n variable_name |  value  \n---------------+---------\n Backend       | primary\n Cache_hit     | 0\n(2 rows)\n```\n\nValues: `Backend` = `primary`, `replicaN`, `cache`, or `none` (no query yet); `Cache_hit` = `0` or `1`.\n\nThis is useful for debugging cache behavior during development.\n\n## Read Replicas\n\nConfigure replicas in `config.ini`:\n\n```ini\n[mariadb]\nlisten = :3307\nprimary = 127.0.0.1:3306\nreplica1 = 127.0.0.2:3306\nreplica2 = 127.0.0.3:3306\n```\n\nSelect queries with a TTL hint are round-robin distributed across replicas.\n\n## Thundering Herd Protection\n\nThe proxy implements single-flight for warmup and resfresh to prevent concurrent DB queries for the same key.\n\n## Metrics\n\nAccess Prometheus metrics at `http://localhost:9090/metrics`:\n\n```bash\ncurl http://localhost:9090/metrics | grep tqdbproxy_query_total\n```\n\nMetrics include file and line labels when metadata comments are used.\n\n## Cluster Setup\n\nDNS round-robin load balancing can be used to distribute queries across multiple proxies.\n\n## Documentation\n\nSee [docs/README.md](docs/README.md) for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmevdschee%2Ftqdbproxy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmevdschee%2Ftqdbproxy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmevdschee%2Ftqdbproxy/lists"}