v3.1.11

ProxySQL 3.1.11 Release Notes

Release date: 2026-08-27

ProxySQL 3.1.11 is the Innovative-tier release. It contains every Stable-tier
fix in 3.0.11 and adds authentication capabilities for modern MySQL and MariaDB
clients, per-user certificate policy, independent Admin credentials, and more
accurate Fast Forward Traffic Observer (FFTO) statistics. It also improves the
reliability of the time-series database used for metrics.

The authentication work is the most visible part of this release. ProxySQL can
now complete non-TLS caching_sha2_password full authentication through the
MySQL RSA protocol, accept MariaDB client_ed25519 credentials at the frontend,
and require a verified client certificate for selected users. These features
are opt-in; existing password and TLS deployments continue to work as before.

Why upgrade

• Oracle MySQL clients using --get-server-public-key or a pinned
  --server-public-key-path can complete caching_sha2_password full
  authentication through ProxySQL without a frontend TLS connection.
• MariaDB clients can authenticate to ProxySQL with client_ed25519, including
  during COM_CHANGE_USER.
• Individual mysql_users rows can require a verified frontend certificate,
  independently of password or authentication-plugin choice.
• Admin/Stats credentials and frontend database users can safely share a
  username without overwriting one another in the runtime authentication map.
• FFTO now understands modern MySQL result framing, multi-result responses,
  prepared-statement cursor fetches, and pipelined PostgreSQL completion.
• TSDB collection and rollover no longer race through one shared SQLite
  connection or terminate ProxySQL on a transient database lock.

Before upgrading

• Review mysql_users.attributes for "require_x509": true. Stable 3.0.x does
  not recognize that key, while 3.1.11 enforces it. A row prepared in advance
  will therefore begin requiring frontend TLS and a verified client certificate
  after moving to the Innovative tier.
• RSA authentication protects the password exchange, not the rest of the MySQL
  session. TLS remains the recommended choice when the entire connection must
  be confidential and authenticated.
• If you configure explicit RSA key files, validate ownership, permissions, and
  rotation procedures before loading them. Invalid keys are rejected atomically
  and do not replace the active key snapshot.
• Frontend ed25519 can authenticate from a stored $ED$ public-key credential.
  A backend connection still needs a cleartext password; ProxySQL cannot derive
  that password from an $ED$ public key.
• FFTO remains opt-in. Its buffer limits continue to protect memory: an
  over-limit payload bypasses observation for that session rather than blocking
  Fast Forward traffic.

RSA full authentication for caching_sha2_password

Before this release, ProxySQL could complete caching_sha2_password full
authentication over TLS, but a non-TLS client following MySQL's RSA exchange
could not authenticate. This affected two common Oracle client modes:

• --get-server-public-key, where the client asks ProxySQL for its public key;
• --server-public-key-path, where the client already trusts a pinned key and
  sends the encrypted password immediately.

ProxySQL 3.1.11 implements both paths. Operators control the key manager with:

• mysql-caching_sha2_password_auto_generate_rsa_keys;
• mysql-caching_sha2_password_private_key_path;
• mysql-caching_sha2_password_public_key_path.

For example, automatic key management can be selected in the Admin interface
and then loaded with the other MySQL variables:

UPDATE global_variables
SET variable_value = 'true'
WHERE variable_name =
      'mysql-caching_sha2_password_auto_generate_rsa_keys';

LOAD MYSQL VARIABLES TO RUNTIME;

Generated keys are RSA-2048. Explicit private keys must be unencrypted PKCS#8,
public keys must use the SPKI form, and the pair is checked for matching type,
size, structure, and public/private material. Relative paths are confined below
ProxySQL's data directory; private-file ownership and mode are checked, and
publication is symlink-safe and atomic.

Each authentication exchange retains one immutable key snapshot. This matters
during rotation: a client cannot receive the old public key and then have its
ciphertext decrypted with a newly loaded private key. Malformed ciphertext and
incorrect passwords fail normally, and recovered cleartext credentials are
cleansed and excluded from logs and internal-session output. (#6017, #6032)

MariaDB ed25519 authentication on both sides of ProxySQL

ProxySQL 3.1.11 supports MariaDB's client_ed25519 / auth_ed25519 protocol for
frontend clients. A valid $ED$ public-key credential in mysql_users can be
used for initial login and COM_CHANGE_USER; ProxySQL issues the normal MySQL
Auth Switch request and verifies the client's Ed25519 signature.

Backend client_ed25519 support is shared with the Stable tier. The important
operational distinction is credential material: frontend verification needs the
stored public key, while authenticating ProxySQL itself to MariaDB needs the
user's cleartext password. A public-key-only $ED$ frontend row is therefore
not sufficient for an upstream backend login. Deployments using the same
identity on both sides must retain a usable backend credential. (#6033)

Per-user frontend X.509 policy

The new require_x509 attribute lets operators require a valid client
certificate for a selected MySQL user while leaving the policy unchanged for
other users. A simple row can be configured as follows (merge the key into any
existing attributes rather than discarding them):

UPDATE mysql_users
SET attributes = '{"require_x509": true}'
WHERE username = 'payments_app';

LOAD MYSQL USERS TO RUNTIME;

require_x509: true is additive to normal authentication. The connection must
use frontend TLS, present a peer certificate, pass certificate-chain
verification (X509_V_OK), and then satisfy the user's password/authentication
plugin. The frontend certificate is not forwarded to a backend.

The certificate evidence is captured once for the physical connection and is
also checked during COM_CHANGE_USER, which cannot renegotiate TLS. The policy
runs before row-backed pass-through authentication probes or cache activity, so
an unverified client is rejected before ProxySQL handles a cleartext credential.
Malformed attributes and non-boolean values fail closed. Existing SPIFFE policy
continues to use its stricter identity rules. (#6028)

Admin and Stats credentials no longer collide with frontend users

In earlier releases, admin-admin_credentials, admin-stats_credentials, and
mysql_users shared one frontend credential map. If an Admin account and an
application account had the same username but different passwords, loading one
could overwrite or delete the other. The documented workaround was to keep
those namespaces disjoint.

The Innovative tier now gives Admin/Stats identities their own credential
scope. A username can exist on the Admin port and in mysql_users with different
passwords, and updating admin-admin_credentials no longer removes the matching
frontend row from runtime. Session-aware lookup applies the correct scope for
MySQL and PostgreSQL Admin/Stats connections while leaving Stable 3.0 behavior
unchanged. This is intentionally tier-gated because resolving a formerly
colliding name into two independent identities is a compatibility change.
(#5993)

FFTO understands complete modern result flows

Fast Forward mode minimizes processing by acting as a protocol-aware pipe, but
that also means normal query processing cannot populate digest statistics.
FFTO passively observes the decrypted protocol stream so Fast Forward sessions
can still contribute query text/digest, latency, rows-sent, affected-row, and
error information.

The MySQL observer now frames resultsets correctly when
CLIENT_DEPRECATE_EOF is negotiated, accumulates multi-result responses until
the final result, understands prepared-statement binary rows, and treats
COM_STMT_FETCH cursor batches as part of the right statement. The PostgreSQL
observer uses the same state-machine approach for simple and extended query
flows. Malformed or over-limit traffic bypasses observation safely rather than
changing the forwarded data. (#6047)

Operators can enable observation independently by protocol:

UPDATE global_variables
SET variable_value = 'true'
WHERE variable_name = 'mysql-ffto_enabled';
LOAD MYSQL VARIABLES TO RUNTIME;

UPDATE global_variables
SET variable_value = 'true'
WHERE variable_name = 'pgsql-ffto_enabled';
LOAD PGSQL VARIABLES TO RUNTIME;

For PostgreSQL extended-query pipelines, ReadyForQuery no longer finalizes an
observed command before its response terminator. This prevents a rapid Sync
or pipelined sequence from attributing completion and counters to the wrong
query. (#6021)

TSDB collection and rollover reliability

The TSDB paths used by metric ingestion, discovery, and downsampling share a
SQLite connection. Concurrent access could previously surface SQLITE_BUSY or
interleave discovery and rollover work; in the worst case, a temporary lock
terminated the daemon.

ProxySQL now serializes access to that shared connection, including REST/GenAI
metric discovery, and coordinates the hourly downsampling rollover. A transient
SQLite lock is handled as an operational condition rather than a fatal error.
This is especially relevant to installations that query metrics while collection
and downsampling are active. (#6004, #6107)

Stable improvements included in 3.1.11

ProxySQL 3.1.11 also includes the complete Stable 3.0.11 maintenance set:

• opt-in literal MySQL user-variable tracking and replay across pooled backends
  (#6043);
• opt-in endpoint-wide GTID learning from successful OK packets (#6035);
• safe --idle-threads shutdown and single-flight query-cache refreshes (#6087,
  #6015);
• bounded authentication response handling and OpenSSL handshake randomness
  (#5998, #6104);
• Admin, mysqldump, SQLite3, compressed Unix-socket, and client-connection
  attribute compatibility improvements (#5994, #6079, #6076, #5978, #6077);
• cleanup of the temporary PostgreSQL termination connection and the PostgreSQL
  user-synchronization Scheduler sample (#6130, #6045);
• portable Linux tarballs with bundled OpenSSL and native FreeBSD descriptor
  accounting (#6105, #6030).

Release commit: 7c91137a465454dfc1a62b56f8c188c1ce59c130

SHA256s:

e0f867b338f25f020d269609506c59f70835c96af03eaeaf6581e28c6fd1542d  proxysql-3.1.11-1-almalinux10-clang.x86_64.rpm
e0a118df2900b6cba5385dbd1bdd8a6e1dd36bf781166edbe84b6682c7bb1915  proxysql-3.1.11-1-almalinux10.aarch64.rpm
1623285eebf1d8cc59d482bf6f0faf57aecf624977e9115d9a9a70d03dc6f562  proxysql-3.1.11-1-almalinux10.x86_64.rpm
d7ffef7c331f3872efad26c5daa650469a42a14c3f2782c92d9352b0ca0db18b  proxysql-3.1.11-1-almalinux9-clang.x86_64.rpm
5a2376c4458d7f36816ecbb223e294fa387dde2af932b9fb5c5eecd7d68c7689  proxysql-3.1.11-1-almalinux9.aarch64.rpm
a0a13c55083d874367db276f1fd4979f6b4b57bd17329f023d82db7732371c5c  proxysql-3.1.11-1-almalinux9.x86_64.rpm
f78ba1c0885c3f0edd5b6ebfcb531d2b890d5ce4c052857496ac94264879c06a  proxysql-3.1.11-1-centos10-clang.x86_64.rpm
84d1e78f03a3566559a15cdf9c3a8b7c1b1308fda9da1297bfc4265f95915953  proxysql-3.1.11-1-centos10.aarch64.rpm
4d43638fe6db9c7b3c32d2e6038e453933900769b3994bd7d4d10fb7cf4bb659  proxysql-3.1.11-1-centos10.x86_64.rpm
79101a4c69a3b17d9b9195b154550b4bd7644a247c3a3a13d8f23fc2e5f887d1  proxysql-3.1.11-1-centos9-clang.x86_64.rpm
41ddd48f24f3c990e48263b3f0ddeec942ef017bf5cf7377499a76744a89bc0f  proxysql-3.1.11-1-centos9.aarch64.rpm
c996543ea074a1fa6824e0c68a37bb4a878abb6e11979daeb3dea8962962fccb  proxysql-3.1.11-1-centos9.x86_64.rpm
56a3d011d8ffcac37e6145cab0309b8e73fecfab2241a09b6ee5bad049f15c6a  proxysql-3.1.11-1-dbg-almalinux10.x86_64.rpm
bc5e53ab2bea352273976c402d7a0095511f9863868ef7ea2623f3e9bd2bac58  proxysql-3.1.11-1-dbg-almalinux9.x86_64.rpm
9bdd61599073dab579fd8d85ee879ba84c35fe268b21e7629df2a40c5ebd125c  proxysql-3.1.11-1-dbg-centos10.x86_64.rpm
c2855adcd7449b645a123676afb688fba97f04f5d4b48ca263863069dde87459  proxysql-3.1.11-1-dbg-centos9.x86_64.rpm
8a05579f4ed8565a39ef12c9ec282cfc239187f59e01e97bf0adaf6729eb6565  proxysql-3.1.11-1-dbg-fedora42.x86_64.rpm
20be649f6de9b2e089bf0a7322d8ec37ca833c5b4a2ac464c9eecbf3bbb9cea8  proxysql-3.1.11-1-dbg-fedora43.x86_64.rpm
311534d345e13f1654e8f961a06fa9a4e6650f4464576d51fa2a62591031fe51  proxysql-3.1.11-1-dbg-fedora44.x86_64.rpm
41b70032488d34d343238253b627517cf6ac28340ef2a16e027d88356a147726  proxysql-3.1.11-1-dbg-opensuse15.x86_64.rpm
7e4c36f202589ad43ad80c3ad13b82947653c0679c88ac3c84f62642035c0965  proxysql-3.1.11-1-dbg-opensuse16.x86_64.rpm
1ec634187bcd857a70398e6f2f52ccc783167302b18ed48c233beb1b054ce1c4  proxysql-3.1.11-1-fedora42-clang.x86_64.rpm
c01bdc811ca12c61fc940f8d6f2a8ca9026240b9054a4686dbfa0ce853c288b6  proxysql-3.1.11-1-fedora42.aarch64.rpm
25dbdd8a4716864ff761e324d7d34d974edb3a2c68c137b0136694b5cf09d576  proxysql-3.1.11-1-fedora42.x86_64.rpm
9eedbfce6e16595b61e842f62b3f87a8d4e48423baaff17679fab0ba126f5004  proxysql-3.1.11-1-fedora43-clang.x86_64.rpm
12b37920ddc56b5250efbaf70c4c72a5b8352d6dfaccdeb242f31fb850b1b526  proxysql-3.1.11-1-fedora43.aarch64.rpm
3bd9e745d9897fa34d4e22e0b28f13a8cf966b7ce6a41fb68cce49677a0e2833  proxysql-3.1.11-1-fedora43.x86_64.rpm
0240f5a78971afa8d594c0d1e98496e718df6e3d278f410f84b7f54e21c0400a  proxysql-3.1.11-1-fedora44-clang.x86_64.rpm
2cc382dc64f86e717f824b57bf574df34a8dd2d2e766987bba643b42cbc70f1a  proxysql-3.1.11-1-fedora44.aarch64.rpm
b16b97d8442e2c97fa92a863478c597da04aa257c9a15ce31a1e12f190a2ba24  proxysql-3.1.11-1-fedora44.x86_64.rpm
eb1568aedbba6857f75e282536177ede94f2f872f69af765ec3ba85a4ffd8673  proxysql-3.1.11-1-opensuse15-clang.x86_64.rpm
69a368f8e1343fa7db1659f49210384aa009626ea3d598a49f71316c79c8fd49  proxysql-3.1.11-1-opensuse15.aarch64.rpm
1a1c8048422c5c5a779042cdde0ddf162337f858594afc5d7ff7d32711525b69  proxysql-3.1.11-1-opensuse15.x86_64.rpm
3b58593a49267ade6780e20195d50c5b6fd71d1514be6e93c332464b2bc98f98  proxysql-3.1.11-1-opensuse16-clang.x86_64.rpm
38fff53a61a474c8fbf0b583b716b986b8ac4afcd03133f9088a24461f3ad345  proxysql-3.1.11-1-opensuse16.aarch64.rpm
57708f5289f8ab08443f981cee38eb441444ed90b090dac8e549dfeba3a129c3  proxysql-3.1.11-1-opensuse16.x86_64.rpm
5e641d36be8842e309f478539e2b18d5729b731bae5a691df5a51b4e8afee6ac  proxysql-3.1.11-linux-amd64.tar.gz
4e6a8516075c617c99e4d34470836cded2aad2360e6992989279a02f849a990b  proxysql-3.1.11-linux-amd64.tar.gz.asc
23e4371b3716ae9e26d4c2e30c8e3b724269202e687c8ccf4499dcaf2dffbf3a  proxysql-3.1.11-linux-amd64.tar.gz.sha256
7824b44b6fa161f3baa4e8f70cc0ff2461a6cd076c2da6cfd31605b4e90880bd  proxysql-3.1.11-linux-arm64.tar.gz
a9855d4719531fff74b825925e22502e4c1182ff3c018dfc826be2eeb406a7a9  proxysql-3.1.11-linux-arm64.tar.gz.asc
50749151a9e1c47061889f5fba721b14f04b6ea8e0dec1de6fdca6fa289032db  proxysql-3.1.11-linux-arm64.tar.gz.sha256
223ea2a43390cba472e75f7a2cd3a4eb32a8b3a09c5ac1185569fd12dbd4336b  proxysql-3.1.11.id-hash
b0a8badfe0030f3e3c035f2fab67b0ed0f4e20fcce32a303d576d6561400bb4b  proxysql_3.1.11-dbg-debian12_amd64.deb
c8b3bd22105429f668af6601705a0b35b1dd6f35797a10574493799f344dd836  proxysql_3.1.11-dbg-debian13_amd64.deb
303438e0d64a16320f7d0496046c153298351836fc727955202a71305654ef95  proxysql_3.1.11-dbg-ubuntu22_amd64.deb
a55accc8ae63de51b2bf382822d4876ff775a604d163319cd5174552cfe1cc71  proxysql_3.1.11-dbg-ubuntu24_amd64.deb
00714a1c0397124b4e25b8d6a15364466f2985c8ab39e7cdd228cb612dc72e42  proxysql_3.1.11-debian12-clang_amd64.deb
9bab85d94c776c7e95bec30a1cee8aafc956c334708ee251ba199b8ad90174b1  proxysql_3.1.11-debian12_amd64.deb
84c727d726f3932ece0d5b5106e9baa4d66d4b6b2df4106177b9ab8bb6c1087f  proxysql_3.1.11-debian12_arm64.deb
d0f61a2580790fc597bc3b7b42b7e546830aa9a6f28beed7ad5b8e1e0e71633c  proxysql_3.1.11-debian13-clang_amd64.deb
f9c6f942251a131eb1b62edec133e4e87a20fff234b88689e7f222fe9eda75d6  proxysql_3.1.11-debian13_amd64.deb
2590aca4f3c23e1aba9424ed5827328d9927c162775ce649bf1615915b90f28c  proxysql_3.1.11-debian13_arm64.deb
f92025e84b1496299d8222e53f7953700b3a74925e6b3b197d263991eec3085d  proxysql_3.1.11-ubuntu22-clang_amd64.deb
b981a312a04cbeb20cc5ee8e402ba10b8829d9f4828eace9c56eb1b167337911  proxysql_3.1.11-ubuntu22_amd64.deb
41e91fad18fd0dc91ba4cffd527cc9c4a71de6a3320e486520369a711ec1faac  proxysql_3.1.11-ubuntu22_arm64.deb
a533fa9b4c140775cb097b3848e080bc85e90782574439e45959194fe04ab67f  proxysql_3.1.11-ubuntu24-clang_amd64.deb
868fbda08d110e572bacfb987c779fc09b0641db811e9cdc3cd3307ba6a4dbb5  proxysql_3.1.11-ubuntu24_amd64.deb
694af0863aa55f6979f75dc08e8a6118e576b4bd3f902daf914b75d07ea43449  proxysql_3.1.11-ubuntu24_arm64.deb