v3.0.10

ProxySQL 3.0.10 Release Notes

Release date: 2026-07-31
Release commit: f5f1e148e
Covers all changes on the v3.0 branch since v3.0.9 (428 commits / 57 PRs,
plus the direct security fix 396c742f7).

ProxySQL 3.0.10 is a maintenance and feature release for the Stable Tier. Its
headline changes are per-hostgroup query timeouts, time-based purging of the
query-digest stats, visible feedback for rejected variables on
LOAD ... VARIABLES TO RUNTIME, PostgreSQL Unix-socket support, AWS RDS
Blue/Green monitoring, and complete configuration round-tripping, together
with correctness fixes for cross-hostgroup prepared statements,
PostgreSQL extended-protocol result formats, compressed MySQL packets, and
backend shunning on expired passwords — plus frontend COM_PING metrics,
generic Linux .tar.gz builds, a portable jemalloc page-size fix, and a broad
testing/CI hardening pass.

Note on pass-through authentication. The pass-through authentication feature
introduced this cycle (#5810, #5945) is an Innovative-tier / AI-MCP-tier feature and
is documented in the 3.1.10 / 4.0.10 release notes. Its code is present in the
3.0.10 Stable build, but it cannot be enabled on the Stable tier: setting
mysql-passthrough_auth_enabled=true is refused and forced back to false at
LOAD MYSQL VARIABLES TO RUNTIME. Use a 3.1.x or 4.0.x build to enable it.

Release commit: f5f1e148e

Highlights

• Per-hostgroup query timeouts: a new default_query_timeout attribute in
  mysql_hostgroup_attributes.hostgroup_settings sets a constant-time query
  timeout per hostgroup, with precedence per-rule > per-hostgroup > global
  (#5772).
• Time-based PURGE of stats_mysql_query_digest: prune digest rows by
  last-seen timestamp instead of wiping the whole table (#4920, closes #4543).
• Actionable feedback on config loads: LOAD MYSQL/PGSQL/ADMIN/... VARIABLES TO RUNTIME now reports Records: N Updated: X Rejected: Y Unknown: Z in the OK
  packet instead of a silent Query OK (#5857, fixes #1288).
• PostgreSQL Unix-domain-socket backends: pgsql_servers rows with port=0
  now connect over the socket path in hostname (#5844, closes #5837).
• AWS RDS Blue/Green monitoring: monitor mysql.rds_topology, manage writer
  and reader switchover state, support explicit and automatically discovered
  green hostgroups, pin green addresses, drain connections, and handle
  completion or rollback (#5861).
• Complete configuration round-tripping: SAVE CONFIG, SELECT CONFIG FILE,
  and LOAD ... FROM CONFIG now preserve firewall and fast-routing tables,
  server SSL parameters, and PostgreSQL hostgroup attributes (#5922, closes
  #3468).
• Frontend COM_PING metrics: Com_frontend_ping is exposed through
  stats_mysql_global and the Prometheus metrics surface (#5948).
• Correctness fixes for a cross-hostgroup prepared-statement memory bug that
  corrupted result rows (#5895), silent PostgreSQL data corruption on mixed Bind
  result formats (#5878), PostgreSQL Bind messages with one format and zero
  parameters (#5899), compressed MySQL packets with a mismatched zlib length
  (396c742f7, GHSA-fvch-fpgq-pwfx), and unwarranted backend shunning when a
  user's password is expired (#5847).
• Portability: jemalloc no longer crashes at startup on 16 KB/64 KB page
  platforms (Apple Silicon, AWS Graviton, ppc64le) (#5822), and ProxySQL now
  publishes generic Linux .tar.gz binaries in addition to RPM/DEB (#569).

New Features

Pass-through authentication (#5810) also landed on the v3.0 branch this
cycle but is gated to the Innovative (3.1.x) and AI/MCP (4.0.x) tiers — it cannot
be enabled on the Stable 3.0.x build (see the note above). It is described in
full in the 3.1.10 / 4.0.10 release notes.

Per-hostgroup query timeouts (#5772)

A new default_query_timeout pseudo-attribute in the
mysql_hostgroup_attributes.hostgroup_settings JSON column sets a per-hostgroup
query timeout in constant time, without pinning a query rule to a specific user.

INSERT INTO mysql_hostgroup_attributes (hostgroup_id, hostgroup_settings)
VALUES (100, '{"default_query_timeout": 8000}');
LOAD MYSQL SERVERS TO RUNTIME;

Precedence is per-rule mysql_query_rules.timeout > per-hostgroup
default_query_timeout > global mysql-default_query_timeout. The attribute is
validated and range-checked; an invalid or unset value falls back to the global
default. The same mechanism applies to the PostgreSQL hostgroup path.

AWS RDS Blue/Green deployment monitoring (#5861)

ProxySQL now monitors Amazon RDS Multi-AZ DB instance Blue/Green deployments
through mysql.rds_topology. The monitor maps blue and green writer/reader
hostgroups, supports explicit green hostgroups and automatic discovery, probes
the promoted writer directly, pins resolved green addresses, drains affected
connections, and handles completed switchovers, cancellation, rollback, and
topology cleanup. Configuration and runtime state are represented by the
mysql_aws_rds_bgd_hostgroups tables and participate in cluster synchronization.
The release also includes a simulator, TAP coverage, and unit tests for the
deployment lifecycle.

Full configuration round-tripping (#5922, closes #3468)

Configuration export and import now round-trip MySQL and PostgreSQL fast-routing
rules, firewall tables, server SSL parameters, and PostgreSQL hostgroup
attributes through SAVE CONFIG, SELECT CONFIG, SELECT INTO OUTFILE, and
the corresponding LOAD ... FROM CONFIG commands. Writers tolerate missing
optional sub-tables, so a partial or older Admin schema does not make the whole
configuration export fail.

Frontend COM_PING metrics (#5948)

Each frontend COM_PING received while a MySQL session is idle increments
Com_frontend_ping in stats_mysql_global and the corresponding
proxysql_com_frontend_ping_total Prometheus metric, making driver health-check
rates visible without inferring them from SELECT 1 traffic.

Time-based purge of stats_mysql_query_digest (#4920, closes #4543)

The PURGE command for the query-digest stats now accepts a last-seen timestamp,
so operators can prune only digests not seen since a given time instead of
clearing the entire table. The purge logic is unified across the synchronous and
asynchronous paths, and monotonic-to-realtime clock conversion helpers were added
to support it.

Visible feedback for rejected variables on config load (#5857, fixes #1288)

Previously, LOAD MYSQL VARIABLES TO RUNTIME (and the PGSQL, ADMIN,
SQLITESERVER, CLICKHOUSE, LDAP, and TSDB equivalents) silently dropped rows
whose value failed module-side validation, returning only Query OK, 0 rows affected. The OK packet's info field now carries a
Records: N Updated: X Rejected: Y Unknown: Z summary — e.g.
Records: 184 Updated: 181 Rejected: 2 Unknown: 1 — naming exactly how many
variables were accepted, rejected, or unknown. Existing log lines and
reset/delete semantics are unchanged.

PostgreSQL Unix-domain-socket backends (#5844, closes #5837)

When a pgsql_servers row has port=0, its hostname is treated as a
Unix-domain-socket directory path. libpq rejects port=0 outright, so ProxySQL
now omits the port= field from the conninfo string at the three sites that
build it (client connect, backend kill, and the PgSQL monitor).

PROXYSQL INTERNAL SESSION reports the build version (#5877, implements #5859)

The JSON returned by PROXYSQL INTERNAL SESSION now includes a version field
(for both the MySQL and PostgreSQL protocols), sourced from PROXYSQL_VERSION, so
a session dump can be correlated with the exact build that produced it. The key is
purely additive.

Admin connect-setup robustness (#5826, #5786)

The admin interface's connect-setup accept-blocks now strip leading whitespace and
/* … */ block comments before matching, so clients that prepend SQL tracing
comments to every statement — SQLCommenter, the Datadog Agent's mysql
integration, Sequelize, Hibernate — no longer fail admin-port connection setup
with near "SET": syntax error. SET LOCK_WAIT_TIMEOUT is also now accepted in
the connect-setup block.

Richer diagnostics on protocol violations (#5936)

When a client sends packets out of order, the "Unexpected packet" / "Unexpected
COM_QUIT" error log now includes the front-end username, hostgroup id, and
connection id, so the offending client can be correlated with the subsequent
KILL CONNECTION line.

Unhealthy-connection diagnostics (#5946)

Warnings emitted when ProxySQL closes an unhealthy or fast-forward client now
include the frontend username, current hostgroup, and backend connection id,
making the client, route, and backend session identifiable from the log entry.

Bug Fixes (Core ProxySQL)

• MySQL compressed-packet information disclosure (396c742f7,
  GHSA-fvch-fpgq-pwfx): the zlib decompression path now verifies that the number
  of bytes produced exactly matches the length declared by the packet before
  parsing the buffer, preventing uninitialized trailing memory from being
  interpreted as MySQL packets.
• PostgreSQL Bind with zero parameters (#5899): a Bind message containing
  one parameter format and no parameters is now accepted according to the
  PostgreSQL protocol; other format-count mismatches return a protocol-violation
  error.
• Dangling STMT_EXECUTE bind buffers across a hostgroup split (#5895, fixes
  #5883): stmt_execute_metadata_t.binds[i].buffer aliases packet/long-data
  memory that is freed after each execute. Only the MYSQL_TYPE_TIME-family
  buffers were being nulled, leaving the other parameter buffers dangling. When a
  session spanned two hostgroups (e.g. writes to one hostgroup while a
  SELECT /* hostgroup=… */ prepared statement went to another), the re-entrant
  lazy-prepare path consumed the dangling binds against freed memory, corrupting
  prepared-statement result rows. Every parameter buffer is now nulled after the
  free. The same PR de-flakes mysql-mirror1-t, which asserted exact row counts
  against best-effort (lossy) mirroring.
• PostgreSQL: silent corruption on heterogeneous Bind result formats (#5878,
  fixes #5866): libpq's PQsendQueryPrepared() accepts only one result-column
  format for all columns, so a per-column format array in the Bind message (e.g.
  pgx requesting text for a varchar and binary for a bytea) was collapsed
  to the first code, returning the remaining columns in the wrong format and
  corrupting binary-preferred values. ProxySQL now rejects a heterogeneous
  result-format array with a clean ErrorResponse instead of returning wrong
  bytes. Uniform arrays ({}, {0,0}, {1,1}, or all-identical codes) are
  unaffected.
• Expired password no longer shuns the backend (#5847, see #5846):
  MySrvC::connect_error() now skips ER_MUST_CHANGE_PASSWORD_LOGIN (1862) — the
  errno MySQL 8.0 / Aurora returns when a user's password is expired. This is
  per-user state, not backend health, so it no longer counts toward
  mysql-shun_on_failures and can no longer mark an otherwise-healthy backend
  SHUNNED for unrelated clients.
• Monitor schema: drop unreachable port defaults (#5850): the DEFAULT 3306
  / DEFAULT 6032 clauses on the port column of the monitor SQLite tables were
  unreachable (every table's primary key includes port NOT NULL and all internal
  inserts supply the port) and are removed for schema honesty. No data or runtime
  behavior changes.

Dependencies, Build & Packaging

• Generic Linux .tar.gz binaries (#569, #5881, #5892, #5898, #5911):
  ProxySQL now publishes distro-independent Linux tarballs alongside RPM/DEB, built
  one tarball per tier (v3.0 / v3.1 / v4.0). Documentation for the generic tarball
  builds is included.
• Portable jemalloc page-size detection (#5822, fixes #4863, #3252): the build
  now auto-detects the system page size via getconf PAGESIZE instead of the old
  ARM+CentOS-only --with-lg-page=16 override. This fixes the
  <jemalloc>: Unsupported system page size startup crash on all non-4 KB-page
  platforms — Apple Silicon (16 KB), AWS Graviton / ppc64le (64 KB), CentOS ARM.
• ParserSQL bumped to v1.0.10 (#5915).
• Vendored cpp-dotenv updated to v1.1.0 (#5875).
• Vendored protobuf / zstd / lz4 build fixes: installed protobuf to lib/
  (not lib64/), and built vendored zstd/lz4 with -fPIC, so shared-object
  plugin links resolve.
• Packaging build pipeline cleanup (#5975): v4.0 packaging containers no
  longer install protobuf at runtime; the dependency is supplied by the build
  image, and container build failures now propagate through the packaging target.

Testing & CI

This cycle carried a large test-infrastructure hardening effort:

• macOS (Darwin) TAP build support (#5933): integration tests build with the
  platform shared-library extension (.so/.dylib) and GNU-ld flags.
• Vendored replication / shunning suite (#5872, #5876, #5888, #5923): the
  replication and shunning TAP suite is now vendored from jenkins-build-scripts,
  with every polling wait bounded, a wait-for-sync before checksum comparison, and
  recovery of a relayed replica IO thread that dies on backend blips.
• MySQL 9.x Group Replication CI (#5880, #5909): new mysql90/93/95-gr
  workflows, and a report_host infra fix so ProxySQL's GR monitor can reach
  members at a routable address (the previous 127.0.0.1 advertisement made the
  monitor shun all members and empty the writer hostgroup).
• ParserSQL SET-parser cases ported from PR #5088 (#5893).
• Coverage / codecov path fixes (#5843, #5858) and retirement of redundant
  taptests CI callers superseded by the modern groups (#5870).
• CI robustness: per-variant docker-compose projects (#5914), robust MySQL tarball
  downloads (#5917), workflow_run permission fixes (#5867), and an
  infra-agnostic ANSI_QUOTES GR test (#5920).
• Post-draft regression coverage: pass-through-auth pool reuse (#5944),
  PostgreSQL zero-parameter Bind handling (#5899, #5955), compressed-packet
  decompression validation (396c742f7), and the AWS RDS Blue/Green simulator
  and lifecycle suite (#5861).
• Coverage and workflow hardening: unit/TAP Codecov merge validation
  (#5954, #5966) and the PostgreSQL cluster TAP caller/reusable-workflow split
  (#5963).

Contributors

Thanks to everyone who contributed to this release, including @renecannao,
@wazir-ahmed, @rahim-kanji, @burnison, @takaidohigasi, @shabih-paystack,
@anthonyryan1, @fogelito, @Zhao73.
Security credit: Tristan Madani (Talence Security) responsibly reported GHSA-fvch-fpgq-pwfx.

Feature/fix requesters and reporters — thank you: @seikath (session version
field, #5859), and the reporters of #4543, #1288, #5786, #5837, #5866, #5883,
#5846, #4863, and #3252.

Packages

Alongside the usual .deb and .rpm packages, this release ships generic Linux
tarballs — proxysql-3.0.10-linux-amd64.tar.gz and
proxysql-3.0.10-linux-arm64.tar.gz — each with a .sha256 checksum and a
detached .asc GPG signature made with the ProxySQL release key
(653F85BB38256DF8A96206C3E8CA2E8D8217C97E).

Two platforms are intentionally not included in this release:

• AlmaLinux 8 — the platform cannot satisfy the OpenSSL 3 requirement that
  ProxySQL 3.0 depends on.
• openSUSE 15 and 16, aarch64 only — their post-build verification failed
  in CI. The x86_64 openSUSE packages are unaffected and are included.

Hashes

The release commit is: f5f1e148e.

SHA256s:

a017dd005cafa436cf59f17289bb00ecb01358e1e88ac4d2866892e335d5d826  proxysql-3.0.10-1-almalinux10-clang.x86_64.rpm
4ec7f4b97ec4880ce39bfd4d7627ed73bd7f2845460edac770347f1a91e0d3d2  proxysql-3.0.10-1-almalinux10.aarch64.rpm
7e23ac991829a34d846dd47be9d6e3ddc199540f5b0736a43a9ccbac860d94cc  proxysql-3.0.10-1-almalinux10.x86_64.rpm
93904468199f7f39cffbde25e8c4af5aaecd54b07d0dd1ff00eb6fe15d80d906  proxysql-3.0.10-1-almalinux9-clang.x86_64.rpm
a85cc2f24a4cb1afe8630d63212de29efb8b78f057527ef281e3647f76fb9c4c  proxysql-3.0.10-1-almalinux9.aarch64.rpm
e5163f9b2095765a34dc2c12a69a9377b755635e75f4b0215dd005c4a6b21e9b  proxysql-3.0.10-1-almalinux9.x86_64.rpm
581d4e954294c6e34ba8709a6cf7e181b84959d878510c7a481774881332f40c  proxysql-3.0.10-1-centos10-clang.x86_64.rpm
eb34dec3d4b8115189cba15d9fff76cb647003f7ff47e077777afa16d8a03997  proxysql-3.0.10-1-centos10.aarch64.rpm
61493587a4770c7218a54701c4945f00e38e8d292d9a9ff7ec8844ce54e7c9c5  proxysql-3.0.10-1-centos10.x86_64.rpm
822412259634cbb83f913bd719b5132e6d622072470645b38260a52314822db5  proxysql-3.0.10-1-centos9-clang.x86_64.rpm
bc868c3dc408449d980a3f392e65ae914cfe6a70e10eb317d4a133c2cedd9b05  proxysql-3.0.10-1-centos9.aarch64.rpm
04d5696c2b9b12bf5dd758a3024c4553231c629521929274d5dd1d53bc35ecc0  proxysql-3.0.10-1-centos9.x86_64.rpm
1de95cffdc972abc828a523dbf458212cde341a47d672c344029bbef30d6ff01  proxysql-3.0.10-1-dbg-almalinux10.x86_64.rpm
9880cda1a533941f3a773d7a64dc292009fab39777b379eb4158941b6cf55761  proxysql-3.0.10-1-dbg-almalinux9.x86_64.rpm
65b77ec18b4cede575e6336d3c1612afa36b02f9c478a9f0ce71638c08e88059  proxysql-3.0.10-1-dbg-centos10.x86_64.rpm
b7ad6bbb1111dfda401bc2f109271532f0ef861aea798882cdabb261a9b38a98  proxysql-3.0.10-1-dbg-centos9.x86_64.rpm
cf5885e8f35d6b496e36cfcdc95e6e659f1761446d4c4f11ef5c703c4bd956e2  proxysql-3.0.10-1-dbg-fedora42.x86_64.rpm
5e0291577bd0fb802960f845c95e126313a5eb329a419d0dd008dc424c03d88d  proxysql-3.0.10-1-dbg-fedora43.x86_64.rpm
5d8288232f2830c7c8017bd95654e8fa49b5f9c976ea84105b4cfb1a72ee90f3  proxysql-3.0.10-1-dbg-fedora44.x86_64.rpm
9546ce16e38cdbd53234c598644f73b58cf74883d60400aa7bd557710142fc55  proxysql-3.0.10-1-dbg-opensuse15.x86_64.rpm
c7a57edab3e2c5c6e087efc3cd810fb4393569c764b415d18b667d5d349f4674  proxysql-3.0.10-1-dbg-opensuse16.x86_64.rpm
275555341c59982b3232ae8a6e5dbda07b08a616d23e3f16a63ce1cb170045f4  proxysql-3.0.10-1-fedora42-clang.x86_64.rpm
a718ba97a73e908beb093589a71c2dd534a4008f6b4d170c5eecc434969b5f0d  proxysql-3.0.10-1-fedora42.aarch64.rpm
08b3463fa38f5d82b3b601367c132b183c059a91fdb9cbabc5a169589f96e83c  proxysql-3.0.10-1-fedora42.x86_64.rpm
0afc99bafa8e02a5045a5677b6cda671b8fd9c213bac403839cf46b55a3c4259  proxysql-3.0.10-1-fedora43-clang.x86_64.rpm
4c7a31eaac2a26f7ab2aba8cbe275a420408e33689c6463c11993276ab4a02e5  proxysql-3.0.10-1-fedora43.aarch64.rpm
1b8b96347132e6d7e6fab846337654c023848874e7a2e78220a0fb251e775952  proxysql-3.0.10-1-fedora43.x86_64.rpm
f964c702caca2660a376f92d28162245fd959accf1a5cb1db847ff2227881cd3  proxysql-3.0.10-1-fedora44-clang.x86_64.rpm
8269daff29b4c71ae00758cc79b4ce0bb71ff08ec1c3c50719e1ac7fae3a9639  proxysql-3.0.10-1-fedora44.aarch64.rpm
c1546f466e72caf73ff62c5fa6e14799e5d6340f69e5caa96e8881c9c77cdf32  proxysql-3.0.10-1-fedora44.x86_64.rpm
a8cfb1bbe6ef8a5574964d390e1c914f5052e6e8c4f72120a6a8bb3204363ede  proxysql-3.0.10-1-opensuse15-clang.x86_64.rpm
0b28534db94882912416b9b03e6285068c142f3bdb64817f2eb66aadf0f399b6  proxysql-3.0.10-1-opensuse15.x86_64.rpm
f1bf05b5db9fd267b63d842c09555697395387344a2b505ebeff5a763302f63b  proxysql-3.0.10-1-opensuse16-clang.x86_64.rpm
bb962eeab7f99368cb90aa789e95c03bf7af0494819b3106a6a8b9babd34beb0  proxysql-3.0.10-1-opensuse16.x86_64.rpm
793ba753023dbbc6edd47ebf927655d9605299e5f4cb2420847cfecf97a2cf95  proxysql-3.0.10-linux-amd64.tar.gz
7c7b40d9969a88451d601a31c09fd75f4d7a0e1ab60d64d61dd331a3f06a56f9  proxysql-3.0.10-linux-amd64.tar.gz.asc
a641fe13bccb6cd8e63dbf190eca64356eb5c45bae1cb53925bfee4ed0294e4b  proxysql-3.0.10-linux-amd64.tar.gz.sha256
8b84878130d4966c0dacffbe23a1da3675bbad572858d97019e48f8e96676ecf  proxysql-3.0.10-linux-arm64.tar.gz
e61b1aac1a0d954e4d4625c5cd3bbdfcb9189957d208692b7e698af05e12065a  proxysql-3.0.10-linux-arm64.tar.gz.asc
a4fdbca633e203210ace46aa9e7723828b5b13d8a00dcddb02f0babc5ede7438  proxysql-3.0.10-linux-arm64.tar.gz.sha256
8c42bbf3a56169c1122ad091eb998050684107575e2c55d101970801de334c41  proxysql-3.0.10.id-hash
1f8d1f75242a4e3314befda7b3df782c5ba93d8bc63e65c3d5117720aa0489c4  proxysql_3.0.10-dbg-debian12_amd64.deb
bdc6c3ac9038f7ad31c38e04234c74b14e14030d541ea9043f0b314d9c1c222a  proxysql_3.0.10-dbg-debian13_amd64.deb
725a7c9928cdfa06b4e0f2a5a349258a7bfce19f7c5c95dc08e3cabe593162b2  proxysql_3.0.10-dbg-ubuntu22_amd64.deb
436a4a7c82188f3db333b4a8ab8f811625ec74e548554d4fa50dd509025c9b2e  proxysql_3.0.10-dbg-ubuntu24_amd64.deb
d12be7da55d112b7061d3cf05f54d81755d89b4157242a7686c9efb6e7ea5086  proxysql_3.0.10-debian12-clang_amd64.deb
ddf4e8e5e110d997566ac14429bb2b821c8dc7c240fa5fe47853aeed3a4c7dac  proxysql_3.0.10-debian12_amd64.deb
03658556bd83b81fe0b2854e42595a2ed6a6fddbc699783eff87aa46bb69e4da  proxysql_3.0.10-debian12_arm64.deb
25e06a6dee27a860bbb82ad5266951325772d2991ae68273f3091f5a8e25823d  proxysql_3.0.10-debian13-clang_amd64.deb
d625b45786a55a134e989081729cf96b5bd7ee7e2d0d3f168240cd6a10f82dca  proxysql_3.0.10-debian13_amd64.deb
e9396130f5f352ebd000f4864ba307d3ea16edf985af6373230b59bf7a404ac6  proxysql_3.0.10-debian13_arm64.deb
a054adf011d9173ce4d8411d2cee03b29a8b9000b98f08a54ca8a3e9815779ff  proxysql_3.0.10-ubuntu22-clang_amd64.deb
c9191becea12a949d37b503bd1231e2215afc1926df2df6ea0dddefd2632437a  proxysql_3.0.10-ubuntu22_amd64.deb
7a5cd075197e3eded428f5fd7d9ab16d745502f47abfce700d28f49074bf3ae8  proxysql_3.0.10-ubuntu22_arm64.deb
1ce1f14746568fe81b654490f20e327af48a477255529cd95bee69e277eed0bf  proxysql_3.0.10-ubuntu24-clang_amd64.deb
1463473c076db228ed7173d503e6d5cc966a6007af85ddb117b9acaa5a159c2c  proxysql_3.0.10-ubuntu24_amd64.deb
d40735fad8e588b48e995d334dd9b0cf71b77fa84d3ca5fc947ed014ff4df941  proxysql_3.0.10-ubuntu24_arm64.deb