v4.0.12

ProxySQL 4.0.12 Release Notes

Release date: 2026-11-05

ProxySQL 4.0.12 adds ways to use familiar database clients for embedded analytics, connect ProxySQL to an InnoDB Cluster, and integrate database routing with optional AWS providers. It also makes plugin configuration more dependable across restarts, reloads, and shutdowns, and includes the protocol, transaction, and security fixes from 3.0.12 and 3.1.12.

The new DuckDB and MySQL Router compatibility plugins require source installation in this release. Downloadable 4.0.12 packages contain MySQLX and GenAI; they do not contain DuckDB or Router. Operators upgrading existing deployments should also review the new PCRE2 default, plugin ABI requirements, and MySQLX configuration migration below.

Highlights

• Embedded analytical SQL: the DuckDB plugin serves a shared database through MySQL and PostgreSQL simple-query clients, without running a separate DuckDB server.
• InnoDB Cluster integration: the Router compatibility plugin registers ProxySQL with cluster metadata and maintains supported topology and users in native ProxySQL configuration.
• Optional AWS integration: compatible external providers can supply short-lived IAM credentials, RDS/Aurora locality information, discovery inventories, and managed configuration. These providers are not bundled.
• More dependable plugin configuration: persistent tables restore before initialization, failed MySQLX route loads retain the working configuration, and MCP distinguishes staged settings from active runtime state.
• PostgreSQL and prepared-query improvements: native PostgreSQL backend execution, prepared-result caching for both protocols, backup routing, and pool diagnostics are included from 3.1.12.
• Eight security advisories fixed: the release includes the four high-severity and four medium-severity corrections shared by all three release tiers.

New Features

Embedded analytics through familiar clients

The DuckDB 1.4.5 plugin lets applications and database tools submit analytical SQL through an ordinary MySQL or PostgreSQL connection. Both listeners reach one embedded database inside the ProxySQL process. Authentication uses mysql_users and pgsql_users, so operators can manage admission through existing ProxySQL account tables. The plugin is available through source installation only in 4.0.12. (#6133.)

Use DuckDB SQL and simple-query client APIs: MySQL COM_QUERY and PostgreSQL simple Query are supported, while client prepared statements and PostgreSQL extended execution are not. Each request must contain one statement. Result columns are advertised as text, so applications that depend on numeric or other native type metadata must account for that boundary. Result adaptation is decided before execution, avoiding a second execution of writes or volatile expressions. (#6133, #6374.)

By default, the database is :memory: and lasts for the process lifetime. Set duckdb-database_path to a file-backed database to preserve data across restarts. Defaults are a 1GB DuckDB memory limit, two execution threads, and 100 connections across both listeners. DuckDB shares the process with ProxySQL, so leave memory for the core, other plugins, and connection buffers. There is no per-query timeout.

Authenticated users share the database without per-user database or table ACLs. The listeners default to 0.0.0.0:6031 and 0.0.0.0:6034; choose the intended bind addresses before exposing them. Database read-only mode defaults to false, and external access separately defaults to false. Read-only mode controls database access when opened; it does not replace external-access restrictions, and read-only :memory: is rejected. Clients cannot change engine-wide controls such as memory, threads, or external access with SET.

Settings use duckdb-* rows in the normal global-variable tables. Memory, thread, and connection-admission limits can change live. Database path, read-only mode, and listener-address changes require reopening the affected resource. Disabling external access can apply live; enabling it requires reopening the database. Extension autoload and autoinstall are disabled in the vendored build. See the DuckDB quickstart and configuration reference. (#6179, #6374.)

ProxySQL routing for InnoDB Cluster

Operators using MySQL Shell to manage an InnoDB Cluster can now register ProxySQL as a Router-compatible instance. The plugin reads cluster metadata and reconciles supported servers, users, hostgroups, and routing rules, reducing the need to maintain that inventory separately. It supports Metadata 2.2, single-primary Group Replication, and MySQL Shell-managed asynchronous read replicas. This plugin also requires source installation in 4.0.12. (#6144.)

The default writer endpoint is 6446, the reader endpoint is 6447, and query-aware read/write splitting uses 6450. The writer and reader endpoints switch to permanent fast-forward after their first matched COM_QUERY; the splitting endpoint continues to use query rules and transaction state. The existing operator-owned 6033 endpoint is retained. Lower-ID operator rules with apply=1 can override Router defaults, and reconciliation preserves operator-owned rows while rejecting ownership collisions. (#6144, #6474.)

Bootstrap accepts its password through a protected input channel such as --bootstrap-password-fd, writes configuration, and exits without serving clients. Passwords in the bootstrap URI are rejected. Start ProxySQL normally with the plugin loaded afterward; changing listener addresses requires a restart rather than a live rebind. Metadata failures no longer leave the plugin reporting ready while metadata is unavailable. (#6374, #6474.)

Metadata TLS settings persist across bootstrap and refreshes. In this implementation, both VERIFY_CA and VERIFY_IDENTITY require an explicit CA and check the hostname. REQUIRED checks negotiated TLS after Connector/C connects and does not authenticate the server; use a verifying mode when server authentication is required. MySQL X Router endpoints, takeover of an existing Router deployment, ReplicaSet, ClusterSet, and Routing Guidelines import are outside this release's scope. See the Router guide. (#6374.)

Optional AWS authentication, locality, and discovery

Deployments using RDS or Aurora can connect per-user backend authentication to an external IAM token source. Users whose backend-authentication policy selects aws_iam obtain tokens through that provider; the core handles token ownership, asynchronous acquisition, connection-pool isolation, and retries. A missing compatible token provider causes IAM authentication to fail closed. Provider deployment, AWS credentials or permissions, and the required TLS identity configuration must be supplied separately. (#6048, #6476.)

For deployments spread across regions or availability zones, mysql-aws_locality_awareness can bias selection toward eligible nearby RDS/Aurora backends using provider metadata and hostgroup policy. It defaults to false. The bias does not rewrite configured server weights or Cluster checksums, and zero-weight servers remain ineligible. Missing or expired locality metadata leaves selection neutral. (#6048.)

Discovery services let a compatible external controller maintain changing endpoint inventories while a selected native monitor continues to handle server roles, health, replication lag, and failover. A controller selecting monitor kind none also owns placement. Managed-configuration services add scoped revisions, idempotency, encrypted secrets, and provider-owned restoration; aws_managed=true requires the compatible management provider and Web binding at startup. These are integration contracts, not bundled AWS providers or automatically enabled services. See the plugin API and locality guide. (#6383, #6477, #6514.)

Database routing and prepared-query improvements

PostgreSQL applications can fetch a prepared result in batches through named portals, or subscribe to database events with LISTEN/NOTIFY. These capabilities use the new native backend protocol, which is enabled by default for new TCP backend connections. The previous PostgreSQL client-library path remains selectable with pgsql-use_native_backend_protocol=false.

Experimental prepared-result caching lets eligible repeated MySQL and PostgreSQL reads reuse a result through existing cache budgets, TTLs, and rules. Unsupported exchanges continue to the backend. Writes do not invalidate cached results. Configure caching only where skipping execution is acceptable, and flush affected entries after changes to permissions, schema semantics, or backend defaults. The 3.1.12 notes describe the supported execution and cache scopes. (#6194.)

Routing also gains MariaDB transaction-position checks for causal reads, helping applications choose replicas that have reached a required write. Subnet matching lets query rules cover groups of client addresses. Operators can reserve spare servers within a hostgroup and inspect pool-wait statistics when connection capacity is exhausted. The 3.0.12 and 3.1.12 feature sections explain these shared additions. (#6222, #6223, #6219, #6150.)

Bug Fixes

Restore plugin configuration before it is needed

Persistent plugin tables now restore after their schemas are registered and before initialization consumes their contents. MCP profiles and rules, and MySQLX entity tables, are therefore available when their modules initialize. Process RESTART and STOP/START rediscover configured plugins and retain their commands, tables, and hooks. (#6144, #6170, #6440.)

MySQLX validates a complete runtime candidate before replacing the active route set. A failed load keeps the previous working routes. Its scalar settings now use the standard mysqlx-* global-variable namespace; legacy settings require the manual migration in Upgrade Notes. (#6174, #6532.)

Make MCP reloads and diagnostics predictable

Loading MCP configuration from Disk into Memory now stages the candidate without changing runtime or reopening a stopped listener. Explicit TO RUNTIME activates the staged configuration. runtime_mcp_target_profiles reports effective and skip_reason, and load feedback explains installed or skipped targets, missing authentication profiles, inactive targets, and listener failures. (#6170, #6172.)

MCP listener reload drains old request threads before replacing shared dependencies. GenAI shutdown coordinates queue state with worker cleanup, and RAG embedding cleanup avoids duplicate deletion. (#6048, #6440, #6445, #6532.)

Contain plugin failures and preserve Admin state

The loader rejects duplicate plugin descriptor names and mismatched DEBUG/release layouts. Lifecycle and Admin exceptions fail cleanly, and a throwing query hook denies the query rather than bypassing its policy. A runtime-projection callback that throws after opening a transaction has that transaction rolled back instead of leaving it open. (#6133, #6144, #6440, #6470.)

Admin publication uses consistent lock ordering. Core LOAD MYSQL SERVERS TO RUNTIME and LOAD PGSQL SERVERS TO RUNTIME retain their established OK-reply behavior; plugins receive state notifications and cannot veto those operations. Cluster synchronization rejects incompatible plugin descriptor sets instead of copying configuration between them. (#6048, #6461, #6470, #6532.)

The release also includes the Stable fixes for partially answered MySQL batch retries, PostgreSQL transaction recovery, authentication, prepared statements, and malformed protocol input. See the 3.0.12 notes for those shared corrections.

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 query-rule patterns before adopting the new default. mysql-query_processor_regex and pgsql-query_processor_regex now default to engine 3, PCRE2, in 4.0.12. Syntax and rewrite behavior differ from PCRE engine 1; explicitly select 1 to retain that engine while migrating. RE2 remains engine 2. In engine 3, an invalid pattern stays inactive even when negated; matching-limit failures skip the rule. Check the regex migration guide, including patterns that become active or stop matching under PCRE2.
• Rebuild incompatible external plugins. Descriptor layouts 14 and 15 are refused and must be rebuilt for ABI 16. Compatible generic layouts 1–10 and 13 remain accepted; reserved layouts 11 and 12 are refused. Match the core's headers, feature flags, and DEBUG/release layout when building modules.
• Migrate MySQLX scalar settings explicitly. Move values from disk.mysqlx_variables into mysqlx-* rows in disk.global_variables. The old table remains intact and is ignored with a warning; its values are not imported automatically. Every mysqlx_routes.bind also needs an explicit decimal port from 1 through 65535, using host:port or [host]:port; invalid or missing ports no longer silently become 33060.
• Separate MCP staging from activation in automation. FROM DISK / TO MEMORY commands do not change live listeners, profiles, or rules. Add the corresponding explicit TO RUNTIME operation where activation is intended.
• Preserve encrypted state and deploy compatible Cluster peers. Back up proxysql-plugin-secrets.key with the plugin database when moving encrypted configuration. Peers must agree on loaded plugin descriptor names and ABI versions; synchronization checks @@proxysql_plugin_set_hash and closes/retries an incompatible peer.
• Review discovery ownership before enabling a provider. Active discovery claims define the runtime inventory for the claimed protocol. Unclaimed runtime rows can be removed even though their Admin Memory/Disk rows remain. A claim is not simply an additional source of health checks.
• Review PostgreSQL and cache policy changes. Native backend execution is enabled by default for new TCP connections; pgsql-use_native_backend_protocol provides the fallback control. Existing cache_ttl rules may now select eligible prepared reads, and writes do not invalidate their cached results. Read the 3.1.12 upgrade notes for protocol and cache restrictions before enabling these policies.

Dependencies, Build & Packaging

The release embeds OpenSSL 3.5.7, includes PCRE2 10.47, and updates RE2, Abseil, and ParserSQL. The source-installable analytics plugin uses DuckDB 1.4.5. Updating the host OpenSSL package alone does not update ProxySQL's embedded copy. This change does not establish FIPS compliance. (#6122, #6218.)

Source builds no longer require Git LFS for vendored archives and can reuse exact, verified OpenSSL dependency artifacts. Build compatibility fixes cover AlmaLinux 8 linking and GenAI normalization with older C++17 libraries.

DuckDB and Router are source-installation features in 4.0.12. The verified DEB, RPM, and tarball payloads contain MySQLX and GenAI modules only. Packaging follow-up is tracked in #6582; 4.0.13 is a tentative target, not a packaging commitment. Compatible external AWS providers must also be obtained and configured separately.

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

3b24032a11df7f3cb23932b134fe946d71e31a6085475829830362daccb746de  proxysql-4.0.12-1-almalinux10-clang.x86_64.rpm
c0ad536f462b78790ff8713e66fa55632f829d86de8eb9ee628298fabff20378  proxysql-4.0.12-1-almalinux10.aarch64.rpm
1ff2a60b60182929393a4d1e32aaeced9bfe327e5ae46ff7c661e03b6418ab59  proxysql-4.0.12-1-almalinux10.x86_64.rpm
f7907b01413db9b7b6ec5b300e7ea574dd4d11be83009a509730087eb985e39b  proxysql-4.0.12-1-almalinux8-clang.x86_64.rpm
72efe9b940e7aca068710ebfceb822ce607363f888e3acdaabca15b481a9c45e  proxysql-4.0.12-1-almalinux8.aarch64.rpm
6f44d83523fb6392b0b5b567b0018970164207bed6cf7b7852e40536f2ebfe0c  proxysql-4.0.12-1-almalinux8.x86_64.rpm
8008db7625b92878b52bf2e93691b8ba35a81649e47859f21570ab3e2a6cee09  proxysql-4.0.12-1-almalinux9-clang.x86_64.rpm
5e7a2ed3cabe36e36b57e53953eef48ee7b3a924882d0c4eb80399a8075cb28e  proxysql-4.0.12-1-almalinux9.aarch64.rpm
c284d55416613cd8a7f68607bc52f1035798b120503abcacb697ff1015b7d255  proxysql-4.0.12-1-almalinux9.x86_64.rpm
fe74ad5f3e12f9933afc3a8c514eaa858bbb0e32cb82b00684a5e6bd725ef699  proxysql-4.0.12-1-centos10-clang.x86_64.rpm
3a69a7e9659f12d0bc01cb3af9b9ed14c8bc803a68894591cceda9b67e2ff594  proxysql-4.0.12-1-centos10.aarch64.rpm
32b9920d91e126bfd17374ecc9559b0dd687ce9f44deef3614cf955997a313bc  proxysql-4.0.12-1-centos10.x86_64.rpm
ec4caa393b0b08209471b1d934d3f1c933e136d72d8fe6a472a0e3a60513e525  proxysql-4.0.12-1-centos9-clang.x86_64.rpm
401c1ddff1835e157cd9f2914bca4b9587fbe1399a420d7e35073e17198fb6bd  proxysql-4.0.12-1-centos9.aarch64.rpm
b70b200726f2b300e7bd815c39205c5bd9191395aed015e7dee310dec95c9dbd  proxysql-4.0.12-1-centos9.x86_64.rpm
89f80bbbef7919821ad78090b0bb93e77772d8c9cedc997e34be2fecf16fbea5  proxysql-4.0.12-1-dbg-almalinux10.x86_64.rpm
364aba045264f6535b486e26bf32c94b3bf9394fe40c4e29dfa4b14fddf1cb59  proxysql-4.0.12-1-dbg-almalinux8.x86_64.rpm
190cf71ee88432c5a3d36479945daf34a9a2d64e074f858abc11e52d145ae45a  proxysql-4.0.12-1-dbg-almalinux9.x86_64.rpm
05d8ea7565a41ac34c1607ada8342e0e271df4507292547333f3b52c780e9626  proxysql-4.0.12-1-dbg-centos10.x86_64.rpm
b62358a350f2678994915b8571837264be435eda72b4c93a250c00d6e5fad472  proxysql-4.0.12-1-dbg-centos9.x86_64.rpm
a3e5dcc07c18b52feb5a132d84d5d2bd1ebb368aa632de017b7491ecdeb2c3e4  proxysql-4.0.12-1-dbg-fedora42.x86_64.rpm
9e2f9a2ebacceb174a57b1fe7b47d718f0457e58c92b3592714af279997f2618  proxysql-4.0.12-1-dbg-fedora43.x86_64.rpm
3f830438736d34498783fef8bb930f3764395ce597fa9d5246c26ce538f4eb3c  proxysql-4.0.12-1-dbg-fedora44.x86_64.rpm
2ea5d7dbc27b2dae706d518c7bd31f71ac073d75e32db653e7630333fa74fd6b  proxysql-4.0.12-1-dbg-opensuse16.x86_64.rpm
c236de7608121e4d2c0bf8f7a7636910176495f2d0824675f99285757d37eddd  proxysql-4.0.12-1-fedora42-clang.x86_64.rpm
3b90eb54087aa7d56fa4c763e217dddac98810327f9b1ad1d3c9cc2559563811  proxysql-4.0.12-1-fedora42.aarch64.rpm
39bc65673cdb9bb5b1713aae7394a9c1e302bf0d33b8d8d66b974a08494bd95a  proxysql-4.0.12-1-fedora42.x86_64.rpm
abd30a1daeb9de9806cc1fbfb0226a02ed13de0b2f9e7b88c4d3a07317a17399  proxysql-4.0.12-1-fedora43-clang.x86_64.rpm
2773236710eaa51226aed711e2b5ca9309e253c6fe3239e74a48b7805558a543  proxysql-4.0.12-1-fedora43.aarch64.rpm
73134c9d34f48e4fa3f8630dd701ceab3507c91bbb8fcd9375bf3cb4b68b3b4d  proxysql-4.0.12-1-fedora43.x86_64.rpm
e58c1c76659bce92993800a36d02abb2b6e66f26520638338ed7bd58d86f05f2  proxysql-4.0.12-1-fedora44-clang.x86_64.rpm
402cf2e8660313cae67f19d1ec395a3a62acc3fdb55ddb8b5a2f534b49f5fb85  proxysql-4.0.12-1-fedora44.aarch64.rpm
ead8fbd1ebbd0c1f5b8d50c0dfee9b62c120f317ec01afe0691004e63868c3e5  proxysql-4.0.12-1-fedora44.x86_64.rpm
4efae2df159b81acdf129882119e4e7a65467bb4e4fa5bce65aaf7377783eea9  proxysql-4.0.12-1-opensuse16-clang.x86_64.rpm
f7388ee146195f1831ce717b7ce360649ae3bb5718ffcce89ccd55e5e7fd5180  proxysql-4.0.12-1-opensuse16.aarch64.rpm
12f9b21dd81ad67e269fb37580087e04fcd759fc9f358e8a1f5111975ef62813  proxysql-4.0.12-1-opensuse16.x86_64.rpm
518289c84196dd431f8c0059824987228877619e7971bd8238f1771d0f248b87  proxysql-4.0.12-linux-amd64.tar.gz
feaff28637bf998e1b4ebd44e1bcbfbd961cb21b53f59cb7a660a59cedd9f391  proxysql-4.0.12-linux-amd64.tar.gz.sha256
109a4eae47a4126f9707cfc1363cb9239dda08cd7ef38444f8bb89c8db4fe951  proxysql-4.0.12-linux-arm64.tar.gz
404f034788e0a2660b12b01d17a26d8f0398e71246efc4122ecd4ff2426558fe  proxysql-4.0.12-linux-arm64.tar.gz.sha256
4ca073e8a9d37a82f7b1a5477a9b8373830f207cda8f4a554d16dec02acf38c3  proxysql-4.0.12.id-hash
05ced892df8f1e0d3b6d1b7bf68e348c958911de47c542c4db2ed218e6cb5844  proxysql_4.0.12-dbg-debian12_amd64.deb
92e5440a8c92838dd60dfb69d09a17ee460f54368db3e20ec1b9b590d085c590  proxysql_4.0.12-dbg-debian13_amd64.deb
51806d78f78e03091563706f53ab6e321206aebf2eb5606db080292e3009a947  proxysql_4.0.12-dbg-ubuntu22_amd64.deb
b0edd7c684dd2e9485f2a03e6d4387250e8f730015888888d0b1b56a1655467a  proxysql_4.0.12-dbg-ubuntu24_amd64.deb
4989f1ac7bf82242d6277436088fb789b60708b7b251d4ed10c6b772a38e963d  proxysql_4.0.12-dbg-ubuntu26_amd64.deb
e6da5ca1f8e5a61db7d4895f8cc4ee36df3945ba40095003a6e3185c68fa97f3  proxysql_4.0.12-debian12-clang_amd64.deb
28d233cf23bf4e5d763b3c6f4a071ff91f427be7f08c1fc9fd16422a1250a9af  proxysql_4.0.12-debian12_amd64.deb
a02df1bfdc21e790a026cc00b96b0353468cb219605e66dbe75499d79085d94c  proxysql_4.0.12-debian12_arm64.deb
ff964190f0bf3750ad1b1a4abb9c17fbeda913f9d0cb686076804aa6c4c01b11  proxysql_4.0.12-debian13-clang_amd64.deb
569d873f390fa69ef8394af88129d9c9c60a0e6161441563dcdaf69c02f6e3a1  proxysql_4.0.12-debian13_amd64.deb
063a92207557def62c5ba3777191dbbb9eb94e1f2ef7a8dda0bad848732a4ae2  proxysql_4.0.12-debian13_arm64.deb
c90e2e597f822606471f276bb08f7fd4de3947b8576f8ee4e510ade31f9b9582  proxysql_4.0.12-ubuntu22-clang_amd64.deb
aff58e82f06b38ef8b8d3b98d660f1d7d2034308331f57e872ec0e57db40f471  proxysql_4.0.12-ubuntu22_amd64.deb
c7cb5ebabbe2cfacffea0b830342f875e4dfed6755d64e2ffe8e76fef11f16c4  proxysql_4.0.12-ubuntu22_arm64.deb
3c57d98704a84b98de42aaa11221e10328740e8e67a1c1ca3fcb378e812a572f  proxysql_4.0.12-ubuntu24-clang_amd64.deb
18cea4cb4dc56f590352ef268a664f09d8b8a3cf8fbe4cb1efe7bdb8efa9e6b0  proxysql_4.0.12-ubuntu24_amd64.deb
1b7baa96b1a9e4549688a540d1844af8926a0d6dfea542199b2591c868627432  proxysql_4.0.12-ubuntu24_arm64.deb
4c88593a362f2fcbdaaafdebac7648b9b7d179918583d2479eb8bfcc5bf55987  proxysql_4.0.12-ubuntu26-clang_amd64.deb
d9ab14d369d9814f1792db8ac8c6b254602ae86d470e8ee51fc6a2fb1f651b66  proxysql_4.0.12-ubuntu26_amd64.deb
d9efce048de5dd8319eb10e9ea60f7d78cb47d2c77327e4cd15459469c12eb56  proxysql_4.0.12-ubuntu26_arm64.deb