ProxySQL: a protocol-aware proxy for MySQL and PostgreSQL

What ProxySQL is for, and who ends up running it

The README states the motivation plainly: development is driven by the lack of open source proxies that provide high performance. ProxySQL is a protocol-aware proxy, which means it parses the MySQL and PostgreSQL wire protocols rather than forwarding opaque TCP streams. That distinction decides who it is for. A team that only needs to spread connections across identical replicas can do that with a TCP load balancer. A team that wants to send writes to a primary, reads to replicas, cache a repeated query, or fail over when a backend stops answering needs something that understands the statements passing through it. ProxySQL targets MySQL and its forks (Percona Server and MariaDB are named explicitly) as well as PostgreSQL. It is licensed GPL-3.0, and the README frames that as part of the pitch: unlimited freedom that comes with a GPL license. It is not archived and the last push was on 2026-09-21.

Protocol awareness, query rules and the runtime configuration model

Two mechanisms define how ProxySQL behaves. The first is protocol parsing: because it speaks the client protocol, it can inspect queries and apply rules to them, which is what makes read/write splitting, query caching and per-query routing possible at all. The second is the configuration model. ProxySQL keeps a running configuration in memory and a persisted copy in a database file. The README notes that after first startup the db file is used instead of the config file, which is the single most common source of confusion for new operators: editing proxysql.cnf after the first run changes nothing until you reinitialize. Configuration is normally done through the admin interface, a separate listener that accepts SQL-like statements for defining backends, users and rules, and the README documents both the admin interface route and the config file route. The repository layout reflects the scope: src/, include/, lib/, plugins/, doc/, and a docker/ tree with per-distribution build images. The Makefile describes three release tiers built from the same codebase. v3.0.x is the default stable tier. Setting PROXYSQL31=1 adds FFTO (Fast Forward Traffic Observer) and TSDB (Time Series Database subsystem) and increments the minor version. Setting PROXYSQL40=1 adds a four-phase plugin lifecycle, a pre-execution query-hook plugin ABI and shared Prometheus support on top of that. Those are build-time flags, not runtime toggles, so the tier is chosen when the binary is produced.

Installing ProxySQL and running a first configuration

The README points at the releases page for packages and shows a .deb install. The same page publishes .rpm packages and distribution-agnostic tarballs for any glibc 2.34+ Linux on amd64 or arm64. The tarball is the option when a .deb or .rpm is inconvenient; it embeds pinned OpenSSL 3.5.7 libraries, so it does not need host OpenSSL shared libraries, though GnuTLS remains a dynamic runtime dependency. The README is explicit that this vendoring is not a FIPS compliance claim.

wget https://github.com/sysown/proxysql/releases/download/v3.0.4/proxysql_3.0.4-ubuntu24_amd64.deb
dpkg -i proxysql_3.0.4-ubuntu24_amd64.deb

The README also documents repository installs for Ubuntu and Debian, Red Hat and CentOS, Amazon Linux, AlmaLinux and openSUSE. The Debian route adds the project keyring and a sources list entry, then installs the package:

apt-get update && apt-get install -y --no-install-recommends lsb-release wget apt-transport-https ca-certificates
wget -nv -O /etc/apt/trusted.gpg.d/proxysql-3.0.x-keyring.gpg 'https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/repo_pub_key.gpg'
echo "deb https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/$(lsb_release -sc)/ ./" | tee /etc/apt/sources.list.d/proxysql.list
apt-get update
apt-get install proxysql

If you prefer the tarball, the README shows verifying the checksum before extracting. The archive contains bin/proxysql, a sample etc/proxysql.cnf, the systemd units and helper tools.

sha256sum -c proxysql-<version>-linux-amd64.tar.gz.sha256
tar xzf proxysql-<version>-linux-amd64.tar.gz

After installation, the README documents starting, stopping, restarting and reinitializing the service. Reinitialization is the step that matters: it is what makes ProxySQL read the config file again after the db file has taken over. For a first real use, the documented path is to configure through the admin interface rather than by editing the config file, because the admin interface writes into the runtime configuration that the proxy actually uses. The README does not walk through a worked example of adding a backend host and a query rule, so plan to read the documentation site for that sequence rather than expecting the README to carry it.

Where ProxySQL is the wrong tool

The first limitation is the one the README itself creates: the config file stops being authoritative after first startup. If your deployment model is immutable configuration files managed by a config management system, you are fighting the design. You either reinitialize on every change or you drive the admin interface, and the admin interface is a network listener with credentials that you now have to protect.

The second is that protocol awareness is not free. Parsing every statement costs CPU that a byte-forwarding proxy does not spend, and the payoff only exists if you actually use routing, caching or rule matching. A single-primary setup with one read replica and no query rules gets little from ProxySQL that a simpler balancer would not provide.

The third is version tiering. The Makefile ties feature sets to build flags. FFTO and TSDB arrive with PROXYSQL31=1; the plugin lifecycle changes and the pre-execution query-hook ABI arrive with PROXYSQL40=1. If you install a v3.0.x package and then read documentation describing v4.0 plugin behaviour, the mismatch is yours to resolve. The README also states that the v4.0 MySQL Router compatibility plugin is not yet included in release packages, and that source builds install proxysql_mysql_router.so under /usr/lib/proxysql/plugins/. That is a feature you cannot get from a binary package today.

ProxySQL compared with a connection pooler

The closest comparison in the search data is PgBouncer, and the difference is architectural rather than a matter of tuning. PgBouncer is a connection pooler: it multiplexes client connections onto a smaller set of server connections and forwards PostgreSQL traffic. It does not parse SQL and does not decide which backend a statement should reach. ProxySQL parses the protocol, which is what lets it apply query rules, split reads from writes and cache results. If your problem is connection count, a pooler solves it with far less machinery. If your problem is that the application should not know which server is primary, a pooler cannot solve it at all. The same split applies to MySQL Router and MaxScale, both of which appear in the search data alongside ProxySQL. The honest framing is that ProxySQL is a routing and rule engine that also pools, not a pooler that happens to route.

Maintenance, upgrades and the GPL-3.0 licence

Maintenance looks healthy on the evidence available: the repository is not archived, the last push was on 2026-09-21, and three release lines (v4.0.11, v3.1.11 and v3.0.11) were published on 2026-08-27. The upgrade cost is the part worth planning for. Because the three tiers are built from one codebase behind flags, moving from v3.0.x to v3.1.x or v4.0.x is not only a version bump; it changes which subsystems are compiled in and, in the v4.0 case, changes the plugin lifecycle and adds a query-hook ABI. Test the tier you intend to run rather than assuming a package upgrade is equivalent.

On licensing: the project is GPL-3.0. The README presents the licence as a benefit, and for teams already comfortable with GPL software that is reasonable. The practical question is distribution. If you ship ProxySQL inside a product you distribute, the GPL-3.0 obligations attach to that distribution, and the project also sells subscriptions and support separately. This is a description of the licence, not legal advice; get your own counsel if you redistribute.

Editorial conclusion

Adopt ProxySQL if you run MySQL, Percona Server, MariaDB or PostgreSQL behind more than one backend and you need routing, failover or query caching that the application should not implement itself. Do not adopt it if you want a single static endpoint with no runtime configuration, or if you are not prepared to run the admin interface as a production surface. Verify first that the release tier you install matches the features you need: the Makefile ties v3.0.x, v3.1.x and v4.0.x to different feature sets, and the v4.0 MySQL Router plugin is not included in release packages.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. sysown/proxysql on GitHub