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.)

...

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...

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 aft...

Verified dependency bundle for d9f669a85c54a9b0073a0b23c6eea8a1add402ff7a5fa758579493577e180e27.

Verified dependency bundle for d65f89f68a09c13838d30fb33a008cb15c458ffdeb692643e5484988dd13400e.

Verified dependency bundle for b355651af3482843c44152b4d8ccf8af5916cb526143003902029267bc4cd424.

Verified dependency bundle for 6bb257d1b16543f75693742761b3bba9b61293d06b7930f4b03dcb9182ba481d.

Verified dependency bundle for f28ab89dd4b68b1bac825bb2421de82b6f25e9d78cb1a9cf0ebb9477b720fdb1.

Verified dependency bundle for f0d681611ee8cb9285439778076c6bdba2e922de8c4948f162c673d9c4ef3d84.

Verified dependency bundle for 694ac95289dda09ae9018158d70597c9602199fd33ba8ed63fc0f6daea87775b.