Skip to content

v3.0.11

Latest
Latest

Choose a tag to compare

View all tags
@renecannao renecannao released this 27 Aug 10:08
v3.0.11
7c91137
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.

ProxySQL 3.0.11 Release Notes

Release date: 2026-08-27

ProxySQL 3.0.11 is a Stable-tier maintenance release focused on safer MySQL
multiplexing, more dependable causal reads, stronger authentication handling,
and predictable operation during shutdown and cache refreshes. It also improves
compatibility with common administration clients and makes the generic Linux
tarballs genuinely portable across supported distributions.

Most changes are transparent after an upgrade. The two main behavioral
features—literal MySQL user-variable tracking and GTID learning from OK
packets—are deliberately disabled by default, so operators can evaluate and
enable them independently.

Why upgrade

  • Applications that use simple @user_variables can remain multiplexable
    without losing their session state when a different pooled backend is chosen.
  • min_gtid routing can learn GTIDs returned by ordinary writes, including
    deployments where the same MySQL endpoint appears in writer and reader
    hostgroups.
  • Malformed authentication packets can no longer drive fixed-width reads past
    the supplied response, and handshake randomness now comes from OpenSSL.
  • ProxySQL shuts down safely with --idle-threads, rather than risking a NULL
    dereference or a worker/idle-thread use-after-free.
  • Concurrent clients crossing a query-cache soft TTL now elect one refresher;
    the other clients continue using the still-valid cached value.
  • Generic Linux tarballs include their OpenSSL runtime and are smoke-tested on
    multiple distributions and architectures before upload.

Before upgrading

  • mysql-user_variable_tracking remains 0 by default. Mode 1 also requires
    either mysql-set_parser_algorithm=3 or
    mysql-query_processor_parser=1; ProxySQL does not enable a parser for you.
  • mysql-update_gtid_from_ok remains disabled by default. It consumes only a
    GTID that MySQL actually returns in a successful OK packet; ProxySQL does not
    infer a GTID or turn on session_track_gtids on the application's behalf.
  • The supported tarball entry point is now bin/proxysql. Scripts that bypass
    the launcher and invoke the internal binary directly will not receive the
    bundled OpenSSL library path.
  • Frontend RSA full authentication for caching_sha2_password, per-user X.509
    policy, and frontend MariaDB ed25519 authentication are 3.1/4.0 features.
    Stable 3.0.11 does include MariaDB ed25519 support for backend connections.

Literal MySQL user variables can remain multiplexable

Many database clients attach request metadata to a session with statements
such as:

SET @browser_lang = 'en-US',
    @browser_timezone = 'GMT+2',
    @request_id = 4815162342;

Historically, ProxySQL had to treat user-variable activity conservatively and
bind the session to a hostgroup. That protects correctness, but it also gives up
connection reuse even when the values are simple literals that ProxySQL could
safely preserve.

ProxySQL 3.0.11 adds the opt-in mysql-user_variable_tracking mode. When mode
1 is active, ProxySQL records supported literal assignments only after the
backend accepts the complete SET. If a later query is assigned a different
pooled connection, ProxySQL first replays the missing or changed values on that
backend and then sends the application query. A backend whose materialized map
already matches the frontend session is preferred, avoiding unnecessary replay.

An operator can enable the feature through the ParserSQL SET parser with:

UPDATE global_variables
SET variable_value = '1'
WHERE variable_name = 'mysql-user_variable_tracking';

UPDATE global_variables
SET variable_value = '3'
WHERE variable_name = 'mysql-set_parser_algorithm';

LOAD MYSQL VARIABLES TO RUNTIME;

The feature is intentionally not a general SQL evaluator. It accepts complete,
text-protocol SET statements whose targets are all user variables and whose
values are strings, numbers, hexadecimal/bit literals, or NULL. Expressions,
functions, variable references, prepared statements, mixed system/user-variable
assignments, malformed input, and hidden writes from stored programs retain the
existing safe fallback. With the default
mysql-set_query_lock_on_hostgroup=1, that fallback locks the hostgroup.

Tracking is bounded to 128 names and 64 KiB of stored replay text per frontend
or backend connection. A statement is handled atomically: one unsupported value
or a limit violation makes the whole statement fall back, and a backend error
commits none of its assignments. Replay failures stop the pending client query
and retire the backend instead of executing with incorrect state. Resets,
COM_CHANGE_USER, reconnects, and disconnects clear the appropriate state.

Five counters in stats_mysql_global and Prometheus report tracked assignments,
replay commands and failures, and unsupported/limit fallbacks. Internal-session
diagnostics expose only counts, stored bytes, and a keyed aggregate fingerprint;
variable names and values are deliberately not disclosed. See
doc/mysql-user-variable-tracking.md for the complete syntax and lifecycle
contract. (#6043)

More complete GTID knowledge for causal reads

min_gtid routing depends on ProxySQL knowing which endpoints have executed a
transaction. The binlog reader remains the primary active source of that
knowledge, but it can leave a visibility gap when the same server is represented
in more than one hostgroup—for example, a write reaches an endpoint through a
writer hostgroup while a later causal read evaluates that endpoint through a
reader hostgroup.

With mysql-update_gtid_from_ok=true, ProxySQL also records a GTID that is
already present in a successful backend OK packet. The state is attached to the
hostname/port endpoint and is therefore visible across its hostgroup entries.
An OK packet without a GTID changes nothing, failed statements change nothing,
and an active binlog reader keeps its existing authoritative behavior.

This is useful when the application or server already negotiates GTID session
tracking and the deployment wants the returned transaction identity to inform a
subsequent min_gtid read. It is not a substitute for enabling GTID reporting
at the MySQL session level, and it does not guess based on routing or timing.
(#6035)

Authentication and credential handling

This release closes several edge cases in authentication paths that are both
security-sensitive and difficult to diagnose operationally:

  • Fixed-width native-password and caching-SHA2 comparisons now first prove that
    the client supplied enough allocated bytes. A deliberately short response can
    no longer cause a 20- or 32-byte read beyond its buffer. The validation still
    accepts legitimate native-password responses whose final byte is NUL, avoiding
    intermittent false denials. (#5998)
  • MySQL and PostgreSQL handshake material now uses OpenSSL RAND_bytes. A random
    source failure aborts that handshake cleanly rather than continuing with weak
    or incomplete material. Related timestamp, credential-cleanup, and bounded
    formatting paths were hardened at the same time. (#6104)
  • Monitor credentials now work when
    mysql-default_authentication_plugin=caching_sha2_password. Generated
    CACHING_SHA2_PASSWORD() salts use a delimiter-safe alphabet; explicitly
    supplied salts must be exactly 20 bytes and cannot contain NUL. These checks
    prevent credentials from being accepted and then parsed differently when
    stored in admin-admin_credentials or admin-stats_credentials. (#5990,
    #5993, #5999)
  • Backend connections can use MariaDB's client_ed25519 plugin when ProxySQL has
    the cleartext password needed to authenticate upstream. Frontend ed25519
    policy remains an Innovative-tier capability. (#6033)

Better compatibility and diagnostics

Several changes remove friction with real clients without weakening the Admin
interface:

  • Admin accepts SET @@session.autocommit = ON|OFF and the scoped
    NET_READ_TIMEOUT / NET_WRITE_TIMEOUT assignments sent by current MySQL
    connectors and mysqldump. They are treated as harmless connection setup
    rather than being passed to SQLite and rejected. (#5994, #6079)
  • SELECT CONNECTION_ID() on the SQLite3 server now returns the ProxySQL
    session identifier even when the client negotiated deprecated-EOF behavior.
    (#6076)
  • Fast-forward connections using a Unix-socket backend keep compression enabled
    when the frontend requested it. (#5978)
  • MySQL CLIENT_CONNECT_ATTRS are retained and exposed under
    client.connect_attrs in stats_mysql_processlist.extended_info. Operators
    can correlate a live connection with client-supplied attributes such as
    connector name, program name, or workload metadata; malformed attribute
    blocks are rejected safely. (#6077)
  • Textual true and false values for
    mysql-session_idle_show_processlist are synchronized correctly, so the
    processlist no longer hides or exposes idle sessions because a string was
    interpreted as a numeric boolean. (#6031)

PostgreSQL operational fixes

When ProxySQL executes pg_terminate_backend() on behalf of a kill operation,
it opens a temporary PostgreSQL connection for that request. The connection is
now explicitly closed afterward, preventing repeated termination operations
from leaking backend connections. (#6130)

The release also includes an operator-owned Scheduler sample for synchronizing
approved PostgreSQL login verifiers into pgsql_users. The sample validates its
input, uses a constrained source function and allow-listed role, and protects
the synchronization configuration's file permissions. It is intended as a
controlled starting point for deployments that keep PostgreSQL credentials in
an external source of truth, not as an automatically enabled feature. (#6045)

Shutdown and cache reliability

With --idle-threads, worker and idle threads can reference one another while
leaving their run loops. The old shutdown path could lock the wrong thread's
mutex, dereference a slot that had already become NULL, or allow one thread to
free state while a peer still used it. ProxySQL now signals each idle thread
under its own mutex and uses a registration-counted barrier before any worker or
idle thread destroys itself. If the barrier takes unusually long, ProxySQL logs
progress every ten seconds rather than failing silently. The fix applies to both
MySQL and PostgreSQL thread handlers. (#6087)

Soft-TTL query-cache refresh now has single-flight behavior. When concurrent
clients reach the soft-TTL boundary together, one request atomically claims the
refresh and goes to the backend; the others continue receiving the existing,
still-valid cache entry. This avoids a burst of identical refresh queries while
preserving the purpose of a soft TTL. The shared fix covers both MySQL and
PostgreSQL caches. (#6015)

Portable Linux tarballs and FreeBSD support

The generic Linux tarballs now contain the OpenSSL libraries used at build time.
bin/proxysql is a launcher that selects those packaged libraries before
executing the internal binary, avoiding startup failures when the host has a
different OpenSSL layout. CI extracts and runs the tarballs on AlmaLinux 9,
Debian 12, and Ubuntu 22.04 for both amd64 and arm64 before upload. (#6105)

On FreeBSD, file-descriptor accounting no longer assumes Linux's
/proc/self/fd; the platform-specific implementation uses the native interface
instead. (#6030)

Release commit: 7c91137a465454dfc1a62b56f8c188c1ce59c130

SHA256s:

2c57545d2c6b7c589e4a37721fa377b98e36c1c5f1301e936b3318e80592b487  proxysql-3.0.11-1-almalinux10-clang.x86_64.rpm
bb3e646aa53a8c1e87236965e0fda19a73a75503203eb3919503abb8ca676084  proxysql-3.0.11-1-almalinux10.aarch64.rpm
a0cf18f086b3428d22c00f7ada98fc401ec29473d49dafb6b0e1362157a2f81d  proxysql-3.0.11-1-almalinux10.x86_64.rpm
a79c33801c790039d4f618fbb7344dbe8dd376120048cc5b651eda0c12e55a34  proxysql-3.0.11-1-almalinux9-clang.x86_64.rpm
0c70703fc4d1db0139120b31e5ceb5811957fab2db89f7b3bd12c50e57f63191  proxysql-3.0.11-1-almalinux9.aarch64.rpm
0c9676c922d4ccdb3fac964ad681e0c5d3482a1cf649a39596c080d0a309a0ac  proxysql-3.0.11-1-almalinux9.x86_64.rpm
75bf44746b705a0de96e036d5e55b9c0aa99846bd3f4490443009a42c2e59177  proxysql-3.0.11-1-centos10-clang.x86_64.rpm
1f6865734f447d922978bf95fd925af7ef1e4995f6fd00ee750f99847ef7b3f0  proxysql-3.0.11-1-centos10.aarch64.rpm
e42592f374772846dc24bea1824a996324071f049401c57a22e104c23fe39486  proxysql-3.0.11-1-centos10.x86_64.rpm
97589eb731d3037a341d9e1c29f6893bdb67b66f41e24068cc7edbc46b118e15  proxysql-3.0.11-1-centos9-clang.x86_64.rpm
05ea0f3e6d52c8b681b985821fc63607d30879d6882e4aa5f108847fd5f17fcf  proxysql-3.0.11-1-centos9.aarch64.rpm
41f0d7aebd93cf6a4ba9681074202b8b1495adec4e810beb5480d8ee3a689fff  proxysql-3.0.11-1-centos9.x86_64.rpm
dd9ae0ef924d4056d1c33c28ded773b02e9c9d622e7d960172bce2d1188bee94  proxysql-3.0.11-1-dbg-almalinux10.x86_64.rpm
2acb1485043079fba0359516f35a1c3dcd337f9b54ace8b4c9f4d4c40421db6c  proxysql-3.0.11-1-dbg-almalinux9.x86_64.rpm
27989373979c2e1d750beb8baa339caff7ced9e54b21aa69affb8fd859b9a3d6  proxysql-3.0.11-1-dbg-centos10.x86_64.rpm
f87129efc977ee38fbf981adecbf0e19aec3f39bf0c17de782f3c7b54dce8bca  proxysql-3.0.11-1-dbg-centos9.x86_64.rpm
7f24271ab60dabd80a902046522ed85f3b9de2dec52abd8aea03a73f1c6dd184  proxysql-3.0.11-1-dbg-fedora42.x86_64.rpm
c9ecb70be6038aaf41aa00cee2192ee26fa2ffb1685864e8245320d77e6ac6fd  proxysql-3.0.11-1-dbg-fedora43.x86_64.rpm
a8554e83b6d4f3741e12124b8683d777e8b316565d6a6b1b5a621f99b9bdb717  proxysql-3.0.11-1-dbg-fedora44.x86_64.rpm
c868dc345ce480ae355c1be85fed25ba86ef294213deb2d4f4fbe04480971852  proxysql-3.0.11-1-dbg-opensuse15.x86_64.rpm
82814d5df79bbdf88513832d47145e5c46a27e7fec2013b95b28257a6b97d3a4  proxysql-3.0.11-1-dbg-opensuse16.x86_64.rpm
b340b0f59b2b4c6415aa93c59c5a7e43728a789cebfe37278944b3599a507c39  proxysql-3.0.11-1-fedora42-clang.x86_64.rpm
a12902d12a88ed8ab84bb11357509cce715a7ad45ee982a9394e02cf5717f791  proxysql-3.0.11-1-fedora42.aarch64.rpm
73ad514470e1bdc06aef8a01362455591ccac7d4673941e02c2116edcf36f05c  proxysql-3.0.11-1-fedora42.x86_64.rpm
744e602822eac385312a04e5b2b3167f94dfdc43069abc5a522391ccd698b550  proxysql-3.0.11-1-fedora43-clang.x86_64.rpm
2c944196bb45c7391a51b57e059b22688f6b0f1e348610b941ff535fc2840c12  proxysql-3.0.11-1-fedora43.aarch64.rpm
eee5207b597119bf91730a38e57ee545e66ce450cb265e0afc2b375a37c2bbd1  proxysql-3.0.11-1-fedora43.x86_64.rpm
274a1225d1362e4010ad2b854fd449080d04befad13bcf68d634571102189200  proxysql-3.0.11-1-fedora44-clang.x86_64.rpm
554b29a44c36c1e9a8a4e4a2f2685a0b94cf136d0e82b6ac547450a5871cf6ac  proxysql-3.0.11-1-fedora44.aarch64.rpm
6d5ffe2c5b631373877ee0f340f8d5f1f4beb1f1ccc13a304ff8a79a159a2812  proxysql-3.0.11-1-fedora44.x86_64.rpm
11cd31e601b3f193f0699003588b8eaf2e90b600618cfcadda1234c1236ecd7e  proxysql-3.0.11-1-opensuse15-clang.x86_64.rpm
d8ea428afd53bb029df35452c4eeee3ae3db7b1a0bc17d44d478a3416a8398fe  proxysql-3.0.11-1-opensuse15.aarch64.rpm
4aae093539f25ddf779d5b4bcb77ff521df058ee5e63e86b72e0f6d5028e7b13  proxysql-3.0.11-1-opensuse15.x86_64.rpm
0adbed01a8fc9ae49584bd7eebf66912b78a3312e817714c0429fec4fc3db877  proxysql-3.0.11-1-opensuse16-clang.x86_64.rpm
89e244d7bb116a2814b30e93e5c0e0bc19917389357fb022a7d4401ff6c17f2d  proxysql-3.0.11-1-opensuse16.aarch64.rpm
3246338451d90e979553aa8c6d39c264dd6abee689a15a6d9e924ee87f845fd7  proxysql-3.0.11-1-opensuse16.x86_64.rpm
98c95ade877770949332e33e68fe1f41fbacd233a1ebd2c926a2d1ee4fe3efb8  proxysql-3.0.11-linux-amd64.tar.gz
1b86a9b8660de83c54e4f0960b429abbe770e770e040413f3f133af86aa3bbb3  proxysql-3.0.11-linux-amd64.tar.gz.asc
0a3479cce47498cc722769f3b9585a65b7b80c57ff9a7d5616595e711a645675  proxysql-3.0.11-linux-amd64.tar.gz.sha256
96169cb3be13bc0bce51bfdffbc4cdb81d4188fb0afb6004d0d0a0c2dea3c3ef  proxysql-3.0.11-linux-arm64.tar.gz
c8aa7a202a3ef6eed69821843811a23246100f1cc7971790305b36cc9755aff3  proxysql-3.0.11-linux-arm64.tar.gz.asc
54a265a6b543638322d6d0eff916eeab7cc35d076c97d1495270e828cf14bdf6  proxysql-3.0.11-linux-arm64.tar.gz.sha256
02ee1ed3d01804bd458496aea88cb3b18db7a8cd7396f9d30874fa313c62c015  proxysql-3.0.11.id-hash
64a7962121115ccd2dcec9a9195f526c2a32277f79a546933a1838420890316b  proxysql_3.0.11-dbg-debian12_amd64.deb
5c5c5de17df04e9bd1dc9cfb7a5455d9bfa4b5c3d23484ba4a2b34a7e8fb68b5  proxysql_3.0.11-dbg-debian13_amd64.deb
8c112a107178c7982949cde86cc39033d49fbced54cfcaabd1574ebef517155d  proxysql_3.0.11-dbg-ubuntu22_amd64.deb
61c34bbd9b4876acf8857c91827fe01f2b9b0b09d725660e32168a5b8f500b14  proxysql_3.0.11-dbg-ubuntu24_amd64.deb
240800338dd92ac964b0cc300091fc1a00eaaa746d54987e7a197e1ba004038c  proxysql_3.0.11-debian12-clang_amd64.deb
676620e2b4d9adc0fac77b2c6322152630f448ee75a9cad7ebb55a66678bc4f5  proxysql_3.0.11-debian12_amd64.deb
661ef029b74e60e7347fa0f22699fe7045a63429d00313b4a50253bba0b3d87f  proxysql_3.0.11-debian12_arm64.deb
20ada200cbcdce4f8fbe1a3ba96faeeb11303833178857896fa7f5fef26918ed  proxysql_3.0.11-debian13-clang_amd64.deb
3f7d6df239b3e182781e370e38c67bd9f38efa39f3b08e480deeb5c8658d9030  proxysql_3.0.11-debian13_amd64.deb
de33c50842b3dea2df1ea333c355ab5eaf7e561f482bb657c3c949e106ecd0f0  proxysql_3.0.11-debian13_arm64.deb
7530326c19ad10d2e951bee10c24a237d316a8257d67eb270095428a43365ac9  proxysql_3.0.11-ubuntu22-clang_amd64.deb
f06a27b32fb96e42aa1b7f71bedd39600101b920f6f1e44e9fd5945c92a2b5b0  proxysql_3.0.11-ubuntu22_amd64.deb
ff4c58e39a3ebbe6db34592d8e3c0230697b38eb6f0bb16ff80feaba7e630b9a  proxysql_3.0.11-ubuntu22_arm64.deb
2dddbe8fe3c4835da1fa087e80563044e45f4c24a840cd5e55e265da5a83df73  proxysql_3.0.11-ubuntu24-clang_amd64.deb
cda9e28707c944ef673dac2a37b7d0c96b5d11c8df49daccaf377495c8ea69ff  proxysql_3.0.11-ubuntu24_amd64.deb
1b1ed90cdeafa985b6c4f465b6a553047e12842c522228d4ffa71977e096860d  proxysql_3.0.11-ubuntu24_arm64.deb
Assets 61
Loading