ProxySQL 3.0.4 Release Notes

This release of ProxySQL 3.0.4 brings significant enhancements to PostgreSQL compatibility, MySQL protocol robustness, monitoring accuracy, and security hardening. With improved SSL/TLS support for PostgreSQL backends, better handling of edge-case MySQL protocol packets, and numerous performance optimizations, this release strengthens ProxySQL's position as a reliable database proxy for both MySQL and PostgreSQL ecosystems.

Release commit: faa64a570d19fe35af43494db0babdee3e3cdc89

Highlights

This release focuses on several key areas:

• Enhanced PostgreSQL Support: A PostgreSQL-specific tokenizer improves query digest generation, while SSL/TLS support for backend connections strengthens security in PostgreSQL monitoring.
• MySQL Protocol Robustness: Special handling for unexpected COM_PING packets prevents connection issues, and direct response to SELECT @@version queries reduces backend load.
• Monitoring Improvements: Fixes for artificially high ping latency provide more accurate health checks, and TCP keepalive warnings help identify potential connection stability issues.
• Security Hardening: A critical SQL injection vulnerability in configuration parsing has been fixed using prepared statements with bound parameters.
• Performance Optimizations: Lock-free hot paths for prepared statement cache operations reduce contention in high-concurrency environments.

New Features

PostgreSQL Improvements

ProxySQL's PostgreSQL support sees two major enhancements in this release:

PostgreSQL-Specific Tokenizer for Query Digest Generation (285fb1b, #5254)
The new tokenizer adds comprehensive PostgreSQL dialect support, including dollar-quoted strings ($$...$$), double-quoted identifiers, type cast syntax (value::type), array literals (ARRAY[...] and {...}), and prefixed literals (E'', U&'', x'', b''). This improves query fingerprinting accuracy for PostgreSQL workloads, ensuring similar queries are properly grouped together for caching and analysis. The tokenizer also handles nested comments and PostgreSQL-specific comment rules, providing more reliable query parsing.

SSL Support for Backend Connections in PostgreSQL Monitor (7205f42, #5237)
The PostgreSQL monitor now supports client certificates for SSL/TLS connections to backend servers, enhancing security for monitored connections. New metrics PgSQL_Monitor_ssl_connections_OK and PgSQL_Monitor_non_ssl_connections_OK provide visibility into connection status, helping administrators verify SSL/TLS configuration and troubleshoot connection issues.

MySQL Protocol Enhancements

Several improvements make ProxySQL more robust when handling MySQL protocol edge cases:

Special Handling for Unexpected COM_PING Packets (d0e8859, #5257)
Some MySQL clients occasionally send COM_PING packets during query processing, which previously caused connection issues. ProxySQL now queues these unexpected COM_PING packets as counters and sends corresponding OK packets after query completion, maintaining connection stability without interrupting normal query flow. Enhanced logging includes client address, session status, and data stream status for better debugging.

Handling of SELECT @@version and SELECT VERSION() Without Backend (df287b2, #4889)
To reduce unnecessary backend load, ProxySQL now responds directly to SELECT @@version and SELECT VERSION() queries without establishing backend connections. It returns a hardcoded server version (currently 8.0.0), which is sufficient for most client compatibility checks while conserving backend resources.

Client-Side wait_timeout Support (abe16e6, #4901)
Previously, ProxySQL ignored client-specified wait_timeout values, using only the global mysql-wait_timeout setting. Now, ProxySQL respects client timeout requests, terminating client connections (but not backend connections) when the client timeout is reached. As a safety measure, client timeouts are clamped to not exceed the global mysql-wait_timeout value.

Fast Forward Grace Close Feature to Prevent Data Loss (44aa606, #5203)
For fast-forward replication sessions, ProxySQL now implements graceful connection closure that ensures all pending data is flushed to the client before closing the connection. This prevents data loss during connection termination in replication scenarios, improving data consistency and reliability.

Monitoring & Diagnostics

Improved visibility into connection health and configuration issues:

TCP Keepalive Warnings When Disabled (cf454b8, #5228)
When TCP keepalive is disabled on connections, ProxySQL now emits warning messages to help administrators identify potential connection stability issues. These warnings include detailed connection information for troubleshooting, making it easier to detect misconfigured environments that might experience unexpected connection drops.

Bug Fixes

This release addresses several critical issues affecting thread safety, caching behavior, monitoring accuracy, and security:

MySQL

Make cur_cmd_cmnt Thread-Safe (91e2064, #5259)
The cur_cmd_cmnt (current command comment) variable was shared across threads, creating potential race conditions in multi-threaded environments. This fix ensures thread-safe access, preventing inconsistent behavior when multiple threads process queries simultaneously.

Fix cache_empty_result=0 Not Caching Non-Empty Resultsets (2987242, #5250)
The cache_empty_result field in query rules had incorrect behavior when set to "0". Previously, it prevented caching of any resultsets regardless of row count. Now, it correctly caches non-empty resultsets while skipping empty resultsets, aligning with the documented behavior and improving cache efficiency.

Incorrect Affected Rows Reporting for DDL Queries (05960b5, #5232)
Issue #4855 identified that mysql_affected_rows() in the ProxySQL Admin interface incorrectly reported affected rows for DDL queries, showing the previous DML's count instead of 0. DDL queries now correctly return 0 affected rows, providing accurate metadata to administrative tools and scripts.

Monitoring

Fix Artificially High Ping Latency in MySQL Backend Monitoring (24e02e9, #5199)
The MySQL backend monitor was reporting artificially high ping latency due to inefficient task dispatching. This fix introduces batching (batches of 30) with poll() calls between batches and reduces the monitor ping poll() timeout from 100ms to 10ms. These changes provide more responsive monitoring with accurate latency measurements.

Security & Configuration

Fix SQL Injection Vulnerability in Read_Global_Variables_from_configfile() (0b2bc1b, #5247)
A critical security vulnerability in configuration parsing has been addressed by replacing sprintf-based SQL query construction with prepared statements using bound parameters. The fix also handles automatic prefix stripping for mysql_variables, pgsql_variables, and admin_variables config parsing, preventing SQL injection attacks when users mistakenly include module prefixes (e.g., "mysql-") in variable names.

Improvements

Performance and stability enhancements across replication, prepared statements, and GTID handling:

Performance Optimizations

Improve Fast Forward Replication CLIENT_DEPRECATE_EOF Validation (5485bb0, #5240)
Enhanced validation logic for fast forward replication with the CLIENT_DEPRECATE_EOF capability flag ensures proper handling of replication packets and improves compatibility with MySQL 8.0+ clients. This prevents protocol mismatches and connection issues in replication scenarios.

Refactored Prepared-Statement Cache Design (Lock-Free Hot Path) (c0f99c0, #5225)
Significant performance improvements for high-concurrency workloads through a lock-free hot path for prepared statement cache operations. The redesign reduces contention by optimizing transaction command parsing to avoid unnecessary tokenization and replacing std::string with char[] to eliminate heap allocation in hot paths.

GTID: Refactor Reconnect Logic & Prevent events_count Reset (50c6028, #5226)
Refactored GTID reconnect logic prevents events_count from being reset during reconnection attempts, preserving replication state and reducing unnecessary replication restarts. This improves replication stability and reduces overhead during network interruptions.

Documentation

Extended documentation improves code maintainability and provides better guidance for developers and administrators:

Comprehensive Documentation Additions (cf8cbfd, #5258)
Extended documentation includes query rules capture groups and backreferences, "Closing killed client connection" warnings, coredump_filters feature addressing issue #5213, and vacuum_stats() with stats_pgsql_stat_activity Doxygen documentation including bug fixes.

Permanent Fast-Forward Sessions and check_data_flow() Documentation (ec1247f, #5245)
Documents behavior of permanent fast-forward sessions and the MySQL_Data_Stream::check_data_flow() method, explaining when bidirectional data checks are skipped for specific session types.

Claude Code Agent Definitions and Architecture Documentation (291e5f0, #5115)
Adds architecture documentation for Claude Code agent integration, including automation framework and internal documentation for AI-assisted development workflows.

Comprehensive Doxygen Documentation for GTID Refactoring (9a55e97, #5229)
Detailed Doxygen documentation for GTID-related code changes, improving code maintainability and developer onboarding.

TAP Test Writing Guide and GitHub Automation Improvements (4989960, #5215)
Provides a comprehensive guide for writing TAP tests for ProxySQL and improves GitHub automation workflows for continuous integration.

Testing

Enhanced test coverage and infrastructure improvements ensure reliability:

Add Comments to SELECT @@version Queries to Bypass ProxySQL Interception (66119b7, #5251)
Adds /* set_testing */ comments to SELECT @@version queries in test files, preventing ProxySQL interception and allowing queries to reach backend MySQL servers for accurate testing.

Add Fast Forward Replication Deprecate EOF Test and Update Test Infrastructure (9df7407, #5241)
Adds comprehensive test coverage for fast forward replication CLIENT_DEPRECATE_EOF validation and updates test infrastructure to better handle replication scenarios.

Add Delay to Let ProxySQL Process mysql_stmt_close() (fa74de3, #5198)
Adds appropriate delays in tests to allow ProxySQL time to process mysql_stmt_close() operations, preventing race conditions in prepared statement tests.

Regroup Tests to Balance Group Test Time (458ff77, #5207)
Reorganizes test groups to balance execution time across test runners, improving CI pipeline efficiency and reducing overall test runtime.

Build/Packaging

Expanded platform support for broader deployment options:

Add OpenSUSE 16 Packaging Support (bce71a9, #5230)
Adds packaging support for OpenSUSE 16, expanding the supported distribution matrix for ProxySQL installations and making it easier for OpenSUSE users to deploy ProxySQL.

Other Changes

Administrative updates for better development workflow:

Bump Version to 3.0.4 at Beginning of Development Cycle (ba66478, #5200)
Updates version number to 3.0.4 at the start of the development cycle for clarity and version tracking, ensuring consistent version references throughout the development process.

Hashes

The release commit is: faa64a570d19fe35af43494db0babdee3e3cdc89

Full Changelog: 3.0.3...v3.0.4

Hashes

SHA256s:

69326e308e1fb3c008f9be70de5db3cf489a8c63de5d07ce5b0aaed3f34a51bb  proxysql-3.0.4-1-almalinux10-clang.x86_64.rpm
d49b6c54f5bebb7d65ae84452f3fea26a1d96c98aecceb39500ec41ff78b2328  proxysql-3.0.4-1-almalinux10.aarch64.rpm
c8997b177fdeca484f968e64acc9790a787f3d339827a44c1ffe0630eb237c20  proxysql-3.0.4-1-almalinux10.x86_64.rpm
991dd503ea459bbb93dd537cf007f307c5f99b797848303ab362fa2fd640afdd  proxysql-3.0.4-1-almalinux8-clang.x86_64.rpm
101e38f76d3b344496f34002cf39aa735bd101a90aec0534276f0516c4b394d1  proxysql-3.0.4-1-almalinux8.aarch64.rpm
891f62418453a65c936ed9e05a351513505823e230a52bad7b1a3a5dfd79ac9b  proxysql-3.0.4-1-almalinux8.x86_64.rpm
580412ae44d2b5be020776a7d2367f200844dcd40ae4bb3aaffd2f28a39bdd8b  proxysql-3.0.4-1-almalinux9-clang.x86_64.rpm
50aa8bcf3da2e4b1a6b16f752baea4be2a48fb272582bcc58c841e64c532d683  proxysql-3.0.4-1-almalinux9.aarch64.rpm
177b833070db61f9aaf4bbe563a412c593f044fdecc914ba8b3cd661a1719540  proxysql-3.0.4-1-almalinux9.x86_64.rpm
0dd6faba9f68de9ea5ea7f4ed24d7b9aab8858048410c3aa0828d3297c92802e  proxysql-3.0.4-1-centos10-clang.x86_64.rpm
8842ae1072114c8bdd5f418a4306e98db35176470ba4007b6193b214a1e44313  proxysql-3.0.4-1-centos10.aarch64.rpm
475995a07651cecb15c3d843a8c62fcef13b55ad0e6e0ef825e8353d115ea0b1  proxysql-3.0.4-1-centos10.x86_64.rpm
2968215298eac0ba1675ece992fb6500059c4924aa47ea490819b6e65185743c  proxysql-3.0.4-1-centos9-clang.x86_64.rpm
557be6544f499c8722933114dfe7f2bcc1e6b21b8bc1d78adbcef8652a1664a4  proxysql-3.0.4-1-centos9.aarch64.rpm
8a12e46f5851e1ac8aa4a6248fd0a979e6a2fd03230bfa2ee8274a5164007d52  proxysql-3.0.4-1-centos9.x86_64.rpm
24eb83800b168062ae08d756fa237a7fe74c3c6ccf2c9082cd3a5a64941b6d32  proxysql-3.0.4-1-dbg-almalinux10.x86_64.rpm
48353f39dc8886bcb8319dd98a052fc73afda7e7e86cdc238142bc10a6cc42c6  proxysql-3.0.4-1-dbg-almalinux8.x86_64.rpm
0fc68e5d47befdcfcb2b4abe6f735677d6466f432a3b2f0612364ad67278d3f4  proxysql-3.0.4-1-dbg-almalinux9.x86_64.rpm
66647218b7fb956feb4538eb8822b45fb4828f923ef774e72ebe85988ea01e49  proxysql-3.0.4-1-dbg-centos10.x86_64.rpm
b3bf244ebf4ea5917b71f52a79f84cae8c3f5b92d85258c006c855ade67f3a77  proxysql-3.0.4-1-dbg-centos9.x86_64.rpm
9e65fd8f17d3c327cb4f2406172dcafc405a15fa0d7a89534822f78df8cb3a00  proxysql-3.0.4-1-dbg-fedora40.x86_64.rpm
4c1db9224b75cc61b9f8e250888d2791af3cfbe8348d8c6e04d9500a2428a0a5  proxysql-3.0.4-1-dbg-fedora41.x86_64.rpm
b39986a4c3a9ca2c36293aae10b99ae2b996834dfff31fe9aac6d1d9706e8bf8  proxysql-3.0.4-1-dbg-fedora42.x86_64.rpm
8589d96dc55447f8a5df08c0fbb952f4fb490fafd66e8085b1a2d428a74c9031  proxysql-3.0.4-1-dbg-opensuse15.x86_64.rpm
ee1789443f9c606518699056a46b056a03393fa1bd4e1925355adb053d431b1e  proxysql-3.0.4-1-dbg-opensuse16.x86_64.rpm
c3d6da7d0047c761c41b3a05e717e2585d0394609e730274704f023049c3780f  proxysql-3.0.4-1-fedora40-clang.x86_64.rpm
1c5a145dcd5197d039ff885e928425a1317150651bff5f32a0302e5bc98b542f  proxysql-3.0.4-1-fedora40.aarch64.rpm
afbdc3cab43071798bf694ad28f9fc8be87a904687b32ed6d92ee5c2df2cc86b  proxysql-3.0.4-1-fedora40.x86_64.rpm
76d3c811d01cec2bed9fa13d06bcc23c7f5ca644c11cadba56e03fc7bb770941  proxysql-3.0.4-1-fedora41-clang.x86_64.rpm
0d3e85e62950f12ee495d79e65ff4cb442d12d027ab6984fa8488c6e078f2a8d  proxysql-3.0.4-1-fedora41.aarch64.rpm
ba0839e6970875cdba5561d32603d93652aa576c5d1b198d66e406412d5f2c24  proxysql-3.0.4-1-fedora41.x86_64.rpm
99ec03eefc07d35a2c8bcf1599bf5bf1fc3bdfe0d24110120d0a6ec8491c36cd  proxysql-3.0.4-1-fedora42-clang.x86_64.rpm
30aa310d831bc332208b5cb686453cbf66ff156faa866a33e2850970edda9e16  proxysql-3.0.4-1-fedora42.aarch64.rpm
08b1dcadf9b071c8b2f587f7861d4cb1d2128466f3f66ae5ffc57738fd55434c  proxysql-3.0.4-1-fedora42.x86_64.rpm
ad97c781257320212e4051af628b11f524da82186ffef1d48880e68792189ec3  proxysql-3.0.4-1-opensuse15-clang.x86_64.rpm
0e21a08fdd2e68725a1a0d8eb4b3f70be953003cac4d7d3b51a256c299e4dc5b  proxysql-3.0.4-1-opensuse15.aarch64.rpm
8be2a815dcfb694c1f127afddd689912e58d6b0ce54bfc54dca40d3be1c05967  proxysql-3.0.4-1-opensuse15.x86_64.rpm
7e524f0d55a4080ebe4c7ee15c9f9e36c0ed5cdfb4410db80442ac839d422896  proxysql-3.0.4-1-opensuse16-clang.x86_64.rpm
3f7807a07330d25eb82fc1554516a36beaed04b04a6136bf05872c602f69dbbe  proxysql-3.0.4-1-opensuse16.aarch64.rpm
c352f20aa5babfde5d7513b796841f6b9e52934d141497b6915182e97df6a959  proxysql-3.0.4-1-opensuse16.x86_64.rpm
ce28457365d3a564f8f7f689c625fcc12ad8efc142a4d217741bf81ec6b1cd9b  proxysql-3.0.4.id-hash
973c8b8a1d201b258684a012085c9f8d899d6f023601f39e093bdb2f5bc124c0  proxysql_3.0.4-dbg-debian12_amd64.deb
7088c4757dcf69dace7af6b89f50f376f88c721c7f8b6585752039e815d8ff68  proxysql_3.0.4-dbg-debian13_amd64.deb
bb43226da8f3450497e5cc90bd36229e375ca9919c15fbec74025260f744183e  proxysql_3.0.4-dbg-ubuntu22_amd64.deb
89fe964825ba5c7272291847fbd4cd5eb74a4b567e0b672cc82f9f2bbeb32e20  proxysql_3.0.4-dbg-ubuntu24_amd64.deb
a38943a535211e1ad7a3885e3275ff884b345cfa8476f14650422bead2098ebe  proxysql_3.0.4-debian12-clang_amd64.deb
fe4b433dadc6393153b509a890d7dfcf7aa8eea5b4690352b5d8ab36d73b8c74  proxysql_3.0.4-debian12_amd64.deb
7b4f0bb471b9d34b7fdc83f1c8c7786e7246b2d2da2894b9e11cdf9622620a81  proxysql_3.0.4-debian12_arm64.deb
c0c78bcd64cd09c152a018fe98b40d3b859202eb71f53c8c54009264ca3fb708  proxysql_3.0.4-debian13-clang_amd64.deb
399347fba99cfd93fd38ad21d7ca6662a95c70e09f15fd27e37139d81b12090a  proxysql_3.0.4-debian13_amd64.deb
37284d80c7dc036f6f2b65c3492150f5e271d348bcd325a4c24607916ada1a38  proxysql_3.0.4-debian13_arm64.deb
90652c0ccdf5d8f501c50d91cfcc3fa0bf352a09fb8baa4799bb7ab6d51dc818  proxysql_3.0.4-ubuntu22-clang_amd64.deb
98f61e9914098d25b1c6bd6af74c1cd743dd3d80f2ceb7e0d3bdea88d275a30f  proxysql_3.0.4-ubuntu22_amd64.deb
808305aa58135f5d2ca2b3a7917e4b4f7c1ddb4fa5c4f455cfb9b16c5f5ad3a3  proxysql_3.0.4-ubuntu22_arm64.deb
3d82960ca9a44b36a18eafa428c5af6daeedb40b292e691763e3748f7c5b9048  proxysql_3.0.4-ubuntu24-clang_amd64.deb
5983ed2f0e29cda6ece36fdf24460ec29722dad8344e0098b82ebe963274062c  proxysql_3.0.4-ubuntu24_amd64.deb
9d929e4a939d23469534a2fb6421b5afcd0a8151d57a8ea82db5adfc5e6f4ad4  proxysql_3.0.4-ubuntu24_arm64.deb