Skip to content

v3.0.12

Latest
Latest

Choose a tag to compare

View all tags
@renecannao renecannao released this 05 Nov 19:16
v3.0.12
e2f317a
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.12 Release Notes

Release date: 2026-11-05

ProxySQL 3.0.12 improves the reliability of applications that use ProxySQL to route database traffic. It fixes cases where a connection failure could cause earlier statements in a batch to run twice, where transaction state could be lost during error recovery, and where malformed client packets could compromise the proxy. The release addresses eight published security advisories.

It also extends causal-read routing to MariaDB, allowing applications to select a replica that has caught up with a required transaction, and adds subnet matching to query rules so operators can apply routing policies to groups of client addresses.

Highlights

  • Safer query retries: a batch is not replayed on another backend after an earlier result has already reached the application, preventing duplicate execution of those statements.
  • MariaDB support for causal reads: routing now understands MariaDB transaction identifiers as well as MySQL GTIDs, helping applications avoid reading a replica before a required write has arrived.
  • Eight security advisories fixed: bounds checks and protocol validation address four high-severity and four medium-severity issues shared by all three release tiers.
  • More reliable PostgreSQL sessions: authentication, transaction recovery, prepared statements, and connection cleanup receive correctness fixes.
  • Subnet-based query rules: client and proxy address conditions can match IPv4 and IPv6 network prefixes rather than requiring a rule for each address.
  • Updated platform support: Ubuntu 26.04 packages are available for both architectures, and the release embeds OpenSSL 3.5.7.

New Features

MariaDB transaction identifiers for causal reads

Applications often write to a primary server and send subsequent reads to replicas. Replication takes time: choosing a replica without checking its progress can return data that predates the application's write. Causal-read routing uses a transaction identifier to select a replica that has reached the required position.

ProxySQL now understands MariaDB's domain-server-sequence identifiers alongside MySQL's UUID:sequence identifiers. For MariaDB, it compares the sequence watermark within the relevant domain. Transaction positions retain their database-specific format in reader updates and statistics. (#6222.)

MariaDB positions can be learned from successful server responses that contain transaction tracking information. When tracking is requested through mysql-default_session_track_gtids=OWN_GTID or by the client, ProxySQL adds MariaDB's last_gtid tracking while preserving other tracked variables. It does not send an extra blocking query to discover the write position. The integration uses binlog reader 2.5.0. (#6275, #6228.)

This routing still depends on correctly configured tracking and replica-progress information. MySQL routing for a tracked single-UUID set uses its highest transaction ID and assumes transactions are applied in commit order; it does not establish complete set containment for out-of-order or multi-UUID replication. (#6461.)

Keep freshness-sensitive queries out of the text-query cache: a cache hit can return an existing TTL-cached result without waiting for the required transaction or replication-lag condition.

Subnet matching in query rules

Routing policies frequently apply to a service network or a group of clients rather than to one IP address. Query rules can now use CIDR network prefixes in client_addr and proxy_addr, avoiding a separate rule for every address in the subnet.

The implementation supports IPv4, IPv6, and normalized IPv4-mapped addresses. Existing literal-address matching continues to work. (#6223, #6259.)

Queued MySQL commands

Some clients send the next command before reading the preceding response. ProxySQL now queues complete commands and executes them in order, including prepared execution and COM_PING. It pauses further input when queued commands or pending output need to be drained. Applications receive responses in the same order as their requests. (#6470, #6511.)

Entering permanent replication forwarding while commands remain queued is rejected by closing that client connection. This prevents already-received commands from being stranded during the transition. (#6579.)

PostgreSQL authentication with stored credentials

Deployments that manage PostgreSQL password verifiers can now use supported SCRAM-SHA-256 verifiers or PostgreSQL md5 secrets in addition to cleartext credentials. This lets credential-management workflows retain the server's stored representation where the authentication path supports it. (#5865.)

The configured authentication policy still applies. The default pgsql-authentication_method=3 requires SCRAM and rejects MD5 credentials. Using an MD5 secret requires policy level 1 or 2 and an MD5 challenge from the backend. SCRAM pass-through requires successful SCRAM authentication from the application and a byte-identical verifier, including its salt, on each backend that user reaches.

Query-rule selection of permanent forwarding

A MySQL query rule can now request a transition to permanent fast-forward mode with the Boolean attribute {"switch_to_fast_forward":true}. This lets routing policy select connections that should subsequently use direct forwarding.

The transition applies to a normal text query using the final selected hostgroup. If the client's protocol state cannot safely be carried into forwarding, the transition is rejected and the client connection is closed. This includes compressed connections, requests that cannot be reconstructed, and connections with another command already queued. Mirror and prepared commands do not consume this action. (#6156, #6440.)

Bug Fixes

MySQL retries, prepared statements, and session state

Prevent replay of partially answered batches. If a backend becomes unavailable after the application has received an earlier result from a multi-statement batch, ProxySQL now fails the unfinished batch rather than sending the entire batch to another backend. Earlier statements therefore cannot run a second time through that retry path. Failures before any result has reached the application can still follow the normal retry policy. (#6554.)

Preserve transaction ownership after errors. Failed prepared execution with autocommit=0 retains the connection's transaction state, so a subsequent ROLLBACK reaches the backend holding that transaction. Prepared-execution packets and bind buffers are also released correctly on local responses, early failures, and retries. (#6482, #6259, #6407.)

Handle session changes as complete statements. Tracking of SET LOCAL assignments and transaction characteristics no longer applies only part of a statement. Unsupported or incomplete assignments follow the backend path without partially changing ProxySQL's tracked state. (#6405, #6441, #6470.)

Return large prepared results correctly. Binary result rows spanning MySQL's packet-size boundary now handle continuation headers and the final empty packet required for exact size multiples. Workers also refresh their heartbeat during large result generation. (#6444, #6511.)

PostgreSQL transactions and prepared statements

Recover transactions without aborting the proxy. Rollback, session-setting changes, and RESET ALL preserve backend-confirmed state. A disagreement between ProxySQL's tracker and the backend no longer aborts the process. Protocol errors inside a transaction retain PostgreSQL's aborted-transaction behavior until recovery completes. (#6161, #6442.)

Keep prepared statements consistent with their session. Prepared-statement identities now account for search_path, the setting that determines which schemas PostgreSQL searches. Changing schemas or encountering a changed result type can therefore trigger the appropriate preparation rather than reusing an incompatible backend statement. Statement deallocation also preserves backend ownership and failed-transaction behavior. (#6401, #6112.)

Preserve result formats and cursor ownership. Mixed per-column result formats are forwarded correctly. Cursors declared with WITH HOLD, which remain open after commit, keep their backend connection rather than allowing another pooled session to inherit that state. Cursor cleanup releases the connection when appropriate. (#6259, #6401.)

Report connection and protocol failures safely. A disconnect during a result or an invalid backend reply retires the affected connection and returns an error instead of aborting ProxySQL. PostgreSQL Admin responses use the correct wire framing, and unsupported Admin/STATS request batches leave the connection synchronized for later queries. (#6111, #6204, #6373.)

GTID routing and connection reuse

Replica progress must describe the current connection, not an earlier reader session. Reader reconnects now clear stale transaction knowledge; malformed or ambiguous positions and oversized updates no longer leave an old position available for routing. Writer fallback is decided before the query is attached to its backend. (#6444, #6461, #6470.)

Backend connection-age limits are enforced for pooled and busy connections at the appropriate release or disconnect boundary. PostgreSQL monitoring resumes correctly after being disabled and re-enabled at runtime, and backend connection attempts can try the resolved addresses of a hostname. (#6198, #6259, #6390, #6442.)

Memory safety, TLS, and shutdown

Query-cache construction now checks sizes and allocation results, including multi-result responses that could previously exceed their allocated buffer. Packet and authentication bounds checks are covered in the security-advisory section below. (#6310.)

TLS writes correctly account for plaintext already consumed when encrypted output needs a retry, preventing duplicated bytes after a temporary socket interruption. Backend quit commands use the TLS layer, and Aurora monitoring clears stale OpenSSL errors before subsequent handshakes. (#6259, #6132, #6199.)

A listener startup failure releases waiting workers before joining threads, avoiding an indefinitely hung shutdown. Certificate generation and shutdown paths also release temporary certificate authorities, retained snapshots, and Scheduler rows. (#6461, #6488, #6532.)

Administration and observability

Query-digest updates and statistics dumps now preserve counts, timings, and row statistics during concurrent activity. Memory-buffer gauges update the correct Prometheus metrics and refresh at the configured memory-metrics interval. (#6165, #6440, #6155, #6153.)

Concurrent configuration refreshes no longer produce duplicate-key failures in runtime MySQL-variable projection. Cluster metric collection avoids an opposing lock order, and REST resources are registered before their listener accepts requests. (#6173, #6440, #6532.)

Operators can inspect the embedded OpenSSL version through OpenSSL_Version and OpenSSL_Version_Num in stats_mysql_global, and inspect startup TLS cipher information through the Admin ssl_ciphers table. The Group Replication bootstrap importer also selects accounts deterministically while preserving credential bytes. (#6122, #6461, #6470.)

Security Fixes

The release addresses eight published security advisories: four high severity and four medium severity. All eight affect shared code and are fixed in 3.0.12, 3.1.12, and 4.0.12.

Severity Advisory Correction
High GHSA-p5xc-69qx-m4q5 Bounds-check MySQL prepared-statement parameter type descriptors.
High GHSA-r23x-jg5r-jmcc Validate remaining packet bytes and temporal lengths while decoding prepared-statement values.
High GHSA-crwq-rcqp-v8jr Enforce LOCAL INFILE policy in the backend connector, including prepared execution.
High GHSA-33xp-q4g3-r79r Bound PostgreSQL frontend message sizes before allocation, including before authentication.
Medium GHSA-85h9-mr8r-6j4j Reject truncated COM_STMT_RESET packets before reading their statement ID.
Medium GHSA-5cf5-7gfq-rrj6 Reject truncated COM_STMT_EXECUTE packets before reading their statement ID.
Medium GHSA-x23w-3v26-vgvj Bound MySQL length-encoded integer decoding by the available bytes, including handshake input.
Medium GHSA-qg2m-q3ch-cg9v Reassemble compressed-protocol inner headers split across frames without aborting the process.

Upgrade Notes

  • Review complex regular-expression rules. Recursive matching now has a limit based on the worker's stack. A rule that reaches a match or recursion limit is skipped, including a negated rule. Applications should not depend on an unbounded match succeeding. (#6470, #6440.)
  • Review PostgreSQL digest-based rules. The default tokenizer now excludes the protocol's terminating byte, allowing trailing semicolons and whitespace to normalize consistently. Existing digest hashes and match_digest expressions that expect a final semicolon may need adjustment. (#6442.)
  • Check stored PostgreSQL credential compatibility before enabling it. The authentication policy and backend credentials must satisfy the requirements in New Features; storing a verifier does not bypass those requirements.
  • Upgrade ProxySQL to receive its OpenSSL updates. OpenSSL is now embedded in the executable. Updating the host's OpenSSL package alone does not update ProxySQL's copy. This change does not establish FIPS compliance.
  • Replace retired openSUSE Leap 15 package targets. Ubuntu 26.04 packages are added for amd64 and arm64; openSUSE Leap 15 targets are removed.

Dependencies, Build & Packaging

The release embeds OpenSSL 3.5.7 and updates RE2, Abseil, and ParserSQL. Eligible backend CA bundles are cached per thread, reducing repeated trust-store setup while retaining cleanup at thread exit. (#6122, #6218, #6121, #6441.)

Source builds no longer require Git LFS for vendored archives. They can also reuse exact, verified OpenSSL dependency artifacts: DEPS_MODE=auto uses an available artifact and otherwise builds from source, source forces compilation, and prebuilt requires a matching artifact. Integrity failures remain errors. (#6213, #6520, #6544.)

Compatibility fixes retain support for the release's older toolchains, including AlmaLinux 8 linking and the Stable bootstrap importer with Clang 14. (#6583, #6586.)

Packages

The release provides 56 DEB/RPM packages and generic Linux tarballs for amd64 and arm64. Native packages include standard, Clang, and debug variants on amd64, and standard builds on arm64. Every native package passed its clean-install check, and both tarballs passed runtime checks in the release build matrix.

The native DEB/RPM packages are signed. Signing primary fingerprint: 653F85BB38256DF8A96206C3E8CA2E8D8217C97E.

Release commit: e2f317a.

Hashes

b6faabbaa9bb2bce2a76ea82eb2cd4a94827c48471fd333db9dee9e159833f73  proxysql-3.0.12-1-almalinux10-clang.x86_64.rpm
82ea0749f6943afa140877fa2e9506f2e597918b5c6c605ea9fb3824980d45c8  proxysql-3.0.12-1-almalinux10.aarch64.rpm
c013c9a1c18c1745a3683155ab9f8548faf9340d3af01cf0bacc843ed539cf68  proxysql-3.0.12-1-almalinux10.x86_64.rpm
0e80be936e7102040864e59990440bb2fff3dad135e4f94d7e6ad42429c3a43f  proxysql-3.0.12-1-almalinux8-clang.x86_64.rpm
8fc708d2a0cf1c2e11634d8f4178a125a2bc8879857436fc6303b55a043bcbad  proxysql-3.0.12-1-almalinux8.aarch64.rpm
ef9510da2ccb7688b67fa553b741ddfacd8ba579935ed6ecf50215b6f3b9683c  proxysql-3.0.12-1-almalinux8.x86_64.rpm
d9d7016e63e15e1813040ed04798f3da7535ed13125d47ce0d7b5303c37b4d42  proxysql-3.0.12-1-almalinux9-clang.x86_64.rpm
535f62598d85648c3fa9f20e96e7d51de728b647d1fe8f0236baa314df4a3d4a  proxysql-3.0.12-1-almalinux9.aarch64.rpm
496bfceef4da785d53e00397227f7b1a47c22f479c0a01d68cb6cfd12eae8a23  proxysql-3.0.12-1-almalinux9.x86_64.rpm
f982b5e70c3e000758524161e4e8d84bd8137f7a6d0a5b285d420220cd8ee1f0  proxysql-3.0.12-1-centos10-clang.x86_64.rpm
45397b58d110cd3d6c4b0e0125f11018b07231b7906288535939049ab62058fb  proxysql-3.0.12-1-centos10.aarch64.rpm
163069b0ce85de56977c94640116587f000273d27e2e5dc62d76bc4793389c50  proxysql-3.0.12-1-centos10.x86_64.rpm
0241ee471cd08343380d994fa14d4884ce03606aed70c8e2c778327d4bcb0957  proxysql-3.0.12-1-centos9-clang.x86_64.rpm
95d78a0c03faf9beec9ae39bde23a2c0032b9d452dccc0e0e8f5a4347c16b814  proxysql-3.0.12-1-centos9.aarch64.rpm
dda32556766d8547b2d2bd3929ba726bf835a3878f783f3c2b5bfaff550f75ff  proxysql-3.0.12-1-centos9.x86_64.rpm
e8c327f40de7e826f8188e47a019048a60272692131d61f20adb6fe10372e322  proxysql-3.0.12-1-dbg-almalinux10.x86_64.rpm
fa4add4815355d375e675d7fdc65699204db31fc0d0ea5854dc06c9151ef1149  proxysql-3.0.12-1-dbg-almalinux8.x86_64.rpm
be7b6757255a635037be839269e4dd830c57f441b7115285921c74a79283c2ee  proxysql-3.0.12-1-dbg-almalinux9.x86_64.rpm
9af75e81241b5b6334ad08150724e5024254cde62415c6e2f36a545baaf2ec60  proxysql-3.0.12-1-dbg-centos10.x86_64.rpm
9045d0586bcdd34a12401db82d4793c3f5b990615ceb60cf1354beb080f23e37  proxysql-3.0.12-1-dbg-centos9.x86_64.rpm
287e6dda4e891b795ddaa267bd14dc058b0b1ea80d5490eadd995f0f3d7263c0  proxysql-3.0.12-1-dbg-fedora42.x86_64.rpm
c3607c157ae7bcc0df694c91c2a55a5468a339b2c37a972d11ca44c1a710dd15  proxysql-3.0.12-1-dbg-fedora43.x86_64.rpm
429dd0caf0eb0455ec0dfefbfea6d04bc56f221c369a0d4adc4dc62c914b96d0  proxysql-3.0.12-1-dbg-fedora44.x86_64.rpm
f53afce28b938f650c97e95f0efc67e30380be3beb1e1a36a69dd77f5f1ba02f  proxysql-3.0.12-1-dbg-opensuse16.x86_64.rpm
567f79e927c077344163e2dbb96477efafe1f0c118cd58c99d2c656c5adbcc4c  proxysql-3.0.12-1-fedora42-clang.x86_64.rpm
fa94bf5e8619e5155e9314ed41b152e552a185b2b4e7939258cc66d25024a78a  proxysql-3.0.12-1-fedora42.aarch64.rpm
ab6950d20f6959af21284ce07031d8c80d94d24e58f2fb47f9edbbc9b556b310  proxysql-3.0.12-1-fedora42.x86_64.rpm
699f4d194269b5bee5f51f8887dcab4c9bddd3fabaca64842605ac3e403fafee  proxysql-3.0.12-1-fedora43-clang.x86_64.rpm
6ffc2b9379f7e63b6c65905dc473c12539dad8149b301d69b403e8c77265a40a  proxysql-3.0.12-1-fedora43.aarch64.rpm
2bac60cd1725f2a4588888dfe8f5fe95887765abb058ee80fe3749dbec004373  proxysql-3.0.12-1-fedora43.x86_64.rpm
31905b028a3112c8b6bb9bda8107129e17af185bec804ea90c16a89d685bf701  proxysql-3.0.12-1-fedora44-clang.x86_64.rpm
73ef657e5398c2d70f612b3cfdae0d4f0d2ed3d4f5c1208640add2f84c312e0e  proxysql-3.0.12-1-fedora44.aarch64.rpm
8a39cc162b7745913bfb8ff595985b626439b166ec77e8900ca5a7af3186f643  proxysql-3.0.12-1-fedora44.x86_64.rpm
d6ae4aa77bf2264240cafd5857c640614a082d1bcd0f7aa2433f08109a0e70b9  proxysql-3.0.12-1-opensuse16-clang.x86_64.rpm
20ccbf2d01fe82a294921c465c523032d0f86bc55c6f2d02782f759b70e58b60  proxysql-3.0.12-1-opensuse16.aarch64.rpm
796c58c9632eb4c36b2fdf68942133c2e60a61201010fe2b37a12e95faccb1d6  proxysql-3.0.12-1-opensuse16.x86_64.rpm
8ded0d5cd9480b3b97e4dedebd91733efb15d3fcded9d2e1db1bc0f93c5940f9  proxysql-3.0.12-linux-amd64.tar.gz
ff0894afc458f1e559b2e9d4719e47f43c2c1271872fd0c9c5dbb73f8b4d00c6  proxysql-3.0.12-linux-amd64.tar.gz.sha256
896d31dd9d6b76fc36854c13d1fb59e0b5b8c8be75e7c513dbe63e1024e2d6d0  proxysql-3.0.12-linux-arm64.tar.gz
9b47afee9a2ac8fcff568130cc5f4db76cab3a5bf4087dcfd1fedc37f3b22c5f  proxysql-3.0.12-linux-arm64.tar.gz.sha256
d3431ad70d21435932a5a81eea95072498f5003bec1612d54743817ee9498cca  proxysql-3.0.12.id-hash
42b879460744152786664ffcb61c71592fdc908671a151107c5eb3fd42af0fc6  proxysql_3.0.12-dbg-debian12_amd64.deb
61469b130f3b3e2ef96b3d71129b2ad04bdbafbb1dfffd567dde276031a4b33f  proxysql_3.0.12-dbg-debian13_amd64.deb
f934cb53f765913eb0d3c426708ccf73528657c0895ed068983943376302a0ec  proxysql_3.0.12-dbg-ubuntu22_amd64.deb
c3fa109e5f3077eec20e227dfb72e7c9dc5b00b7dbcd9e4003b627255078ec16  proxysql_3.0.12-dbg-ubuntu24_amd64.deb
f16321ad5e1330e25ef6b1206a7c1961cf090555c43b5277e3ddfde7ece7376b  proxysql_3.0.12-dbg-ubuntu26_amd64.deb
a82a7a40cb26bccf71f484e629abe98541c58be86259931bdedd2e5ad80fb9af  proxysql_3.0.12-debian12-clang_amd64.deb
68921d6f8f80c4b94673aaa5a0639f35e9338fe22b9614d87e27c3c28a16edb1  proxysql_3.0.12-debian12_amd64.deb
c52f3012c35cb3e546aae3439a94215b7b0360b662bbb8b47edb5357ad2257bd  proxysql_3.0.12-debian12_arm64.deb
30c305b0936641f0c96ea93c79a1710cf3c90310ee180de1f6fdc16e19ef1266  proxysql_3.0.12-debian13-clang_amd64.deb
fac360df33f597f8da60f6ef14e50db4abc2a266ea9f783ef3de0ebf9f2f1bec  proxysql_3.0.12-debian13_amd64.deb
deecd9fdd6b5660f229b8079447b83fcf742f73c68fcd05cf4d32e70023c265a  proxysql_3.0.12-debian13_arm64.deb
a723cf2653ade99dcf3e51e39421840f3d1ec0cbd401c313d90484a9338beada  proxysql_3.0.12-ubuntu22-clang_amd64.deb
78950e02a37bdfdfed3e46cce4e2b86b303529772173cd2653284be98a6752d7  proxysql_3.0.12-ubuntu22_amd64.deb
3310273e2b7ef4b3a7c30e5610b543af4d5dce8a3aafc89f689f377f642fd9af  proxysql_3.0.12-ubuntu22_arm64.deb
e9d917137ce22c482c6b3bd3e6cfdf4aecf813f015e02fd37233a8528d90351c  proxysql_3.0.12-ubuntu24-clang_amd64.deb
fa59c370f4deb76b67b6607259ede512307644f63a30f608bbe8e5e198460729  proxysql_3.0.12-ubuntu24_amd64.deb
cd7dc2b1a5198efc8373347023bb202a0c9f4456cc900666a1a8fe7a3f2d5522  proxysql_3.0.12-ubuntu24_arm64.deb
a9f16b11dff2a4074c979a0dfd2f608ec047169f38e6fc5619749e97dae551f0  proxysql_3.0.12-ubuntu26-clang_amd64.deb
d3343ffd10a9636e124713ea8e850ebad47ca7059dbfaf68c9605e82e44052b6  proxysql_3.0.12-ubuntu26_amd64.deb
163a056363385af3c559d5db26989113d3365353ea27771a10b45bccbe463933  proxysql_3.0.12-ubuntu26_arm64.deb
Assets 64
Loading