FAQ and troubleshooting

Questions#

Is StreamQL production ready?#

It is early software. The pooler core, fleet, console and insights are implemented and tested against PostgreSQL 13 to 19, but the project is young. Run it next to your current pooler before you move traffic.

Does it cache query results?#

No. Caching and coalescing are on the roadmap and are not part of the current data path. Statements are forwarded unmodified.

Does anything leave my network?#

StreamQL has no tracking and needs no external service. The slow-risk estimate runs in the process. Alert channels and single sign-on call only the providers you configure.

How is it different from PgBouncer?#

It pools like PgBouncer and adds a console, a worker fleet with a control plane, slow-query insights and a decision record per statement. In the repository benchmarks it has higher throughput than single-process PgBouncer at 100 and 500 clients, while PgBouncer uses less CPU and memory and has lower p99 under load.

Is there enterprise support?#

Yes. For support, deployment help and managed setup on your cloud, contact us.

Troubleshooting#

Clients get error 53000#

The pool is full and the client waited longer than queue_timeout_ms. Look at Pools for waiting clients, raise max_size within your connection budget, add a reserve, or shorten transactions.

A client limit was reached: limits.max_user_clients or max_db_clients, or listen.max_client_connections.

A statement is rejected in statement mode#

Statement pooling rejects BEGIN with error 0A000. Use transaction or session mode for transactions.

/readyz returns 503#

The upstream has been unreachable for longer than upstream.readiness_grace_s. Check the upstream URL, network and TLS settings. The process stays alive, and /livez still answers.

Connections are pinned#

Open Decisions and filter for the pin reason, for example POOL_PINNED_ADVISORY_LOCK. Remove the session-level feature, attest a function with session.attested_functions when it has no session effects, or use session mode for that pool.

Console changes are lost after a restart#

Set admin.state_file so configuration changed through the API is stored. The Databases screen shows a warning while it is unset.

A worker cannot join#

Check that the worker reaches the control plane (fleet.listen, port 9931 by default), that the token has not expired or been used up, and that the clocks agree. The control plane returns codes such as JOIN_DENIED and WORKER_REVOKED.