mirror of https://github.com/sysown/proxysql
The README.md on this branch was a stale copy of the ProxySQL project README. That was actively misleading -- anyone landing on the GH-Actions branch (e.g. by following a "Uses: .../ci-legacy-g1.yml@GH-Actions" link from a workflow run) saw the full project intro as if this were a normal development branch, when in fact only .github/workflows/ci-*.yml is meaningful here. Replace it with a focused README that: - States clearly that this is a CI-only branch and sends casual visitors back to v3.0 - Lists the files that actually matter (.github/workflows/ci-*.yml) - Points at doc/GH-Actions/README.md on v3.0 as the authoritative architecture reference - Provides a quick-reference cheatsheet for the three most common tasks: adding a new test group, modifying a reusable, deleting a reusable -- including the merge-order rule between this branch and v3.0 - Notes that everything else on this branch (source tree, docs, test directories) is vestigial and should not be edited here No changes to any workflow file.ci/gh-actions-readme-pointer
Rene Cannao
1 month ago
parent
1b3149e02e
commit
52130f7cc2
@ -1,330 +1,123 @@
|
||||
[](https://github.com/sysown/proxysql/actions/workflows/ci-selftests.yml)
|
||||
[](https://github.com/sysown/proxysql/actions/workflows/ci-repltests.yml)
|
||||
[](https://github.com/sysown/proxysql/actions/workflows/codeql.yml)
|
||||
[](https://github.com/sysown/proxysql/actions/workflows/package-build.yml)
|
||||
# `GH-Actions` branch
|
||||
|
||||
<a><img src="https://i0.wp.com/proxysql.com/wp-content/uploads/2020/04/ProxySQL-Colour-Logo.png?fit=800%2C278&ssl=1" alt="ProxySQL"></a>
|
||||
**You probably didn't mean to land here.** This branch is not a development
|
||||
branch for ProxySQL source code — it exists purely to host the
|
||||
**reusable GitHub Actions workflows** that ProxySQL's CI uses.
|
||||
|
||||
Introduction
|
||||
============
|
||||
If you're looking for ProxySQL itself, switch to the default branch:
|
||||
**[`v3.0`](https://github.com/sysown/proxysql/tree/v3.0)**.
|
||||
|
||||
ProxySQL is a high performance, high availability, protocol aware proxy for MySQL and forks (like Percona Server and MariaDB).
|
||||
All the while getting the unlimited freedom that comes with a GPL license.
|
||||
---
|
||||
|
||||
Its development is driven by the lack of open source proxies that provide high performance.
|
||||
## What lives here
|
||||
|
||||
Useful links
|
||||
===============
|
||||
Only one directory matters on this branch:
|
||||
|
||||
- [Official website](https://www.proxysql.com/)
|
||||
- [Subscriptions and Support](https://proxysql.com/services/support/)
|
||||
- [Documentation](https://www.proxysql.com/Documentation)
|
||||
- [DockerHub Repository](https://hub.docker.com/r/proxysql/proxysql)
|
||||
- [Benchmarks and blog posts](http://www.proxysql.blogspot.com/)
|
||||
- [Forum](https://groups.google.com/forum/#!forum/proxysql/)
|
||||
- [Facebook](https://www.facebook.com/proxysql)
|
||||
- [Linkedin](https://www.linkedin.com/groups/13581070/)
|
||||
- [Twitter](https://twitter.com/proxysql)
|
||||
|
||||
Getting started
|
||||
===============
|
||||
|
||||
### Installation
|
||||
Released packages can be found here: https://github.com/sysown/proxysql/releases
|
||||
|
||||
Just download a package and use your systems package manager to install it:
|
||||
```bash
|
||||
wget https://github.com/sysown/proxysql/releases/download/v2.4.2/proxysql_2.4.2-ubuntu20_amd64.deb
|
||||
dpkg -i proxysql_2.4.2-ubuntu20_amd64.deb
|
||||
```
|
||||
|
||||
Alternatively you can also use the available repositories:
|
||||
|
||||
#### Ubuntu / Debian:
|
||||
|
||||
Adding repository:
|
||||
```bash
|
||||
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-2.4.x-keyring.gpg 'https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/repo_pub_key.gpg'
|
||||
echo "deb https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/$(lsb_release -sc)/ ./" | tee /etc/apt/sources.list.d/proxysql.list
|
||||
```
|
||||
|
||||
Installing:
|
||||
```bash
|
||||
apt-get update
|
||||
apt-get install proxysql OR apt-get install proxysql=version
|
||||
```
|
||||
|
||||
#### Red Hat / CentOS:
|
||||
|
||||
Adding repository:
|
||||
```bash
|
||||
cat > /etc/yum.repos.d/proxysql.repo << EOF
|
||||
[proxysql]
|
||||
name=ProxySQL YUM repository
|
||||
baseurl=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/centos/\$releasever
|
||||
gpgcheck=1
|
||||
gpgkey=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/repo_pub_key
|
||||
EOF
|
||||
```
|
||||
|
||||
Installing:
|
||||
```bash
|
||||
yum install proxysql OR yum install proxysql-version
|
||||
```
|
||||
|
||||
#### Amazon Linux:
|
||||
|
||||
Adding repository:
|
||||
```bash
|
||||
cat > /etc/yum.repos.d/proxysql.repo << EOF
|
||||
[proxysql]
|
||||
name=ProxySQL YUM repository
|
||||
baseurl=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/centos/8
|
||||
gpgcheck=1
|
||||
gpgkey=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/repo_pub_key
|
||||
EOF
|
||||
.github/workflows/
|
||||
├── ci-trigger.yml ← Entry point; babysits CI-builds
|
||||
├── ci-builds.yml ← Builds ProxySQL in Docker, caches artefacts
|
||||
├── ci-basictests.yml
|
||||
├── ci-selftests.yml
|
||||
├── ci-maketest.yml
|
||||
├── ci-legacy-g1.yml .. ci-legacy-g5.yml
|
||||
├── ci-legacy-g2-genai.yml
|
||||
├── ci-legacy-clickhouse-g1.yml
|
||||
├── ci-mysql84-g1.yml .. ci-mysql84-g5.yml
|
||||
├── ci-unittests.yml
|
||||
├── ci-codeql.yml
|
||||
├── ci-package-build.yml
|
||||
├── ci-3p-*.yml ← Third-party integration workflows
|
||||
└── ci-taptests-groups.yml ← DEPRECATED; do not add new callers pointing here
|
||||
```
|
||||
|
||||
Installing:
|
||||
```bash
|
||||
yum install proxysql OR yum install proxysql-version
|
||||
```
|
||||
These are **reusable workflows** — they declare `on: workflow_call` and are
|
||||
invoked from matching "caller" files on the `v3.0` branch under the same
|
||||
path (e.g. `v3.0:.github/workflows/CI-legacy-g1.yml`). The caller files
|
||||
are what trigger on push/PR; the files here are the actual job bodies.
|
||||
|
||||
#### Almalinux:
|
||||
All other files on this branch (source code, docs, test directories, etc.)
|
||||
are **vestigial**. They're snapshots from an old point in history that
|
||||
happen to still exist on this branch because git never garbage-collected
|
||||
them. **Do not edit them here.** Any changes to source code, TAP tests,
|
||||
infra scripts, or documentation belong on `v3.0`.
|
||||
|
||||
Adding repository:
|
||||
```bash
|
||||
cat > /etc/yum.repos.d/proxysql.repo << EOF
|
||||
[proxysql]
|
||||
name=ProxySQL YUM repository
|
||||
baseurl=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/almalinux/\$releasever
|
||||
gpgcheck=1
|
||||
gpgkey=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/repo_pub_key
|
||||
EOF
|
||||
```
|
||||
---
|
||||
|
||||
Installing:
|
||||
```bash
|
||||
yum install proxysql OR yum install proxysql-version
|
||||
```
|
||||
## Where the real documentation is
|
||||
|
||||
#### OpenSUSE:
|
||||
The complete CI architecture is documented on the `v3.0` branch:
|
||||
|
||||
Adding repository:
|
||||
```bash
|
||||
cat > /etc/zypp/repos.d/proxysql.repo << EOF
|
||||
[proxysql]
|
||||
name=ProxySQL Zypper repository
|
||||
enabled=1
|
||||
autorefresh=0
|
||||
baseurl=https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/opensuse/\$releasever_major
|
||||
gpgcheck=1
|
||||
EOF
|
||||
```
|
||||
or
|
||||
```bash
|
||||
zypper addrepo -g -n 'ProxySQL Zypper repository' 'https://repo.proxysql.com/ProxySQL/proxysql-2.4.x/opensuse/$releasever_major' proxysql
|
||||
```
|
||||
### [`doc/GH-Actions/README.md` on `v3.0`](https://github.com/sysown/proxysql/blob/v3.0/doc/GH-Actions/README.md)
|
||||
|
||||
Installing:
|
||||
```bash
|
||||
yum install proxysql OR yum install proxysql-version
|
||||
```
|
||||
That doc covers:
|
||||
|
||||
### Service management
|
||||
Once the software is installed, you can use the `service` command to control the process:
|
||||
- The two-branch caller/reusable split and *why* it exists
|
||||
- The `CI-trigger` → `CI-builds` → test-workflow cascade (with diagrams)
|
||||
- The dedicated-reusable pattern with a step-by-step walkthrough of
|
||||
`ci-legacy-g4.yml` as the canonical template
|
||||
- The build cache layout (`_src`, `_test`, `_bin`, `_matrix`)
|
||||
- The TAP groups system (`test/tap/groups/`, `BASE_GROUP` stripping,
|
||||
`SKIP_PROXYSQL` mode)
|
||||
- An end-to-end walkthrough for adding a new test group
|
||||
- Common pitfalls (merge ordering, `workflow_run` head_sha propagation,
|
||||
the empty-matrix wedge, false-positive permissions hotspots)
|
||||
- A debugging guide for failing runs
|
||||
|
||||
#### Starting ProxySQL:
|
||||
```bash
|
||||
service proxysql start
|
||||
```
|
||||
#### Stopping ProxySQL:
|
||||
```bash
|
||||
service proxysql stop
|
||||
```
|
||||
Read it before touching anything here.
|
||||
|
||||
Or alternatively via the Admin interface:
|
||||
```
|
||||
$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin> '
|
||||
Warning: Using a password on the command line interface can be insecure.
|
||||
Welcome to the MySQL monitor. Commands end with ; or \g.
|
||||
Your MySQL connection id is 4
|
||||
Server version: 5.5.30 (ProxySQL Admin Module)
|
||||
---
|
||||
|
||||
Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
|
||||
## Quick reference for common tasks
|
||||
|
||||
Oracle is a registered trademark of Oracle Corporation and/or its
|
||||
affiliates. Other names may be trademarks of their respective
|
||||
owners.
|
||||
### Adding a new test group
|
||||
|
||||
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
|
||||
Four things, in this order:
|
||||
|
||||
Admin> proxysql stop
|
||||
```
|
||||
1. On **`v3.0`**: add the group to `test/tap/groups/groups.json` and
|
||||
create `test/tap/groups/<base-group>/{env.sh,infras.lst}` if the base
|
||||
group doesn't exist yet.
|
||||
2. On **`GH-Actions`** (here): create `.github/workflows/ci-<group>.yml`.
|
||||
Cut it from `ci-legacy-g4.yml` and change only `name:`, `INFRA_ID`,
|
||||
`TAP_GROUP`, and the `docker logs proxysql.<id>` target.
|
||||
3. On **`v3.0`**: create `.github/workflows/CI-<group>.yml` (the thin
|
||||
caller). Cut it from `CI-legacy-g4.yml` on `v3.0` and change the
|
||||
`name:` and `uses:` target.
|
||||
4. **Merge order:** the `GH-Actions` PR (step 2) must merge **before**
|
||||
the `v3.0` PR that introduces the new caller (steps 1 and 3).
|
||||
Otherwise the caller will try to resolve a reusable that doesn't yet
|
||||
exist on `GH-Actions` and every run will error out with
|
||||
`Unable to resolve action`.
|
||||
|
||||
#### Restarting ProxySQL:
|
||||
```bash
|
||||
service proxysql restart
|
||||
```
|
||||
### Modifying an existing reusable
|
||||
|
||||
Or alternatively via the Admin interface:
|
||||
```
|
||||
$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin> '
|
||||
Warning: Using a password on the command line interface can be insecure.
|
||||
Welcome to the MySQL monitor. Commands end with ; or \g.
|
||||
Your MySQL connection id is 4
|
||||
Server version: 5.5.30 (ProxySQL Admin Module)
|
||||
|
||||
Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Oracle is a registered trademark of Oracle Corporation and/or its
|
||||
affiliates. Other names may be trademarks of their respective
|
||||
owners.
|
||||
|
||||
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
|
||||
|
||||
Admin> proxysql restart
|
||||
```
|
||||
|
||||
#### Reinitializing ProxySQL from the config file (after first startup the DB file is used instead of the config file):
|
||||
```bash
|
||||
# If you are using the init script run:
|
||||
/etc/init.d/proxysql initial
|
||||
# or
|
||||
service proxysql initial
|
||||
|
||||
# If you are using the systemd unit file run:
|
||||
systemctl start proxysql-initial
|
||||
# or
|
||||
service proxysql-initial start
|
||||
```
|
||||
|
||||
### Upgrades
|
||||
Just install the new package and restart ProxySQL:
|
||||
```bash
|
||||
wget https://github.com/sysown/proxysql/releases/download/v2.1.0/proxysql_2.1.0-ubuntu16_amd64.deb
|
||||
dpkg -i proxysql_2.1.0-ubuntu16_amd64.deb
|
||||
service proxysql restart
|
||||
```
|
||||
|
||||
### How to check the ProxySQL version
|
||||
```bash
|
||||
$ proxysql --version
|
||||
```
|
||||
```bash
|
||||
ProxySQL version 2.1.0-544-g17a4b4a7, 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.
|
||||
```bash
|
||||
$ proxysql --version
|
||||
```
|
||||
```bash
|
||||
Main init phase0 completed in 0.000146 secs.
|
||||
ProxySQL version 2.1.0-544-g17a4b4a7_DEBUG, codename Truls
|
||||
```
|
||||
|
||||
### Configuring ProxySQL via the `admin interface`
|
||||
|
||||
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):
|
||||
```bash
|
||||
$ mysql -u admin -padmin -h 127.0.0.1 -P6032 --prompt='Admin> '
|
||||
Warning: Using a password on the command line interface can be insecure.
|
||||
Welcome to the MySQL monitor. Commands end with ; or \g.
|
||||
Your MySQL connection id is 4
|
||||
Server version: 5.5.30 (ProxySQL Admin Module)
|
||||
|
||||
Copyright (c) 2000, 2016, Oracle and/or its affiliates. All rights reserved.
|
||||
|
||||
Oracle is a registered trademark of Oracle Corporation and/or its
|
||||
affiliates. Other names may be trademarks of their respective
|
||||
owners.
|
||||
|
||||
Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.
|
||||
|
||||
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.
|
||||
|
||||
Once 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:
|
||||
```mysql
|
||||
Admin> SHOW DATABASES;
|
||||
+-----+---------+-------------------------------+
|
||||
| seq | name | file |
|
||||
+-----+---------+-------------------------------+
|
||||
| 0 | main | |
|
||||
| 2 | disk | /var/lib/proxysql/proxysql.db |
|
||||
| 3 | stats | |
|
||||
| 4 | monitor | |
|
||||
+-----+---------+-------------------------------+
|
||||
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 [here](https://github.com/sysown/proxysql/wiki/ProxySQL-Configuration).
|
||||
Make the edit on `GH-Actions` directly in a feature branch, open a PR
|
||||
targeting `GH-Actions`, and merge. The change takes effect on the next
|
||||
run of any caller that points at that file — **no `v3.0` change is
|
||||
needed** as long as you don't change the `inputs:` interface.
|
||||
|
||||
#### Configuring ProxySQL through the config file
|
||||
If you *do* change the `inputs:` (add a new required input, rename one,
|
||||
etc.), you must update every caller on `v3.0` in a coordinated pair of
|
||||
PRs — same merge-order rule as adding a new group.
|
||||
|
||||
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.
|
||||
### Deleting a reusable
|
||||
|
||||
Let's quickly go over the main sections of the configuration file (this overview serves as a very high level overview of ProxySQL configuration).
|
||||
1. First, make sure no caller on `v3.0` points at it. Grep for the
|
||||
filename in `v3.0:.github/workflows/CI-*.yml`. If any match, rewire
|
||||
them to a different reusable first (separate `v3.0` PR), merge that,
|
||||
then proceed.
|
||||
2. Then open a `GH-Actions` PR deleting the file.
|
||||
|
||||
Top-level sections:
|
||||
* `admin_variables`: contains global variables that control the functionality of the admin interface.
|
||||
* `mysql_variables`: contains global variables that control the functionality for handling the incoming MySQL traffic.
|
||||
* `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:
|
||||
|
||||
```bash
|
||||
mysql_servers =
|
||||
(
|
||||
{
|
||||
address="127.0.0.1"
|
||||
port=3306
|
||||
hostgroup=0
|
||||
max_connections=200
|
||||
}
|
||||
)
|
||||
```
|
||||
* `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:
|
||||
|
||||
```bash
|
||||
mysql_users:
|
||||
(
|
||||
{
|
||||
username = "root"
|
||||
password = "root"
|
||||
default_hostgroup = 0
|
||||
max_connections=1000
|
||||
default_schema="information_schema"
|
||||
active = 1
|
||||
}
|
||||
)
|
||||
```
|
||||
* `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):
|
||||
|
||||
```bash
|
||||
mysql_query_rules:
|
||||
(
|
||||
{
|
||||
rule_id=1
|
||||
active=1
|
||||
match_pattern="^SELECT .* FOR UPDATE$"
|
||||
destination_hostgroup=0
|
||||
apply=1
|
||||
},
|
||||
{
|
||||
rule_id=2
|
||||
active=1
|
||||
match_pattern="^SELECT"
|
||||
destination_hostgroup=1
|
||||
apply=1
|
||||
}
|
||||
)
|
||||
```
|
||||
* top-level configuration item: `datadir`, as a string, to point to the data dir.
|
||||
---
|
||||
|
||||
## Branch protection
|
||||
|
||||
As of 2026-04-11, `GH-Actions` has **no branch protection**. You can
|
||||
push directly to it if you're a maintainer. PRs are the recommended
|
||||
workflow so that review bots (CodeRabbit, Sonar) can comment on the
|
||||
change and so the history is easy to audit, but they are not mechanically
|
||||
required. The same applies to merge-button status checks: failing
|
||||
Sonar/CodeRabbit runs don't block merges here.
|
||||
|
||||
`v3.0` protection rules are separate and stricter — see the repository
|
||||
settings for the current state.
|
||||
|
||||
Loading…
Reference in new issue