What is QueryPilot?

QueryPilot is a SQL proxy built for modern workloads. It speaks the PostgreSQL and MySQL wire protocols on the front; behind them it accelerates query processing with automatic caching and enforces policies on agentic traffic with Guard, keeping your database focused on serving your application. Applications keep their existing drivers, SQL, and credentials; they change only the host and port they connect to.

The platform is three components:

Only the Router is mandatory. Each of the other two is opt-in and independent of the other.

Architecture

The Router

The Router (binary querypilot) is the core of the platform and the only required process. It is configured by a single TOML file, querypilot.toml (see the configuration reference).

• Wire protocols. Each [[listeners]] entry serves either the PostgreSQL or the MySQL protocol. A single Router can serve both at once on different ports.
• Connection pooling. Named [pools.<name>] hold connections to backend servers, with three modes: session (connection held for the whole client session), transaction (released at COMMIT/ROLLBACK, the default), and statement (released after every statement). Backends within a pool are selected round-robin, and replicas can be skipped when their measured lag exceeds max_replica_lag.
• Query routing. For each query the Router first honors transaction pinning (in-transaction statements stay on the same backend connection), then translation rules, then pattern rules, then regex rules, then the read/write split, falling back to default_pool.
• Query translation. Translation rules rewrite a query's SQL and pin it to a target pool, rewriting a function call the target backend does not support into its equivalent. Literals are parameterized on both sides, so one rule covers every query with the same shape regardless of values.
• Cross-protocol pools. A pool can override the backend protocol, so a MySQL client can be served transparently from a PostgreSQL-speaking backend.
• Observability and control. With [metrics] enabled = true the Router serves Prometheus metrics (sqp_* series) and a REST admin API on the same IP at the metrics port + 1 (9090 metrics / 9091 admin by convention).

Accelerator

The Accelerator watches query traffic, ranks the hottest queries, creates caches for them on a Readyset deployment, and installs the routing rules that steer matching queries to the Readyset pool. It runs in two forms: in-process, enabled by a [plugins.accelerator] block in querypilot.toml, or standalone as the querypilot-accelerator binary managing a ProxySQL or Router deployment. See the Accelerator guide.

Guard

Guard is an in-process plugin enabled by a [plugins.guard] block in querypilot.toml. It assigns each session a trust level, evaluates YAML policies and a trusted-query registry against every query, and can allow, amend, or block, or run in shadow/warn mode that only records what it would have done. Every decision is written to an audit sink. See the Guard guide.

How the components compose

• Router alone is a protocol-aware pooling proxy with routing rules: read/write splitting, query rejection, multi-pool fan-out.
• Router + Accelerator (+ Readyset) adds automatic caching: the plugin creates Readyset caches for hot queries and routes matching traffic to them.
• Guard layers policy enforcement onto any of the above.

Plugins are opt-in via their config blocks; when none are enabled the plugin chain is empty and adds zero per-query overhead.

Compatibility