ProxySQL 3.1.12 Release Notes

Release date: 2026-11-05

ProxySQL 3.1.12 extends the Innovative tier for applications that need more than simple request-and-response database traffic. PostgreSQL applications can fetch prepared results in batches and receive background notifications through the proxy. Operators can reserve spare servers within a hostgroup, see when connection pools are under pressure, and give MySQL listeners different advertised version strings.

The release also introduces experimental prepared-result caching for a restricted set of MySQL and PostgreSQL SELECT operations. It includes all Stable 3.0.12 reliability and security fixes, including protection against replaying partially answered batches and fixes for eight published security advisories.

Highlights

• More PostgreSQL application patterns: native backend execution supports named portals for fetching results in batches and LISTEN/NOTIFY for asynchronous notifications.
• Prepared-result caching: existing cache rules can select eligible prepared SELECTs in both protocols, with explicit limits and no automatic invalidation after writes.
• Fairer access to busy pools: released backend capacity is offered to older waiting sessions before the releasing session starts its next buffered command.
• Visible pool pressure: MySQL and PostgreSQL hostgroup statistics expose acquisitions, waits, accumulated wait time, and current waiters.
• Spare servers within a hostgroup: lower-weight servers can remain in reserve until the configured primary-availability condition allows them to participate.
• Per-listener MySQL identities: different listeners can advertise different versions, with a consistent identity for each accepted connection.
• Shared maintenance and security fixes: the complete Stable 3.0.12 fixes are included, together with embedded OpenSSL 3.5.7 and updated platform support.

New Features

Native PostgreSQL backend execution

PostgreSQL applications may need to keep an execution open while fetching part of its results, or keep a connection subscribed to database notifications. ProxySQL 3.1.12 adds native backend protocol support for these patterns, alongside ordinary queries, prepared execution, authentication, TLS, and cancellation. ProxySQL manages the backend exchange directly; the new portal and notification capabilities use this native path. (#5882, #6112.)

Native mode is enabled by default for new TCP backend connections through pgsql-use_native_backend_protocol=true. Unix-domain backend connections continue to use the PostgreSQL client library, libpq. Operators can select that library path for new connections by setting the variable to false and loading PostgreSQL variables to runtime. Existing connections retain their original implementation until replaced.

The native path supports cleartext, MD5, SCRAM-SHA-256, and SCRAM-SHA-256-PLUS channel binding over TLS, subject to the configured authentication policy and available credentials. Unsupported authentication reports an error rather than silently trying another backend implementation. Stored SCRAM verifier pass-through requires a successful frontend SCRAM exchange and the same verifier, including its salt, on each destination backend. The default pgsql-authentication_method=3 requires SCRAM; an MD5 secret requires policy level 1 or 2 and an MD5 backend challenge. (#5865, #6112.)

Configured backend trust, client certificates, CRLs, and TLS version bounds apply. With use_ssl=1, the certificate chain is verified when a CA is configured; hostname verification is not requested. Pool reuse preserves the established TLS transport, and connections with incomplete results or fatal protocol failures are retired instead of being handed to another session. (#5882, #6112.)

Fetch PostgreSQL results in batches with named portals

Applications processing a large result may want to request a limited number of rows at a time rather than receive the whole result at once. A PostgreSQL portal holds a prepared execution and its position in the result. Named portals now support creating, describing, executing, suspending, resuming, and closing that execution through ProxySQL. (#5882, #6112.)

A bounded Execute can return part of the result and suspend the portal until the application requests more rows. ProxySQL keeps the owning backend connection attached for the portal's lifetime, so later fetches continue the same execution. Portal state is cleared at the relevant transaction or connection boundary. General migration of an existing portal between hostgroups is not supported.

Receive PostgreSQL background notifications

Applications use LISTEN and NOTIFY to receive database events without repeatedly issuing a query. Native PostgreSQL sessions can now retain a subscription and receive asynchronous notifications while the frontend is idle. ProxySQL keeps that session's backend connection attached so notifications reach the subscribing application. (#6112, #6442.)

UNLISTEN * and DISCARD ALL release the subscription-related connection pin; an individual UNLISTEN does not. Detection handles comments and LISTEN appearing after another statement, but cannot discover a subscription hidden inside a function or DO block. This capability requires the native TCP backend path; LISTEN is refused on a libpq backend connection.

PostgreSQL extended-query batches

Prepared PostgreSQL operations arrive as a sequence of messages to prepare, bind, execute, and synchronize work. Eligible messages can now be sent to the backend in batches while preserving application-visible response order and the client's Sync boundary. Query-rule timeouts still apply to each Execute, and an error skips the remaining messages through Sync. This allows applications to retain their extended-query batching pattern through the proxy without changing transaction boundaries. (#6401.)

Experimental caching of prepared SELECT results

Applications that repeatedly execute the same prepared read with the same parameters can now reuse an eligible cached result. Both protocol prototypes use the existing cache budgets, cache_ttl rules, TTLs, soft refresh, and empty-result policy. No separate enabling variable is added; existing rules may select newly eligible prepared execution. Exchanges outside the supported subset execute normally on the backend. (#6194.)

For MySQL, eligible prepared SELECT executions can cache binary result rows. Parameters, effective parameter types, prepared SQL, connection identity, destination hostgroup, and tracked session settings distinguish entries. Cursor execution, pending LongData, transactions, autocommit-off sessions, hostgroup locks, and GTID- or lag-constrained requests bypass caching. Only a complete, successful single result set is stored.

For PostgreSQL, preparation must have completed in an earlier cycle. The supported execution is one unnamed-portal Bind, an optional portal Describe, an Execute without a row limit, and an explicit Sync. SQL, parameter type identifiers, parameter bytes and formats, result formats, routing identity, and tracked/startup settings distinguish entries. Preparing and executing in the same cycle, named portals, transactions, pinned/session-dependent exchanges, locking reads, errors, notices, and partially streamed results bypass caching. Mixed per-column result formats are supported and participate in the cache identity.

These are bounded experimental TTL caches, not a general transaction cache. Writes do not invalidate entries. The operator's rule must identify reads that are safe to reuse: classifying a statement as SELECT does not prove that it has no volatile functions, hidden side effects, or untracked session dependencies. Flush affected entries after changes to permissions, backend defaults, schema semantics, or initialization policy. The MySQL prepared-cache guide explains its configuration and eligibility boundaries.

Backend-pool fairness and pressure metrics

When a hostgroup reaches its connection limit, an active client should not repeatedly reclaim released capacity while older requests wait. MySQL and PostgreSQL pool scheduling now offers released capacity to existing waiters before the releasing session begins its next buffered command. Waiting sessions retain deadline handling, disconnect detection, recovery, and cleanup while capacity is unavailable. (#6195, #6570.)

Operators can inspect stats_mysql_hostgroup_connection_pool and stats_pgsql_hostgroup_connection_pool to distinguish connection demand from available capacity. The tables expose acquisitions_total, waits_total, wait_time_us_total, and live waiters; _reset variants support interval inspection. Prometheus exposes corresponding acquisitions, waits, wait seconds, and waiter metrics by protocol and hostgroup. Retrying one logical wait does not create another wait count, and an Admin reset read does not reset Prometheus cumulative counters. (#6150.)

Spare servers within a hostgroup

Operators can keep lower-weight servers in reserve without creating another hostgroup. Set hostgroup_settings.backup_weight_threshold to a positive value T: servers with weight >= T are primaries, while servers with 0 < weight < T are backups. Weight 0 remains unselectable. A threshold of 0, the default, retains ordinary weighted selection. (#6219.)

backup_availability determines when the backup set becomes eligible:

This distinction lets operators choose whether backups should respond to normal eligibility, server status, or connection capacity. Server-selection checks remain in effect, including after emergency unshunning, and per-protocol Prometheus counters report backup selections. The policy selects servers within the same hostgroup; it does not route to a different hostgroup.

Per-listener MySQL version advertising

A deployment serving different client populations may need different advertised MySQL versions. mysql-server_version_by_interface maps exact textual listener identifiers to version strings, for example:

{
  "0.0.0.0:6033": "8.0.37-primary",
  "/tmp/proxysql.sock": "5.7.44-legacy"
}

An unmapped listener uses mysql-server_version. Each connection chooses its identity when accepted and retains it for the handshake and locally generated version responses. The catalog follows ordinary MySQL-variable persistence and Cluster synchronization. Configure listening addresses separately through mysql-interfaces; the version catalog does not reconfigure or synchronize those interfaces. Its default empty catalog preserves the global advertised version. (#6151.)

Track supported mixed MySQL SET assignments

Applications sometimes set user variables and session settings in one statement. With the existing opt-in mysql-user_variable_tracking=1 and either mysql-set_parser_algorithm=3 or mysql-query_processor_parser=1, supported literal user-variable assignments can now share a text SET with supported session assignments. ProxySQL records the complete desired state atomically and can acknowledge it without first acquiring a backend, then synchronizes the selected connection before the next real query. (#6503.)

An autocommit change that commits an active transaction still runs immediately on that transaction's backend. If it fails, staged changes are discarded. Unsupported expressions, incomplete assignments, and unsafe contexts follow the documented backend path. Tracking remains limited to 128 variables and 64 KiB of replay state; the opt-in default and parser prerequisites are unchanged. See the tracking extension.

Shared features from Stable

MariaDB causal-read routing can select a replica that has reached a required write position, helping applications avoid reads that arrive before their preceding writes. It understands MariaDB domain-server-sequence identifiers alongside MySQL GTIDs; selection uses the sequence watermark in the relevant domain and requires correctly configured tracking and replica-progress information. CIDR prefixes in client_addr and proxy_addr query-rule conditions also let operators apply policies to IPv4 or IPv6 subnets instead of maintaining one rule per address. (#6222, #6223.)

MySQL clients can send queued commands and receive their responses in request order. PostgreSQL deployments can use supported stored SCRAM verifiers or MD5 secrets subject to the authentication requirements above. These shared additions are described in the Stable 3.0.12 New Features. (#6470, #5865.)

Bug Fixes

PostgreSQL execution and connection state

Backend disconnects and invalid reply sequences retire the affected connection and report an error rather than terminating ProxySQL. Cancellation uses the saved backend identity and actual connected peer, avoiding another DNS lookup that could select a different endpoint. Processlist and connection diagnostics correctly report backend process IDs, TLS, native mode, and transaction state. (#6112, #6442.)

Extended-query retries require evidence that completed or ambiguous work will not be replayed. Protocol errors preserve PostgreSQL's failed-transaction behavior, and session resets wait for protocol completion before a backend can be reused. Prepared-statement identities account for search_path, and mixed per-column Bind result formats are forwarded correctly. (#6401, #6259, #6442.)

MySQL parsing and session tracking

Parser mode now derives digest text and first-comment metadata from the dialect tokenizer while retaining ParserSQL classification and SET analysis. Commands unknown to ParserSQL can use legacy classification, preserving intercepted commands such as KILL. Unsupported assignments do not partially update tracked session state. (#6460, #6441, #6511.)

Shared Stable maintenance fixes

The Stable 3.0.12 notes describe the full shared maintenance set. It includes preventing replay after part of a multi-statement response has reached the client; retaining transaction ownership after prepared-execution errors; correct large binary-result framing; PostgreSQL transaction, authentication, monitoring and cursor cleanup; and memory-safety, TLS and shutdown corrections. (#6554, #6482, #6259, #6442, #6532.)

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.

Upgrade Notes

• Plan the PostgreSQL backend transition. Native execution defaults to true for new TCP backend connections. Setting pgsql-use_native_backend_protocol=false and loading PostgreSQL variables selects libpq for new connections; it does not convert existing pooled connections. Replace existing connections when a consistent pool implementation is required.
• Finish portal work before disabling native mode. Portal operations also consult the current worker setting and can be refused after disabling it, even if their existing backend connection remains native. New LISTEN statements consult the setting too. Unix-domain backend connections remain on libpq, so they do not provide these native-only capabilities.
• Review existing cache rules. Eligible prepared SELECTs may now use their existing cache_ttl policy. Choose safe TTLs and reusable results; writes do not invalidate entries. This remains an experimental, restricted cache path.
• Check PostgreSQL authentication and TLS requirements. Stored verifiers do not bypass authentication policy or backend credential matching. A configured CA enables native backend certificate-chain verification, not hostname verification.
• Review regex and digest compatibility. Regular-expression recursion limits can cause complex rules to be skipped rather than exhaust a worker's stack. PostgreSQL tokenizer corrections can change digest hashes and match_digest patterns that expect a trailing semicolon. Review those rules before upgrading. (#6470, #6442.)
• Apply the shared Stable upgrade guidance. Review regex resource limits, stored PostgreSQL credentials, embedded OpenSSL updates, and retired package targets in the Stable upgrade notes.

Dependencies, Build & Packaging

The release embeds OpenSSL 3.5.7, updates RE2 to 2025-11-05 with vendored Abseil 20260107.0, and uses ParserSQL 1.1.1. Updating the host OpenSSL package does not update ProxySQL's embedded copy; this change does not establish FIPS compliance. (#6122, #6121, #6441.)

Source builds no longer require Git LFS for vendored archives. Verified OpenSSL dependency reuse supports DEPS_MODE=auto, source, and prebuilt; integrity failures remain errors. Ubuntu 26.04 packages are available for amd64 and arm64, while openSUSE Leap 15 targets are removed. AlmaLinux 8 linking and Clang 14 bootstrap compatibility fixes retain support for the selected older toolchains. (#6213, #6520, #6544, #6518, #6181, #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

af20879e096f3a54e18578267d8e2056607c0525b40dde7c295f2d8313067142  proxysql-3.1.12-1-almalinux10-clang.x86_64.rpm
c21c6cc8f99739bb267fe985168e3b2ec0c7add70b0ceba5c459836d90ad38d4  proxysql-3.1.12-1-almalinux10.aarch64.rpm
b9550507de15cf83b6960dc8b93c9f8ecd33ba372270fcbeb243c1a277c9884d  proxysql-3.1.12-1-almalinux10.x86_64.rpm
f003a3f4e21b05e34b18b396d290f2f38e218c0bf86b19b36dd9ae3a9281ceaf  proxysql-3.1.12-1-almalinux8-clang.x86_64.rpm
c1e52c90d97a6b29e95bc0434fdc45b60f1b191a5ca6131219bf8ee858533aaf  proxysql-3.1.12-1-almalinux8.aarch64.rpm
cd9701bcd7e941bb324f113bf0f13cdbb33cfaa4d361c572ff14c46854445aba  proxysql-3.1.12-1-almalinux8.x86_64.rpm
0a1e5fca6b583a751f3e926344dba714979ef89bc1e364d6d3d13c2ab1ef95e6  proxysql-3.1.12-1-almalinux9-clang.x86_64.rpm
e10c8af2a868ad1d15c9d36fa679e5827e706857421ba861b131ee14e8464af6  proxysql-3.1.12-1-almalinux9.aarch64.rpm
26f996ef21608fd4840a3c149f8d2b86c3c0cf3e52df9f73dd7f7d46c3298db6  proxysql-3.1.12-1-almalinux9.x86_64.rpm
9af3bef37103e99fa0d46abc3be6a4631384300ec3befd903b9f20cdacf68cae  proxysql-3.1.12-1-centos10-clang.x86_64.rpm
b82c8109799b3c3861871c6a31472e6a50874f18e2d227154dcf36c032201acc  proxysql-3.1.12-1-centos10.aarch64.rpm
420ff18ee0a3bc6b5adced9b77fe6ef9e48fa107f396187a2c385178f2ea1053  proxysql-3.1.12-1-centos10.x86_64.rpm
0d9e1a0c3829889ae6ac739ce6ee703107441799372f45b5c5dfdc8a35fcc3e7  proxysql-3.1.12-1-centos9-clang.x86_64.rpm
f1ec45f7dc6e3c64cb989483919c4e4f20eb8b051bd704a95ecefbcc1db0488c  proxysql-3.1.12-1-centos9.aarch64.rpm
f2fda0ad4d64755e0369fb0cdd8f42d43ffdb4cdb8988be801efa3ea1b4c6637  proxysql-3.1.12-1-centos9.x86_64.rpm
df79129f382b698d081d46c32332c95b1939df228581c511a4d0901142a9adef  proxysql-3.1.12-1-dbg-almalinux10.x86_64.rpm
12066706b6a424d12dba05b2002792ed6e178b397468a360377a6ba5ad3c3b13  proxysql-3.1.12-1-dbg-almalinux8.x86_64.rpm
4d11028400acba8bab84944de7496235ae11a7e7c74b1d9c6ace3ede27125d34  proxysql-3.1.12-1-dbg-almalinux9.x86_64.rpm
3abddd383f59c649cb52109d960e3be6b171c7438baff0fa94a7a6d7d4340338  proxysql-3.1.12-1-dbg-centos10.x86_64.rpm
c3d695761d519ca2b9778d8d04d1612d1dba35b229f9fb143fd65901abdbb652  proxysql-3.1.12-1-dbg-centos9.x86_64.rpm
b93ca6bbb906bed2158cea06910cacc3846bf6327bb572d238ec70ab44d96dd1  proxysql-3.1.12-1-dbg-fedora42.x86_64.rpm
99143c54457c57ec4527cd860087ff959246c90f1b399eebcfa8842d45cbfb82  proxysql-3.1.12-1-dbg-fedora43.x86_64.rpm
1154f40071ac3a8ba238e10944195312db4e99a734c403018c0325dfe6820996  proxysql-3.1.12-1-dbg-fedora44.x86_64.rpm
302e8c5f3681214e0b466e81792cc0bb096c762f8fa31d4dc82702af85ba6c7b  proxysql-3.1.12-1-dbg-opensuse16.x86_64.rpm
d9febe3f1675439e486f6fc9121009c48dcc1ccbb091640350ade2a4f1b617c6  proxysql-3.1.12-1-fedora42-clang.x86_64.rpm
d357cd7f29f9b38e21eb5f5c1eabc183cce906e67a7671124e130e4e059b091d  proxysql-3.1.12-1-fedora42.aarch64.rpm
9e12e60b3f9936ad885f64132aba0681ccff379acd63a2a4a596af8f7b39945c  proxysql-3.1.12-1-fedora42.x86_64.rpm
8dbe1cc430a6e71f4154051b0653d4f18e846584b4c6ec754f902161a2493d10  proxysql-3.1.12-1-fedora43-clang.x86_64.rpm
036d76a0a07120f9a2cf431191286e5e85b28585e6964ca69b77f4b1a861bce8  proxysql-3.1.12-1-fedora43.aarch64.rpm
a55940d069ce2110d4f0935a866ae4281252599ef8bbfc2a5b5c20007cd683e3  proxysql-3.1.12-1-fedora43.x86_64.rpm
05eb18084e2344622a5d77fa4df3f199d28a47f74d79b994a891b59bd075f973  proxysql-3.1.12-1-fedora44-clang.x86_64.rpm
ec2ef61a419a7da163ce10665b4de642990ae9672f4da6f1fb19fafc4ace138d  proxysql-3.1.12-1-fedora44.aarch64.rpm
20ca5a9d53da3972778d575a5d280778b1748e5d5c692f6b899928c587e8b265  proxysql-3.1.12-1-fedora44.x86_64.rpm
034d6e986a762b6a7e3d4d2f5a1fffd8f4e18f3ebafc311cb389bef50cdf6f56  proxysql-3.1.12-1-opensuse16-clang.x86_64.rpm
fe282ee93cd34d8f4b5a03106b83fac50c647b310a6d144417d311e2cb8a9cf1  proxysql-3.1.12-1-opensuse16.aarch64.rpm
fe0b2c4a76b9393a873189fdac2815613883a2c91d093587c25148432b240fc3  proxysql-3.1.12-1-opensuse16.x86_64.rpm
ad3bc629451959f1d5fa44294f24915fd1be8d370fbdb241d735081ea57bad29  proxysql-3.1.12-linux-amd64.tar.gz
6ac4e2b0dbeb420eb4fb62b11b6fc490825f628ad58fa3eb6601c4ff88ef63ae  proxysql-3.1.12-linux-amd64.tar.gz.sha256
a506b5a298d2a4b515f7b004b710f40c8b36c4684d06a5e58246574d3fe675ca  proxysql-3.1.12-linux-arm64.tar.gz
f99efdc2f4547a526204dd879c857a6a3ccf8caf812ebaed60e7ea4f33276a20  proxysql-3.1.12-linux-arm64.tar.gz.sha256
23143ae9387b2e19c814e4d866a2a6050996cef4489f717527ecb8b7b19a619a  proxysql-3.1.12.id-hash
57da38bee8e3269684933eb479cf011ada3ce30895d2fc807d4c7defbfc336cc  proxysql_3.1.12-dbg-debian12_amd64.deb
fbb93152551caab0808a25fde696b219f9d1429a869122219f640ed5c17cf6ca  proxysql_3.1.12-dbg-debian13_amd64.deb
a53570f92df7dff2cc0a161808cf588156964c46775bef3e6ae73c049f4ef80e  proxysql_3.1.12-dbg-ubuntu22_amd64.deb
f161800472798364e23d0f9c77a82fcf1227e82ace046c96716082f05e390a4a  proxysql_3.1.12-dbg-ubuntu24_amd64.deb
33bd74ce6279c2e7587d50c327a169de9bc51d8d1e43fa9dde6c0903f9406715  proxysql_3.1.12-dbg-ubuntu26_amd64.deb
68a76e3bbf4a10247e42fc4a181db7fbaca5d1bdd2ec3deb5197482ea3cdaa25  proxysql_3.1.12-debian12-clang_amd64.deb
23833fbd37e308f9a1b428ebfad6beb88232c52dcbe256d2b9c3acfe748c552b  proxysql_3.1.12-debian12_amd64.deb
a977e9f517d19d66a063bd2d7cb3db377907700cbbe0bee422c5bcfc446d5bb4  proxysql_3.1.12-debian12_arm64.deb
16272f8c756e44ee329cf7daedc340408e3925aeb0d1b48f688df755bed0ba9d  proxysql_3.1.12-debian13-clang_amd64.deb
6fa3ab69ff5d6c6462d00f964782aab32ab1d248b398255c61b62da2a72bd8cb  proxysql_3.1.12-debian13_amd64.deb
58ed533eff05f8916650c4d4e1cf6a3b9b8e9b8781841ef7fd79b810e90d9a09  proxysql_3.1.12-debian13_arm64.deb
463a682618bb9afabc37c4ee9ba094a42ea5d0eed646eea35076777c25a9c607  proxysql_3.1.12-ubuntu22-clang_amd64.deb
841c60397f29fe6132d5058964dc036ec2536fab52dbb09d4ee30ef93d78b72c  proxysql_3.1.12-ubuntu22_amd64.deb
d3902ef1aeaaabe4e0236b98689ff3845b71975122575107854a5bc4552db4e7  proxysql_3.1.12-ubuntu22_arm64.deb
f7d0cf2b3ca997702a749dbe50ffe585b1adb7f753ff3bb1db0a9e00f5882040  proxysql_3.1.12-ubuntu24-clang_amd64.deb
42a7cf3702513f8cceab61422afa9b6a69f2acc9b453ec10a294c9de6fcb00a5  proxysql_3.1.12-ubuntu24_amd64.deb
ab5f0c3071128a655f9da0025f3484d6c451ebd9e53d2c03c514b086795e2059  proxysql_3.1.12-ubuntu24_arm64.deb
c46ac1ace80d1abbbe13539f0669cb6dafee66fef315efbb3b35ae26c7fc4227  proxysql_3.1.12-ubuntu26-clang_amd64.deb
aa58ff30bd0c1da762534c845977d6f45e558ae622d25d0374bc791ffb83ea80  proxysql_3.1.12-ubuntu26_amd64.deb
1779a24c49191ec812c14e73c1e9904a92d9f4e514ee2da0c19d868529ac24df  proxysql_3.1.12-ubuntu26_arm64.deb