{"id":13453030,"url":"https://github.com/sysown/proxysql","last_synced_at":"2026-01-16T22:57:22.236Z","repository":{"id":23975321,"uuid":"27358084","full_name":"sysown/proxysql","owner":"sysown","description":"High-performance MySQL proxy with a GPL license.","archived":false,"fork":false,"pushed_at":"2025-05-08T23:05:56.000Z","size":480607,"stargazers_count":6250,"open_issues_count":1151,"forks_count":1013,"subscribers_count":243,"default_branch":"v3.0","last_synced_at":"2025-05-09T00:18:40.679Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://www.proxysql.com","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sysown.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-12-01T01:58:26.000Z","updated_at":"2025-05-08T23:06:01.000Z","dependencies_parsed_at":"2023-10-11T21:00:44.761Z","dependency_job_id":"1368ce28-5681-4da3-8583-cab637f1d748","html_url":"https://github.com/sysown/proxysql","commit_stats":{"total_commits":5512,"total_committers":143,"mean_commits":38.54545454545455,"dds":"0.47115384615384615","last_synced_commit":"5cc418bb6c59aefca2bc21232e21de6f240a49cf"},"previous_names":[],"tags_count":207,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysown%2Fproxysql","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysown%2Fproxysql/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysown%2Fproxysql/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sysown%2Fproxysql/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sysown","download_url":"https://codeload.github.com/sysown/proxysql/tar.gz/refs/heads/v3.0","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253765193,"owners_count":21960687,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T08:00:31.274Z","updated_at":"2026-01-16T22:57:22.229Z","avatar_url":"https://github.com/sysown.png","language":"C++","funding_links":[],"categories":["C++","Uncategorized","\u003ca name=\"cpp\"\u003e\u003c/a\u003eC++","C/C++","数据库、分布存储相关","Proxy"],"sub_categories":["Uncategorized"],"readme":"[![CI-selftests](https://github.com/sysown/proxysql/actions/workflows/CI-selftests.yml/badge.svg)](https://github.com/sysown/proxysql/actions/workflows/CI-selftests.yml)\n[![CI-repltests](https://github.com/sysown/proxysql/actions/workflows/CI-repltests.yml/badge.svg)](https://github.com/sysown/proxysql/actions/workflows/CI-repltests.yml)\n[![CodeQL](https://github.com/sysown/proxysql/actions/workflows/CI-codeql.yml/badge.svg)](https://github.com/sysown/proxysql/actions/workflows/CI-codeql.yml)\n[![Package-Build](https://github.com/sysown/proxysql/actions/workflows/CI-package-build.yml/badge.svg)](https://github.com/sysown/proxysql/actions/workflows/-CI-package-build.yml)\n\n\u003ca\u003e\u003cimg src=\"https://i0.wp.com/proxysql.com/wp-content/uploads/2020/04/ProxySQL-Colour-Logo.png?fit=800%2C278\u0026ssl=1\" alt=\"ProxySQL\"\u003e\u003c/a\u003e\n\nTable of Contents\n=================\n\n- [Introduction](#introduction)\n- [Useful links](#useful-links)\n- [Getting started](#getting-started)\n  - [Installation](#installation)\n    - [Ubuntu / Debian](#ubuntu--debian)\n    - [Red Hat / CentOS](#red-hat--centos)\n    - [Amazon Linux](#amazon-linux)\n    - [Almalinux](#almalinux)\n    - [OpenSUSE](#opensuse)\n    - [FreeBSD](#freebsd)\n  - [Service management](#service-management)\n    - [Starting ProxySQL](#starting-proxysql)\n    - [Stopping ProxySQL](#stopping-proxysql)\n    - [Restarting ProxySQL](#restarting-proxysql)\n    - [Reinitializing ProxySQL](#reinitializing-proxysql-from-the-config-file-after-first-startup-the-db-file-is-used-instead-of-the-config-file)\n  - [Upgrades](#upgrades)\n  - [How to check the ProxySQL version](#how-to-check-the-proxysql-version)\n  - [Configuring ProxySQL via the admin interface](#configuring-proxysql-via-the-admin-interface)\n    - [Configuring ProxySQL through the admin interface](#configuring-proxysql-through-the-admin-interface)\n    - [Configuring ProxySQL through the config file](#configuring-proxysql-through-the-config-file)\n\nIntroduction\u003ca name=\"introduction\"\u003e\u003c/a\u003e\n============\n\nProxySQL is a high-performance, high-availability, protocol-aware proxy for MySQL and its forks (such as Percona Server and MariaDB), as well as PostgreSQL.\nAll the while getting the unlimited freedom that comes with a GPL license.\n\nIts development is driven by the lack of open source proxies that provide high performance.\n\nUseful links\u003ca name=\"useful-links\"\u003e\u003c/a\u003e\t\n===============\t\n\n- [Official website](https://www.proxysql.com/)\t\n- [Subscriptions and Support](https://proxysql.com/services/support/) \n- [Documentation](https://www.proxysql.com/Documentation)\n- [DockerHub Repository](https://hub.docker.com/r/proxysql/proxysql)\n- [Benchmarks and blog posts](http://www.proxysql.blogspot.com/)\t\n- [Forum](https://groups.google.com/forum/#!forum/proxysql/)\n- [Facebook](https://www.facebook.com/proxysql)\t\n- [Linkedin](https://www.linkedin.com/groups/13581070/)\t\n- [Twitter](https://twitter.com/proxysql)\n\nGetting started\u003ca name=\"getting-started\"\u003e\u003c/a\u003e\n===============\n\n### Installation\nReleased packages can be found here: https://github.com/sysown/proxysql/releases\n\nJust download a package and use your systems package manager to install it:\n```bash\nwget https://github.com/sysown/proxysql/releases/download/v3.0.4/proxysql_3.0.4-ubuntu24_amd64.deb\ndpkg -i proxysql_3.0.4-ubuntu24_amd64.deb\n```\n\nAlternatively you can also use the available repositories:\n\n#### Ubuntu / Debian:\n\nAdding repository:\n```bash\napt-get update \u0026\u0026 apt-get install -y --no-install-recommends lsb-release wget apt-transport-https ca-certificates\nwget -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'\necho \"deb https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/$(lsb_release -sc)/ ./\" | tee /etc/apt/sources.list.d/proxysql.list\n```\n\nInstalling:\n```bash\napt-get update\napt-get install proxysql OR apt-get install proxysql=version\n```\n\n#### Red Hat / CentOS:\n\nAdding repository:\n```bash\ncat \u003e /etc/yum.repos.d/proxysql.repo \u003c\u003c EOF\n[proxysql]\nname=ProxySQL YUM repository\nbaseurl=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/centos/\\$releasever\ngpgcheck=1\ngpgkey=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/repo_pub_key\nEOF\n```\n\nInstalling:\n```bash\nyum install proxysql OR yum install proxysql-version\n```\n\n#### Amazon Linux:\n\nAdding repository:\n```bash\ncat \u003e /etc/yum.repos.d/proxysql.repo \u003c\u003c EOF\n[proxysql]\nname=ProxySQL YUM repository\nbaseurl=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/centos/8\ngpgcheck=1\ngpgkey=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/repo_pub_key\nEOF\n```\n\nInstalling:\n```bash\nyum install proxysql OR yum install proxysql-version\n```\n\n#### Almalinux:\n\nAdding repository:\n```bash\ncat \u003e /etc/yum.repos.d/proxysql.repo \u003c\u003c EOF\n[proxysql]\nname=ProxySQL YUM repository\nbaseurl=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/almalinux/\\$releasever\ngpgcheck=1\ngpgkey=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/repo_pub_key\nEOF\n```\n\nInstalling:\n```bash\nyum install proxysql OR yum install proxysql-version\n```\n\n#### OpenSUSE:\n\nAdding repository:\n```bash\ncat \u003e /etc/zypp/repos.d/proxysql.repo \u003c\u003c EOF\n[proxysql]\nname=ProxySQL Zypper repository\nenabled=1\nautorefresh=0\nbaseurl=https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/opensuse/\\$releasever_major\ngpgcheck=1\nEOF\n```\nor\n```bash\nzypper addrepo -g -n 'ProxySQL Zypper repository' 'https://repo.proxysql.com/ProxySQL/proxysql-3.0.x/opensuse/$releasever_major' proxysql\n```\n\nInstalling:\n```bash\nyum install proxysql OR yum install proxysql-version\n```\n\n#### FreeBSD:\n\nInstalling (via pkg):\n```bash\npkg install proxysql\n```\n\nInstalling (via ports):\n```bash\ncd /usr/ports/databases/proxysql/ \u0026\u0026 make install clean\n```\n\n### Service management\nOnce the software is installed, you can use the `service` command to control the process:  \n\n#### Starting ProxySQL:\n```bash\nservice proxysql start\n```\n#### Stopping ProxySQL:\n```bash\nservice proxysql stop\n```\n\nOr alternatively via the Admin interface (MySQL admin example):\n```\n$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin\u003e '\nWarning: Using a password on the command line interface can be insecure.\nWelcome to the MySQL monitor.  Commands end with ; or \\g.\nYour MySQL connection id is 4\nServer version: 5.5.30 (ProxySQL Admin Module)\n\nCopyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.\n\nOracle is a registered trademark of Oracle Corporation and/or its\naffiliates. Other names may be trademarks of their respective\nowners.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nAdmin\u003e proxysql stop\n```\n\nFor PostgreSQL admin interface the same Admin commands apply and the admin port defaults to 6132. \nYou can connect using the psql client as follows:\n```\n$ export PGPASSWORD=admin\n$ psql -U admin -h 127.0.0.1 -p6132\npsql (17.4 (Ubuntu 17.4-1.pgdg22.04+2), server 16.1)\nSSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)\nType \"help\" for help.\n\nadmin=# proxysql stop\n```\n\n_(The examples above show the Admin interface workflow - the Admin SQL commands are the same for both MySQL and PostgreSQL modes.)_\n\n#### Restarting ProxySQL:\n```bash\nservice proxysql restart\n```\n\nOr alternatively via the Admin interface (MySQL example):\n```\n$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin\u003e '\nWarning: Using a password on the command line interface can be insecure.\nWelcome to the MySQL monitor.  Commands end with ; or \\g.\nYour MySQL connection id is 4\nServer version: 5.5.30 (ProxySQL Admin Module)\n\nCopyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.\n\nOracle is a registered trademark of Oracle Corporation and/or its\naffiliates. Other names may be trademarks of their respective\nowners.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nAdmin\u003e proxysql restart\n```\n\nOr via the PostgreSQL admin port:\n```\n$ export PGPASSWORD=admin\n$ psql -U admin -h 127.0.0.1 -p6132\npsql (17.4 (Ubuntu 17.4-1.pgdg22.04+2), server 16.1)\nSSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)\nType \"help\" for help.\n\nadmin=# proxysql restart\n```\n\n#### Reinitializing ProxySQL from the config file (after first startup the DB file is used instead of the config file):\n```bash\n# If you are using the init script run:\n/etc/init.d/proxysql initial\n# or\nservice proxysql initial\n \n# If you are using the systemd unit file run:\nsystemctl start proxysql-initial\n# or\nservice proxysql-initial start\n```\n\n### Upgrades\nJust install the new package and restart ProxySQL:\n```bash\nwget https://github.com/sysown/proxysql/releases/download/v3.0.4/proxysql_3.0.4-ubuntu24_amd64.deb\ndpkg -i proxysql_3.0.4-ubuntu24_amd64.deb\nservice proxysql restart\n```\n\n### How to check the ProxySQL version\n```bash\n$ proxysql --version\n```\n```bash\nProxySQL version 3.0.4-162-gfaa64a5, codename Truls\n```\nA debug version has `_DEBUG` in its version string.\nIt is slower than non-debug version, but easier to debug in case of failures.\n```bash\n$ proxysql --version\n```\n```bash\nProxySQL version 3.0.4-162-gfaa64a5_DEBUG, codename Truls\n```\n\n### Configuring ProxySQL via the `admin interface`\n\nFirst 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.\n\nAs a secondary way to configure it, we have the configuration file. \n\n#### Configuring ProxySQL through the admin interface\n\nTo log into the admin interface for MySQL (with the default credentials) use a mysql client and connect using the following `admin` credentials locally on port (6032):\n```bash\n$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin\u003e '\nWarning: Using a password on the command line interface can be insecure.\nWelcome to the MySQL monitor.  Commands end with ; or \\g.\nYour MySQL connection id is 4\nServer version: 5.5.30 (ProxySQL Admin Module)\n\nCopyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.\n\nOracle is a registered trademark of Oracle Corporation and/or its\naffiliates. Other names may be trademarks of their respective\nowners.\n\nType 'help;' or '\\h' for help. Type '\\c' to clear the current input statement.\n\nAdmin\u003e\n```\nnote: 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.\n\nTo log into the admin interface for PostgreSQL use the psql client and connect using admin on port 6132 (the Admin SQL commands are the same):\n```bash\n$ export PGPASSWORD=admin\n$ psql -U admin -h 127.0.0.1 -p6132\npsql (17.4 (Ubuntu 17.4-1.pgdg22.04+2), server 16.1)\nSSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off, ALPN: none)\nType \"help\" for help.\n\nadmin=#\n```\nOnce connected to the admin interface, you will have a list of databases and tables at your disposal that can be queried using the SQL language:\n```mysql\nAdmin\u003e SHOW DATABASES;\n+-----+---------+-------------------------------+\n| seq | name    | file                          |\n+-----+---------+-------------------------------+\n| 0   | main    |                               |\n| 2   | disk    | /var/lib/proxysql/proxysql.db |\n| 3   | stats   |                               |\n| 4   | monitor |                               |\n+-----+---------+-------------------------------+\n4 rows in set (0.00 sec)\n```\nThis 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 [here](https://github.com/sysown/proxysql/wiki/ProxySQL-Configuration).\n\n#### Configuring ProxySQL through the config file\n\nEven 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.\n\nLet's quickly go over the main sections of the configuration file (this overview serves as a very high level overview of ProxySQL configuration).\n\nTop-level sections:\n* `admin_variables`: contains global variables that control the functionality of the admin interface.\n* `mysql_variables`: contains global variables that control the functionality for handling the incoming MySQL traffic.\n* `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:\n\t\n\t```bash\n\tmysql_servers =\n\t(\n\t\t{\n\t\t\taddress=\"127.0.0.1\"\n\t\t\tport=3306\n\t\t\thostgroup=0\n\t\t\tmax_connections=200\n\t\t}\n\t)\n\t```\n* `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:\n\t\n\t```bash\n\tmysql_users:\n\t(\n\t\t{\n\t\t\tusername=\"root\"\n\t\t\tpassword=\"root\"\n\t\t\tdefault_hostgroup=0\n\t\t\tmax_connections=1000\n\t\t\tdefault_schema=\"information_schema\"\n\t\t\tactive=1\n\t\t}\n\t)\n\t```\n* `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):\n\t\n\t```bash\n\tmysql_query_rules:\n\t(\n\t\t{\n\t\t\trule_id=1\n\t\t\tactive=1\n\t\t\tmatch_pattern=\"^SELECT .* FOR UPDATE$\"\n\t\t\tdestination_hostgroup=0\n\t\t\tapply=1\n\t\t},\n\t\t{\n\t\t\trule_id=2\n\t\t\tactive=1\n\t\t\tmatch_pattern=\"^SELECT\"\n\t\t\tdestination_hostgroup=1\n\t\t\tapply=1\n\t\t}\n\t)\n\t```\n* `pgsql_variables`: contains global variables that control the functionality for handling the incoming PostgreSQL traffic.\n* `pgsql_servers`: contains rows for the `pgsql_servers` table from the admin interface. Basically, these define the backend servers towards which the incoming PostgreSQL traffic is routed. Rows are encoded as per the `.cfg` file format, here is an example:\n\t\n\t```bash\n\tpgsql_servers =\n\t(\n\t\t{\n\t\t\taddress=\"127.0.0.1\"\n\t\t\tport=5432\n\t\t\thostgroup=0\n\t\t\tmax_connections=200\n\t\t}\n\t)\n\t```\n* `pgsql_users`: contains rows for the `pgsql_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:\n\t\n\t```bash\n\tpgsql_users:\n\t(\n\t\t{\n\t\t\tusername=\"postgres\"\n\t\t\tpassword=\"postgres\"\n\t\t\tdefault_hostgroup=0\n\t\t\tmax_connections=1000\n\t\t\tactive=1\n\t\t}\n\t)\n\t```\n* `pgsql_query_rules`: contains rows for the `pgsql_query_rules` table from the admin interface. Basically, these define the rules used to classify and route the incoming PostgreSQL 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):\n\t\n\t```bash\n\tpgsql_query_rules:\n\t(\n\t\t{\n\t\t\trule_id=1\n\t\t\tactive=1\n\t\t\tmatch_pattern=\"^SELECT .* FOR UPDATE$\"\n\t\t\tdestination_hostgroup=0\n\t\t\tapply=1\n\t\t},\n\t\t{\n\t\t\trule_id=2\n\t\t\tactive=1\n\t\t\tmatch_pattern=\"^SELECT\"\n\t\t\tdestination_hostgroup=1\n\t\t\tapply=1\n\t\t}\n\t)\n\t```\n* top-level configuration item: `datadir`, as a string, to point to the data dir.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysown%2Fproxysql","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsysown%2Fproxysql","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsysown%2Fproxysql/lists"}