Getting Started

Pull the Router image.

docker pull readysettech/querypilot:latest

Write a minimal querypilot.toml.

The image reads its configuration from /etc/sqp/querypilot.toml (set via the QUERYPILOT_CONFIG environment variable baked into the image). Create querypilot.toml in your working directory:

[general]
pool_mode = "transaction"

[[listeners]]
protocol = "postgres"
bind = "0.0.0.0:5433"

[pools.primary]
role = "primary"
username = "<your_pg_user>"
password = "<your_pg_password>"
database = "<your_database>"
min_connections = 2
max_connections = 50

backends = [
    { host = "127.0.0.1", port = 5432 }
]

[routing]
default_pool = "primary"

[metrics]
enabled = true
bind = "0.0.0.0:9090"

Adjust host/port under backends to point at your PostgreSQL server.

Two things this config does deliberately:

• The pool carries credentials. Inside a container the listener binds 0.0.0.0, and the Router refuses to start a non-loopback listener without authentication (see Security). Clients authenticate to the Router with this same username/password.
• Metrics are on. This also starts the admin API on the metrics IP at the metrics port + 1, in this case 9091. You use it to verify the deployment below.

Validate the config.

docker run --rm -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
  readysettech/querypilot:latest --check

This prints Configuration is valid and exits. The Router's schema is strict: a typo in any key name fails here instead of being silently ignored.

Run the Router.

Run with host networking so 127.0.0.1 in the config reaches PostgreSQL on the host:

docker run -d --name querypilot --network host \
  -v "$(pwd)/querypilot.toml:/etc/sqp/querypilot.toml:ro" \
  readysettech/querypilot:latest

The image exposes 5433 (PostgreSQL wire), 9090 (metrics), and 9091 (admin API) and health-checks itself against http://localhost:9091/api/config/status. Wait for the container to report healthy:

docker ps --filter name=querypilot

To turn up logging without touching the config, pass --log-level debug or set QUERYPILOT_LOG_LEVEL=debug (see environment variables).

Connect and run a query.

Authenticate with the pool credentials from your config:

psql -h 127.0.0.1 -p 5433 -U <your_pg_user> -d <your_database> -c "SELECT 1"

 ?column?
----------
        1
(1 row)

That query went client, Router, pooled backend connection, PostgreSQL, and back.

Verify through the metrics and admin ports.

# Prometheus metrics: the counter increments with each proxied query
curl -s http://127.0.0.1:9090/metrics | grep sqp_queries_total

# Admin API (metrics port + 1): config status
curl -s http://127.0.0.1:9091/api/config/status

# Ask the Router where it would route a query
curl -s "http://127.0.0.1:9091/api/routing/test?sql=SELECT+1"

If sqp_queries_total is greater than zero, you have proxied a query.