Getting started

Introduction

StreamQL is a PostgreSQL connection pooler and gateway written in Rust, with an operator console and a record of what it decided for each statement.

What StreamQL is#

Clients connect to StreamQL with the normal PostgreSQL protocol. StreamQL multiplexes many client connections onto a small number of server connections, forwards statements to PostgreSQL unmodified, and keeps evidence about what it did: pins, state replays, policy outcomes and refusals. A web console and an admin API show the same information.

  • Pooling. Transaction, session and statement modes, prepared statements across pooled backends, session state replayed as a minimal diff, queue deadlines and connection limits.
  • Fleet. One primary node is the control plane. Workers join it, receive configuration generations and share one connection budget.
  • Console. Overview, pools, gateways, live and slow queries, decisions, trace, X-ray, alerts, users and roles, MCP access and configuration.
  • Insights. Slow-query templates with a pool wait, database and lock split, captured plans and advice-only hints.
  • Deploy anywhere. A static container image, Docker Compose, Kubernetes manifests, a Helm chart, an operator, and systemd units with deb and rpm packaging.

StreamQL is early software. This guide describes what is implemented today. Features on the roadmap, such as result caching, LISTEN multiplexing and replica routing, are not part of the current data path and are not documented here.

Quick start#

Run StreamQL in front of a PostgreSQL server you already have. PostgreSQL 13 through 19 is supported. The Compose file reads the upstream URL and the admin token from files, so no credentials live in the image or the file.

deploy/docker
git clone https://github.com/streamql/streamql
cd streamql/deploy/docker
mkdir -p secrets
printf 'postgres://app:APP_PASSWORD@db.example.com:5432/app?sslmode=require' > secrets/upstream_url
openssl rand -hex 24 > secrets/admin_token
docker compose up -d

Clients connect on port 6432 with the role and password from the upstream URL. The console and the admin API are on port 9930.

connect
psql 'host=localhost port=6432 user=app dbname=app'
docker compose logs streamql | grep setup_code   # then open http://localhost:9930

StreamQL runs in two ways: full featured with the web console, admin API, alerts, insights and fleet, or pool only without the web UI. Both do the same pooling. See Choose an edition.

Your first pool#

With no [[pool]] entries StreamQL creates a pool on demand for each database a client asks for (defaults.auto_create = true), using the settings in [defaults]: transaction mode and 20 server connections per database and role.

To run a quick load against it, use pgbench through the pooler:

pgbench
pgbench -i -h localhost -p 6432 -U app app
pgbench -S -M prepared -c 40 -j 4 -T 30 -h localhost -p 6432 -U app app

Then open the console on port 9930 and look at Pools to see clients multiplexed onto server connections.

Where to go next#

InstallationDocker, Kubernetes, Helm, systemd.ConfigurationEvery section, default and environment override.PoolingModes, prepared statements, queues, limits.Console guideA walk through every screen.ClusterPrimary, workers, join tokens, rollouts.CLI referenceEvery subcommand and flag.