High availability

Running several gateways#

• Run more than one gateway pod or worker behind a balancer so a restart of one does not interrupt clients. Clients reconnect to another node when one stops.
• Rolling restarts under load were tested with no failed transactions: a node drains, open transactions finish, and clients reconnect through the other nodes.
• The Helm chart ships a pod disruption budget (maxUnavailable: 1) and zone spreading.

Readiness and liveness#

• /livez answers while the process runs. It never looks at the database, so a database outage does not restart pods.
• /readyz answers 200 while the node can serve clients and 503 (not ready: upstream unreachable) once the upstream has been unreachable longer than upstream.readiness_grace_s (5 s). A not-ready pod is removed from the Service endpoints but keeps running, and it is ready again as soon as the upstream answers.
• Set upstream.readiness_check = false for a process-only readiness.

Upgrades without dropping the listener#

A new binary can take over the listening sockets of the running process, which then drains and exits: start it with streamql --upgrade and set runtime.handoff_socket. With systemd socket activation (LISTEN_FDS) the sockets belong to systemd and never close.

The upstream database#

StreamQL connects to the host and port you give it and does not choose a primary by itself yet. Point upstream.url at a stable endpoint that follows your primary, such as a Patroni or CloudNativePG service, a managed-service endpoint or a virtual IP. Clients reconnect through StreamQL after a failover, and idle server connections are checked before use (defaults.server_check_delay_s).