$ guides / proxysql / proxysql-per-user-max-connections ▌

Operations Guides

ProxySQL per-user max_connections: one application starving the shared proxy

ProxySQL enforces two layers of frontend connection limits: a global ceiling (mysql-max_connections, default 2048) and an optional per-user cap (mysql_users.max_connections, default 10000). The per-user cap is the one most teams leave at default, which is effectively no limit. A single application with a connection leak or misconfigured pool can consume connections toward the global ceiling. Once the global pool is exhausted, every other application sharing that ProxySQL instance is denied new connections.

How the two-layer limit works

ProxySQL’s mysql_users table defines every user that can authenticate against the frontend listener (default port 6033). Each row has a max_connections column that caps concurrent frontend connections for that username. This is a ProxySQL-layer limit, enforced before any backend connection is involved. It is independent of MySQL’s own max_user_connections server variable.

When a new client connects, ProxySQL checks two limits in sequence:

Is the global frontend connection count below mysql-max_connections?
Is this user’s connection count below mysql_users.max_connections?

If either limit is reached, the connection is rejected immediately. There is no queueing. The client sees an error.

Because the default mysql_users.max_connections is 10000, the only effective ceiling for most deployments is the global one. A single user can grow toward mysql-max_connections unchecked, and once the global pool is full, all users are denied equally.

When a user exceeds its per-user cap, ProxySQL logs:

MySQL_Session.cpp:handler___status_CONNECTING_CLIENT___STATE_SERVER_HANDSHAKE(): [WARNING] User 'aaa' has exceeded the 'max_user_connections' resource (current value: 200)

The rejected connection increments Access_Denied_Max_User_Connections in stats_mysql_global. This is distinct from Access_Denied_Max_Connections, which increments when the global ceiling is hit.

Key properties:

Enforced at the proxy, not the backend. The limit applies to frontend connections to ProxySQL, not backend MySQL connections. MySQL’s own max_user_connections is separate and independent.
No queueing. Exceeding the limit rejects the connection immediately.
Per-user, not per-hostgroup. stats_mysql_users shows one row per username across all hostgroups. Frontend connection count aggregates across hostgroups.
Cumulative counter, not a gauge. Access_Denied_Max_User_Connections is monotonically increasing. Compute a rate (delta over time) to detect active rejection.

flowchart TD
    subgraph without ["No per-user cap (default 10000)"]
        A1["App A grows unchecked"] --> A2["Global pool exhausted"]
        A2 --> A3["Apps B and C denied"]
        A3 --> A4["Access_Denied_Max_Connections rises"]
    end

    subgraph with ["With per-user cap set"]
        B1["App A grows"] --> B2["Hits per-user cap"]
        B2 --> B3["Access_Denied_Max_User_Connections rises"]
        B2 --> B4["Apps B and C unaffected"]
    end

The starvation pattern

Teams set a global limit but not per-user limits. One application consumes all frontend connections, starving every other application on the same instance.

Typical sequence:

Multiple applications share a ProxySQL instance, each with its own mysql_users entry. Per-user max_connections is left at 10000.
One application develops a connection leak or enters a retry loop. Its frontend connection count grows steadily.
Its connections approach the global mysql-max_connections ceiling.
New connections from other applications are rejected because the global pool is full. Access_Denied_Max_Connections rises.
The misbehaving application is never throttled because its per-user limit (10000) far exceeds the global ceiling.

The diagnostic trap: the operator investigating connection failures checks ProxySQL and sees backends are ONLINE and the backend pool has free connections. The problem is purely frontend-side. Without per-user connection monitoring, the root cause is invisible.

Setting and verifying per-user limits

Update mysql_users via the admin interface (port 6032), then load to runtime and save to disk:

# Admin password on CLI is visible in ps and shell history. Use --defaults-file in production.
mysql -u admin -p<admin_password> -h 127.0.0.1 -P 6032 \
  -e "UPDATE mysql_users SET max_connections=200 WHERE username='app_a'; LOAD MYSQL USERS TO RUNTIME; SAVE MYSQL USERS TO DISK;"

LOAD MYSQL USERS TO RUNTIME is required. Changes to mysql_users do not take effect until loaded to runtime. ProxySQL uses a three-layer model: MEMORY (what you just edited), RUNTIME (active config), and DISK (persisted config). You must explicitly promote MEMORY to RUNTIME to activate, and save to DISK to persist across restarts.

Verify current limits and utilization:

mysql -u admin -p<admin_password> -h 127.0.0.1 -P 6032 \
  -e "SELECT username, frontend_connections, frontend_max_connections,
      ROUND(frontend_connections * 100.0 / frontend_max_connections, 1) AS utilization_pct
      FROM stats_mysql_users ORDER BY utilization_pct DESC;"

Sort by utilization descending to see which users are closest to their cap.

Check whether connections are actively being denied:

mysql -u admin -p<admin_password> -h 127.0.0.1 -P 6032 \
  -e "SELECT Variable_Name, Variable_Value FROM stats_mysql_global
      WHERE Variable_Name IN ('Access_Denied_Max_User_Connections', 'Access_Denied_Max_Connections');"

These are cumulative counters. A single reading gives the total since ProxySQL started. To detect active rejection, take two readings spaced apart and compute the delta. If Access_Denied_Max_User_Connections is increasing, at least one user is hitting its cap now.

Choosing per-user limits

No universal formula. The cap depends on the application’s expected connection count and total proxy capacity. The principle is isolation: set each user’s limit low enough that no single user can exhaust the global pool, but high enough that the application functions under peak load.

Practical approach:

Measure peak frontend connections per user during normal operation and traffic spikes.
Set the cap at 1.5x to 2x observed peak to allow headroom for bursts.
Ensure the sum of all per-user caps does not exceed mysql-max_connections. Over-subscription can still lead to contention when multiple applications peak simultaneously.
Review limits when onboarding new applications or when workload changes.

For example: three applications share a ProxySQL instance with mysql-max_connections=2048. Observed peaks are 150, 80, and 40 connections. Reasonable caps: 300, 150, and 80. The sum (530) is well under the global ceiling, leaving room for admin and monitor connections.

Signals to watch in production

Signal	Why it matters	Warning sign
`frontend_connections / frontend_max_connections` per user	Direct utilization of each user’s connection budget	Ratio above 90% sustained
`Access_Denied_Max_User_Connections` rate	Connections actively rejected due to per-user cap	Any sustained increase from zero
`Access_Denied_Max_Connections` rate	Connections rejected due to global cap	Any sustained increase (global pool exhausted)
`Client_Connections_connected` vs `mysql-max_connections`	Overall frontend saturation	Connected count above 80% of global ceiling
`Client_Connections_aborted` rate	Clients being rejected for any reason	Sustained non-zero rate
Per-user connection distribution	Whether one user dominates the pool	One user holding more than 50% of total connections

A user at 90% of its cap is not broken; it is approaching a hard wall. This is a ticket-level signal, not a page. The alert gives you time to investigate and adjust before rejections begin. Healthy headroom target: below 80% utilization during peak.

Common pitfalls

Confusing ProxySQL’s per-user limit with MySQL’s max_user_connections. An operator checks MySQL’s SHOW VARIABLES LIKE 'max_user_connections', sees 0 (unlimited), and concludes there is no limit. But ProxySQL enforces its own mysql_users.max_connections independently. The backend is not the bottleneck; the proxy is.
Forgetting LOAD MYSQL USERS TO RUNTIME. A per-user limit set in the admin interface exists only in the MEMORY layer until explicitly loaded. It has no effect until runtime is updated, and it is lost on restart unless saved to disk.
Setting per-user limits but never monitoring utilization. A user approaching its cap indicates an application-side problem (connection leak, pool misconfiguration). The cap prevents starvation of other users but does not fix the underlying issue.
Over-subscribing the global pool. If the sum of per-user limits exceeds mysql-max_connections, users can still be denied when multiple applications peak simultaneously, even though each is within its individual cap.
Not accounting for connection churn. Applications with aggressive connect/disconnect cycles may show low frontend_connections but high Client_Connections_created rates. The per-user limit gates concurrent connections, not connection rate.

How Netdata helps

Netdata’s ProxySQL collector surfaces per-user connection signals that manual checks miss:

Per-user frontend_connections and frontend_max_connections from stats_mysql_users, collected per second, so you can see each user’s utilization trend and spot who is approaching their cap before rejections begin.
Access_Denied_Max_User_Connections and Access_Denied_Max_Connections, collected as counters and automatically converted to rates, so active rejection is visible in real time without manual delta math.
Client_Connections_connected and Client_Connections_aborted, correlated with per-user utilization to distinguish “one user is at its cap” from “the global pool is exhausted.”
Anomaly detection on per-user connection trends, flagging unexpected growth patterns (a slow connection leak) before they hit any static threshold.

When one user’s frontend_connections spikes, you can immediately see whether Access_Denied_Max_User_Connections is rising (the per-user cap is working) or Access_Denied_Max_Connections is rising (the global pool is the bottleneck and per-user limits need tightening).