Installation & Deployment
This page lists the building blocks of a QueryFlux deployment, what each one does, and the ways to deploy them. To try QueryFlux in a few minutes instead, start with a Quickstart.
Reference architecture
Components
| Component | Purpose | Required? | Options |
|---|---|---|---|
| QueryFlux server | Accepts client protocols, routes each query to a cluster group, enforces concurrency limits, translates SQL, and dispatches to an engine. One Rust binary. | Yes | Binary · Docker · Helm |
| Python + sqlglot | Dialect translation and pythonScript routers. | For translation | Bundled in the Docker image; queryflux --install-deps for the binary |
| Admin API | Health, readiness, /metrics, and the API behind Studio. Runs inside the server on port 9000. | Yes | — |
| QueryFlux Studio | Web UI for clusters, routing, query history, and access control. | No | Included in the default image; omitted in -slim |
| Postgres | Persistence for config, query history, the shared queue, and capacity limits. Required for more than one replica. | Production | Any Postgres; see Multi-replica operations |
| Query engines | Where queries actually run. | Yes | Trino, StarRocks, DuckDB (embedded), Athena, ClickHouse, MySQL, ADBC (Snowflake, Databricks, BigQuery, Redshift) |
| Identity provider | Authenticates clients. | No | Static users, OIDC, LDAP — see Authentication |
| Policy engine | Row filters, column masks, allow/deny. | No | OPA, Cerbos |
| Metrics | Scrapes /metrics on the admin port. | No | Prometheus + the repo's Grafana dashboards — see Observability |
How to deploy QueryFlux
Local (binary)Build with Cargo and run natively on a laptop, VM, or bare-metal host.DockerRun the
ghcr.io/lakeops-org/queryflux image, with or without Studio, standalone or in Compose.Kubernetes (Helm)The charts/queryflux chart — starter install through a production-ready release.| Local (binary) | Docker | Kubernetes (Helm) | |
|---|---|---|---|
| Best for | Development, single VM | Single host, Compose stacks | Production |
| Studio | Run separately | Default image | Default image |
| Replicas | One | One per container (Postgres for more) | Many, with Postgres |
| Autoscaling / PDB / ingress | — | — | Built into the chart |
Ports
Every install method uses the same default ports. Only the frontends you enable in config.yaml listen.
| Port | What | Notes |
|---|---|---|
8080 | Trino HTTP frontend | Trino CLI, JDBC, Python clients |
5432 | PostgreSQL wire frontend | psql, Postgres drivers |
3306 | MySQL wire frontend | mysql, BI tools |
9000 | Admin API | /health, /readyz, /metrics, Studio backend |
3000 | QueryFlux Studio | Default image only, not -slim |
Snowflake HTTP, Arrow Flight SQL, and MCP ports are set per frontend; see the YAML reference.
Persistence: pick before you go to production
persistence.type | Use for | Replicas |
|---|---|---|
inMemory | Local tryouts, single instance | One only. Queues, history, and config live in the process. |
postgres | Production | Many. Config, capacity limits, and the queue are shared across replicas. |
Scaling out
- Multi-replica operations — capacity leases, queue claims, drain, and crash recovery.
- Worker mode — a control plane plus workers that pull config from it, deployed as a pool, a DaemonSet, or sidecars.
- ADBC drivers — install drivers for Snowflake, Databricks, BigQuery, and Redshift backends.
After installing
- Configure clusters, cluster groups, and routers.
- Set up authentication — static users, OIDC, or LDAP.
- Open Studio to watch query history and edit routing.