Getting started

    Just download a package and use your systems package manager to install it:

    Alternatively you can also use the available repositories:

    Ubuntu / Debian:

    Adding repository:

    1. apt-get install -y lsb-release
    2. wget -O - 'http://repo.proxysql.com/ProxySQL/repo_pub_key' | apt-key add -
    3. echo deb http://repo.proxysql.com/ProxySQL/proxysql-1.4.x/$(lsb_release -sc)/ ./ \
    4. | tee /etc/apt/sources.list.d/proxysql.list

    Installing:

    1. apt-get update
    2. apt-get install proxysql OR apt-get install proxysql=version

    Red Hat / CentOS:

    Adding repository:

    1. cat <<EOF | tee /etc/yum.repos.d/proxysql.repo
    2. [proxysql_repo]
    3. name= ProxySQL YUM repository
    4. baseurl=http://repo.proxysql.com/ProxySQL/proxysql-1.4.x/centos/\$releasever
    5. gpgcheck=1
    6. gpgkey=http://repo.proxysql.com/ProxySQL/repo_pub_key
    7. EOF

    Installing:

    1. yum install proxysql OR yum install proxysql-version

    Once the software is installed, you can use the command to control the process:

    Starting ProxySQL:

    1. service proxysql start

    Stopping ProxySQL:

    1. service proxysql stop

    Restarting ProxySQL:

    1. service proxysql restart

    Or alternatively via the Admin interface:

    1. $ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin> '
    2. Warning: Using a password on the command line interface can be insecure.
    3. Welcome to the MySQL monitor.  Commands end with ; or \g.
    4. Your MySQL connection id is 4
    5. Server version: 5.5.30 (ProxySQL Admin Module)
    7. Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
    9. Oracle is a registered trademark of Oracle Corporation and/or its
    10. owners.
    12. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
    14. Admin> proxysql restart

    Reinitializing ProxySQL from the config file (after first startup the DB file is used instead of the config file):

    1. service proxysql initial

    Just install the new package and restart ProxySQL:

    1. wget https://github.com/sysown/proxysql/releases/download/v1.4.9/proxysql_1.4.9-ubuntu16_amd64.deb
    2. dpkg -i proxysql_1.4.9-ubuntu16_amd64.deb
    3. service proxysql restart
    1. $ proxysql --version
    1. ProxySQL version v1.4.9-1.1, codename Truls

    A debug version has _DEBUG in its version string.It is slower than non-debug version, but easier to debug in case of failures.

    1. Main init phase0 completed in 0.000146 secs.
    2. ProxySQL version v1.4.9-1.1_DEBUG, codename Truls

    First of all, bear in mind that the best way to configure ProxySQL is through its admin interface. This lends itself to online configuration (without having to restart the proxy) via SQL queries to its admin database. It's an effective way to configure it both manually and in an automated fashion.

    As a secondary way to configure it, we have the configuration file.

    Configuring ProxySQL through the admin interface

    To log into the admin interface (with the default credentials) use a mysql client and connect using the following admin credentials locally on port (6032):

    1. $ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin> '
    2. Warning: Using a password on the command line interface can be insecure.
    3. Welcome to the MySQL monitor.  Commands end with ; or \g.
    4. Your MySQL connection id is 4
    5. Server version: 5.5.30 (ProxySQL Admin Module)
    6.  
    7. Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
    8.  
    9. Oracle is a registered trademark of Oracle Corporation and/or its
    10. affiliates. Other names may be trademarks of their respective
    11. owners.
    12.  
    13. Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
    14.  
    15. Admin>

    note: If your MySQL client version is version 8.04 or higher add —default-auth=mysql_native_password to the above command to connect to the admin interface.

    1. Admin> SHOW DATABASES;
    2. +-----+---------+-------------------------------+
    3. | seq | name    | file                          |
    4. +-----+---------+-------------------------------+
    5. | 0   | main    |                               |
    6. | 2   | disk    | /var/lib/proxysql/proxysql.db |
    7. | 3   | stats   |                               |
    8. | 4   | monitor |                               |
    9. +-----+---------+-------------------------------+
    10. 4 rows in set (0.00 sec)

    This will allow you to control the list of the backend servers, how traffic is routed to them, and other important settings (such as caching, access control, etc). Once you've made modifications to the in-memory data structure, you must load the new configuration to the runtime, or persist the new settings to disk (so that they are still there after a restart of the proxy). A detailed tutorial on how to configure ProxySQL through the Admin interface is available .

    Configuring ProxySQL through the config file

    Even though the config file should only be regarded as a secondary way to configure the proxy, we must not discard its value as a valid way to bootstrap a fresh ProxySQL install.

    Let's quickly go over the main sections of the configuration file (this overview serves as a very high level overview of ProxySQL configuration).

    Top-level sections:

    • admin_variables: contains global variables that control the functionality of the admin interface.

    • mysql_servers: contains rows for the mysql_servers table from the admin interface. Basically, these define the backend servers towards which the incoming MySQL traffic is routed. Rows are encoded as per the .cfg file format, here is an example:

    1.  mysql_servers =
    2.  (
    3.      {
    4.          address="127.0.0.1"
    5.          port=3306
    6.          hostgroup=0
    7.          max_connections=200
    8.      }
    9.  )
    • mysql_users: contains rows for the mysql_users table from the admin interface. Basically, these define the users which can connect to the proxy, and the users with which the proxy can connect to the backend servers. Rows are encoded as per the .cfg file format, here is an example:
    1.  mysql_users:
    2.  (
    3.      {
    4.          username = "root"
    5.          password = "root"
    6.          default_hostgroup = 0
    7.          max_connections=1000
    8.          default_schema="information_schema"
    9.          active = 1
    10.      }
    11.  )
    • mysql_query_rules: contains rows for the mysql_query_rules table from the admin interface. Basically, these define the rules used to classify and route the incoming MySQL traffic, according to various criteria (patterns matched, user used to run the query, etc.). Rows are encoded as per the .cfg file format, here is an example (Note: the example is a very generic query routing rule and it is recommended to create specific rules for queries rather than using a generic rule such as this):
    1.  mysql_query_rules:
    2.  (
    3.      {
    4.          rule_id=1
    5.          active=1
    6.          match_pattern="^SELECT .* FOR UPDATE$"
    7.          destination_hostgroup=0
    8.          apply=1
    9.      },
    10.      {
    11.          rule_id=2
    12.          active=1
    13.          match_pattern="^SELECT"
    14.          destination_hostgroup=1
    15.          apply=1
    16.      }
    • top-level configuration item: , as a string, to point to the data dir.