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, enforces policies on agentic traffic with Guard, and splits analytics queries off to Analytics so your database stays focused on transactional work. Applications keep their existing drivers, SQL, and credentials; they change only the host and port they connect to.

The platform is four components:

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

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, for example rewriting MySQL JSON_OVERLAPS(...) into DuckDB list_has_any(...). 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 (including Analytics).
• 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.

Analytics

Analytics (binary querypilot-analytics) is a separate server process that embeds DuckDB and exposes it over the PostgreSQL wire protocol. Its [replicator] section performs CDC replication from an upstream database, taking a snapshot of existing data first and then streaming changes, so DuckDB holds a continuously updated copy of the configured tables. See the Analytics 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 + Analytics is the HTAP setup: Analytics replicates your tables into DuckDB, and to the Router it is simply another PostgreSQL backend in a pool. Analytical reads route to DuckDB; writes and point lookups stay on the source database. The deployment guide ships this shape.
• 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