QueryFlux architecture documentation
This section describes how QueryFlux is put together: why it exists, how SQL is translated, and how traffic is routed to cluster groups and individual clusters.
| Document | What it covers |
|---|---|
| Motivation and goals | Problem statement, goals, and how QueryFlux fits multi-engine estates. |
| System map | End-to-end query lifecycle, major crates, and component status (high level). |
| Query translation | Dialect detection, sqlglot integration, when translation runs, and schema-aware mode. |
| Routing and clusters | Router chain, routingFallback, cluster groups, load-balancing strategies, and queueing. |
| Query tags | Attaching metadata to queries for routing, observability, and backend forwarding. |
| Query parameters | Typed positional bindings — how ? params flow from frontend to native engine APIs. |
| Observability | Prometheus metrics, Grafana dashboard, QueryFlux Studio, and the Admin REST API. |
| Frontends | Protocol listeners — Trino HTTP, PostgreSQL wire, MySQL wire, Flight SQL, and more. Shared dispatch, session model, and per-protocol details. |
| Extending QueryFlux | Backend (Rust + Studio) and Frontend (new protocols). |
| Auth / authz design | Authentication and authorization design notes. |
Start with Motivation and goals if you are new to the project; use System map as the single-page map of the system.
The canonical Markdown sources live under docs/ in the repository.
