November 16, 2026 by Rene Cannao · Tech

Query Timeouts That Follow the Query, Not the User

A query timeout is one of those settings where the right value depends entirely on where the query is going. Eight seconds is generous for the OLTP writer and insulting to the reporting replica. Ten minutes is reasonable for the reporting replica and a great way to lose a Saturday on the writer.

Before the hostgroup setting introduced in ProxySQL 3.0.10, the usual choices were:

  • Globally, with mysql-default_query_timeout — one number for all traffic.
  • Per query rule, with mysql_query_rules.timeout — precise, but it means writing and maintaining a rule, and pinning it to a username or a query pattern.

Neither of those is really what you wanted. What you wanted was “queries that end up on the analytics hostgroup get the analytics timeout”, which is a property of the destination, not of who sent the query or what it looks like.

The new attribute

ProxySQL 3.0.10 added default_query_timeout as a key in the JSON hostgroup_settings column of the hostgroup attributes table:

-- 8 seconds for everything routed to hostgroup 100
INSERT INTO mysql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (100, '{"default_query_timeout": 8000}');

LOAD MYSQL SERVERS TO RUNTIME;
SAVE MYSQL SERVERS TO DISK;

The value is in milliseconds, and the accepted range is 1000 to 1728000000 — one second to twenty days — the same upper bound as the global variable (whose value can also be zero to disable the global fallback).

PostgreSQL works identically, on pgsql_hostgroup_attributes:

INSERT INTO pgsql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (100, '{"default_query_timeout": 8000}');

LOAD PGSQL SERVERS TO RUNTIME;
SAVE PGSQL SERVERS TO DISK;

The inserts above assume a new hostgroup attribute row. If a row already exists, merge the new key into its existing hostgroup_settings JSON; preserve every other key rather than replacing the object with just the timeout. Inspect it first:

SELECT hostgroup_id, hostgroup_settings
FROM mysql_hostgroup_attributes
WHERE hostgroup_id = 100;

Run the PostgreSQL statements on the same ProxySQL Admin interface, using the pgsql_ tables and LOAD PGSQL SERVERS TO RUNTIME.

Precedence

For any query, the effective timeout is the first of these that is set:

  1. Query rule — a positive mysql_query_rules.timeout on a matched rule
  2. Hostgroup — a valid default_query_timeout in the backend connection’s hostgroup settings
  3. Global — mysql-default_query_timeout

The PostgreSQL equivalents are pgsql_query_rules.timeout, pgsql_hostgroup_attributes, and pgsql-default_query_timeout.

So a per-hostgroup timeout overrides the global default, and a query rule still overrides everything. A zero global timeout disables that fallback. A zero rule timeout does not disable a valid hostgroup timeout; use a positive rule value to override it.

This ordering is the useful one. Existing rules keep working exactly as they did while the hostgroup attribute gives you a baseline underneath them. Adding a hostgroup timeout changes the limit for queries that previously used the global default.

What it looks like in practice

A fairly ordinary split:

-- Writers: strict. Something that runs this long is a problem, not a report.
INSERT INTO mysql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (10, '{"default_query_timeout": 5000}');

-- Read replicas serving the app: still tight.
INSERT INTO mysql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (20, '{"default_query_timeout": 15000}');

-- Analytics replica: let the reports run.
INSERT INTO mysql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (30, '{"default_query_timeout": 600000}');

LOAD MYSQL SERVERS TO RUNTIME;
SAVE MYSQL SERVERS TO DISK;

Three numbers, no rules, and the policy follows the routing decision you already made. If you later add a rule that sends a specific heavy report to hostgroup 30 with its own timeout, that rule still wins.

Details worth knowing

It is evaluated in constant time. The timeout is read from the hostgroup the connection already belongs to, so selecting this default adds a direct attribute lookup after normal query processing.

An invalid value does not fail the load. If you put something out of range in there, that hostgroup falls back to the global default and the rest of your configuration still loads. You get the fallback rather than a broken load, which is the right trade for a maintenance operation — but it does mean the load can succeed without the limit you intended. Inspect the ProxySQL logs and verify behavior with a controlled query.

It is a normal hostgroup attribute. It participates in LOAD ... SERVERS TO RUNTIME / SAVE ... SERVERS TO DISK and in ProxySQL Cluster synchronisation like everything else in hostgroup_settings. Changes take effect on the next query after the load.

Omit the key to inherit the global default. The internal unset value is -1; it is not a supported JSON timeout value. There is no way to accidentally impose a timeout on a hostgroup by adding an unrelated attribute.

Available in ProxySQL 3.0.10 and later, in all tiers, for both MySQL and PostgreSQL. It was contributed in #5772.

The hostgroup attributes reference and PostgreSQL hostgroup attributes cover the configuration tables. The precedence is implemented in the released MySQL session timeout selection and PostgreSQL equivalent.