Skip to content

PATTERN Cited by 1 source

Query gateway

Definition

Query gateway is the architectural pattern of placing a proxy / load balancer in front of a heterogeneous fleet of SQL-query clusters, giving clients a single connection URL, and having the gateway route each incoming query to the backend cluster best suited to execute it.

It is the SQL-engine-specific realisation of single-endpoint abstraction + workload-aware routing, combined with gateway-level features like health-aware cluster selection and centralised query history.

Canonical instance: Trino Gateway

Open-source gateway for Trino (originated at Lyft as Presto Gateway). Four headline properties (sources/2026-03-24-expedia-operating-trino-at-scale-with-trino-gateway):

  1. Single connection URL for client tools; workload distribution across multiple Trino clusters is invisible to clients.
  2. Automatic routing of queries to dedicated clusters based on routing rules that inspect tables, query body, and source headers.
  3. No-downtime upgrades (patterns/no-downtime-cluster-upgrade) — blue/green or canary cluster swap behind the gateway.
  4. Transparent capacity changes — add / remove backend clusters without user interruption.

Structural ingredients

  1. Client-facing single URL. Clients point at one address; the gateway does cluster selection.
  2. Cluster fleet model. Named backend clusters grouped into routing groups (e.g. large-cluster, metadata-cluster, gateway-bi). Rules resolve to a group; the gateway picks a healthy cluster from the group.
  3. Routing rule engine. Per-rule condition + actions evaluated per query; rules inspect parsed query properties and HTTP request context (patterns/routing-rules-as-config).
  4. Cluster health tracking. Health-check subsystem computes per-cluster state (HEALTHY / UNHEALTHY / PENDING — concepts/cluster-health-check); the RoutingManager only routes to HEALTHY clusters.
  5. Centralised observability. Query history, per-query metadata, and routing decisions all flow through the gateway → natural place for unified history + source filter
  6. full query text inspection.

Why not just round-robin a TCP LB?

A TCP-level LB in front of a Trino cluster fleet gives you the single URL but not:

  • Workload-aware routing. TCP LBs cannot inspect the SQL query, so they cannot match query shape to cluster shape.
  • No-downtime upgrade. A TCP LB can drain connections but cannot rewrite a Trino client's session to re-plan a query on a new cluster mid-execution; the gateway needs to understand the protocol.
  • Health-aware routing at cluster granularity. TCP LBs see TCP reachability, not Trino cluster "am I ready to accept queries?"

The query gateway is a layer above that — it understands the SQL-engine protocol.

  • Generic API gateway (Amazon API Gateway) is structurally similar but operates on REST / HTTP semantics, not SQL-query semantics.
  • Service mesh sidecar (Envoy) shares the single-endpoint abstraction but operates at service-to-service RPC granularity.
  • Caching proxy tier (Figcache) shares the "proxy in front of a fleet" architecture but the fleet is a data cache, not a query engine.
  • The SQL-query-gateway space is niche enough that Trino Gateway is effectively the de facto open-source implementation; some cloud-managed Trino offerings bake equivalent routing into their service.

Trade-offs

  • Operational substrate. A gateway tier is one more production system to run (HA, upgrades, monitoring). For small fleets the cost is not worth it; for large heterogeneous fleets it becomes load-bearing.
  • Routing-rule complexity growth. Rules accrete over time; a rules UI (Expedia's PR #433) is load-bearing once the rule set is non-trivial.
  • Routing-rule evaluation latency. Every query pays a small routing-rule evaluation cost. Usually negligible against query execution time.

Seen in

Last updated · 200 distilled / 1,178 read