Skip to content
Percona Software for MySQL Documentation

Rate this page
☆ ☆ ☆ ☆ ☆
Thanks for your feedback
Thank you! The feedback has been submitted.

Get free database assistance or contact our experts for personalized support.

Get help from Percona

Install Percona build of ProxySQL and the admin tools

This task guide installs the Percona build of ProxySQL and Percona admin tools with a package manager.

Use the same package manager that installs Percona XtraDB Cluster or other Percona software. Matching package managers ensures repository compatibility.

For tarball or offline installs, see the tarball installation guide or the download locations guide.

Recommended version

Install the latest ProxySQL 3 release with the proxysql3 package. Use proxysql2 only for an existing ProxySQL 2.x deployment or a version lock. See release notes for the current ProxySQL 3 version.

Install ProxySQL with a package manager

Select the tab that matches your Linux distribution.

Use APT when Percona software is installed from APT repositories. Run one of the following commands as root or with sudo.

For ProxySQL 3 (recommended):

$ sudo apt install proxysql3

For ProxySQL 2 (legacy deployments only):

$ sudo apt install proxysql2
Expected output 
Reading package lists... Done
Building dependency tree
Reading state information... Done
The following additional packages will be installed:
  debconf-utils logrotate
The following NEW packages will be installed:
  debconf-utils logrotate proxysql2
0 upgraded, 3 newly installed, 0 to remove and 3 not upgraded.
Need to get 7259 kB of archives.
...

Use YUM or DNF when Percona software is installed from YUM repositories. Run one of the following commands as root or with sudo.

For ProxySQL 3 (recommended):

$ sudo yum install proxysql3

For ProxySQL 2 (legacy deployments only):

$ sudo yum install proxysql2
Expected output 
Last metadata expiration check: 0:01:47 ago on Wed Oct  5 14:42:00 2022.
Dependencies resolved.
=========================================================================================================================
Package                  Architecture          Version                        Repository                           Size
=========================================================================================================================
Installing:
proxysql2                x86_64                2.4.4-1.1.el8                  tools-release-x86_64                 21 M
Installing dependencies:
logrotate                x86_64                3.14.0-4.el8                   baseos                               85 k

Transaction Summary
=========================================================================================================================
Install  2 Packages

Total download size: 21 M
Installed size: 88 M
Is this ok [y/N]: y
Downloading Packages:
(1/2): logrotate-3.14.0-4.el8.x86_64.rpm                                                 371 kB/s |  85 kB     00:00
(2/2): proxysql2-2.4.4-1.1.el8.x86_64.rpm                                                3.6 MB/s |  21 MB     00:05
-------------------------------------------------------------------------------------------------------------------------
Total                                                                                    3.3 MB/s |  21 MB     00:06
...

Verify pxc_scheduler_handler installation

ProxySQL 3 releases and ProxySQL 2.3.2-1.2 and later 2.x releases include pxc_scheduler_handler. Verify the installation with the following command:

$ percona-scheduler-admin --debug

Without the pxc_scheduler_handler configuration file, the command reports an error.

Error message 
ERROR : The --config-file option is required but is missing from the command.

Run ProxySQL in Docker

Pull a Docker image from one of the following repositories:

MySQL 8.4 and Percona Server for MySQL 8.4 considerations

In an MySQL 8.4 or Percona Server for MySQL 8.4 environment, you may have the following issues:

  • ProxySQL contains counters that have not been updated to use the new terminology. Unexpected results may occur
  • The binlog reader errors out during initialization due to the use of the old terminology, such as SHOW MASTER STATUS command.
Last update: 2026-06-12