Skip to content

Commit 9e97643

Browse files
patrickbirchpatrickbirch
committed
PSQLADM-570 [DOCS] - Remove 2.x from the titles in preparation of 3.x release
 modified: docs/index.md modified: docs/install-proxysql2-tarball.md modified: docs/install-v2.md modified: docs/proxysql-admin-tool-changes.md modified: docs/proxysql-admin-tool-v2-config.md modified: docs/psh-detailed-options.md modified: docs/psh-overview.md modified: docs/start-or-stop-proxysql2.md modified: docs/uninstall-proxysql2.md modified: docs/upgrade-proxysql2.md modified: docs/where-to-download-proxysql.md
1 parent 636772e commit 9e97643

13 files changed

+259
-165
lines changed

‎docs/build-psh.md

Lines changed: 4 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,5 @@
11
# Build the pxc_scheduler_handler tool
22

3-
In an MySQL 8.4 or Percona Server for MySQL 8.4 environment, you may have the following issues:
4-
5-
* ProxySQL contains counters that have not been updated to use the new terminology. Unexpected results may occur
6-
* The binlog reader errors out during initialization due to the use of the old terminology, such as SHOW MASTER STATUS command.
7-
83
The pxc_scheduler_handler tool has two main files: the `pxc_scheduler_handler` binary and the `percona_scheduler_admin` script.
94

105
The `pxc_scheduler_handler` does the following tasks:
@@ -39,12 +34,12 @@ $ build_scheduler.sh
3934

4035
The `pxc_scheduler_handler` binary is located in the base directory.
4136

42-
We do not recommend running multiple instances of the same binary. If you start a new instance when an instance of
43-
`pxc_scheduler_handler` is already running, the binary runs, but the second instance does the following:
37+
Do not run multiple instances of this binary. If you start a new instance when an instance of
38+
`pxc_scheduler_handler` is already running, both instances execute, but the second instance:
4439

45-
* Consumes network and system resources
40+
* Consumes additional network and system resources
4641

47-
* Returns the same results since multiple versions use the same configuration file
42+
* Returns identical results because both use the same configuration file
4843

4944
## Create an account
5045

‎docs/index.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,11 @@ The ProxySQL service runs as a daemon and is monitored by a watchdog process cap
1212

1313
Configuration is handled using SQL-like statements, including runtime options, server grouping, and query routing rules. Most settings can be changed dynamically without restarting the proxy.
1414

15-
The [ProxySQL 2 documentation](https://proxysql.com/documentation/) includes detailed guidance on installation, operation, and the use of supporting tools. The maintained releases are listed on
15+
The [ProxySQL documentation](https://proxysql.com/documentation/) includes detailed guidance on installation, operation, and the use of supporting tools. The maintained releases are listed on
1616
[ProxySQL Installation](https://proxysql.com/documentation/installing-proxysql/).
1717

18-
[You can download Percona's build of ProxySQL 2.x.x](https://www.percona.com/download-proxysql). Note that
19-
Version 1 is no longer actively maintained. The ProxySQL 2. x. x downloads may include:
18+
[You can download Percona build of ProxySQL](https://www.percona.com/download-proxysql). Note that
19+
Version 1 is no longer actively maintained. The ProxySQL downloads may include:
2020

2121
- [ProxySQL Admin (proxysql-admin)](proxysql-admin-tool-v2-config.md) simplifies the configuration of Percona XtraDB Cluster nodes with ProxySQL.
2222

‎docs/install-proxysql2-tarball.md

Lines changed: 42 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,65 @@
1-
# Install Percona's build of ProxySQL 2.x.x binary tarball
1+
# Install Percona build of ProxySQL binary tarball
22

3-
If installing [_ProxySQL 2_ with a package manager](install-v2.md) is not an option in your environment, you can install from a binary tarball. The difference between versions is the available tar files or the command to extract the file.
3+
If installing [Percona build of ProxySQL with a package manager](install-v2.md) is not an option in your environment, you can install from a binary tarball. The difference between versions is the available tar files or the command to extract the file.
4+
5+
## Version changes
6+
7+
### CentOS 6
48

59
Starting with [_ProxySQL 2.3.2-1.2_](release-notes-2.3.2-1.md), Percona no longer provides a tarball for CentOS 6. For more information, see [Spring Cleaning: Discontinuing RHEL 6/CentOS 6 (glibc2.12) and 32-bit Binary Builds of Percona Software](https://www.percona.com/blog/spring-cleaning-discontinuing-rhel-6-centos-6-glibc-2-12-and-32-bit-binary-builds-of-percona-software/)
610

11+
### OpenSSL 1.1.1
12+
713
The password-based file encryption requires OpenSSL 1.1.1, but Ubuntu 16.04 does not support this OpenSSL version. A special statically linked OpenSSL 1.1.1 binary is packaged with the executable. This packaged binary avoids conflicts with the system OpenSSL and any shared libraries. Each new release rebuilds the binary.
814

9-
Follow these steps:
15+
## Format
16+
17+
The tar file binary have the following format:
1018

11-
1. In [Download ProxySQL](https://www.percona.com/downloads/proxysql/), select the `ProxySQL 2` product.
19+
proxysql-<version>-<operating_system>-<architecture>-<glibc_version>.tar.gz
1220

13-
2. In the _Select Product Version_ field, select the `ProxySQL 2` version.
21+
The following is an example of a tar file binary for ProxySQL 3.0.1
1422

15-
3. In the _Select Platform_ field, select **Linux - Generic**.
23+
proxysql-3.0.1-Linux-x86_64.glibc2.31.tar.gz
24+
25+
## Download the file
1626

17-
4. Select the tar file.
27+
[Follow the instructions in `Download locations for Percona’s build of ProxySQL and ProxySQL admin tools`](where-to-download-proxysql.md)
1828

19-
??? note "tar files for ProxySQL 2.4.4 and higher"
29+
Be sure to select the appropriate file for your operating system based on the `glibc version` used. Verify that you're installing the correct ProxySQL version for your environment, such as `proxysql2` or `proxysql3`.
2030

21-
| Name | Description |
22-
| ------------------------------------------------- | ------------------------------------- |
23-
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
24-
|proxysql-2-<version>-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
25-
|proxysql-2-<version>-Linux-x86_64.glibc2.27.tar.gz | For every supported operating system but `xenial`. For CentOS 7, install OpenSSL 1.1.1, if needed. |
31+
??? note "tar files for ProxySQL 2.4.4 and higher"
2632

27-
??? note "tar files from ProxySQL 2.3.2-1.2 to ProxySQL 2.4.3"
33+
| Name | Description |
34+
| ------------------------------------------------- | ------------------------------------- |
35+
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
36+
|proxysql-2-<version>-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
37+
|proxysql-2-<version>-Linux-x86_64.glibc2.27.tar.gz | For every supported operating system but `xenial`. For CentOS 7, install OpenSSL 1.1.1, if needed. |
2838

29-
| Name | Description |
30-
| ------------------------------------------------- | ------------------------------------- |
31-
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
39+
??? note "tar files from ProxySQL 2.3.2-1.2 to ProxySQL 2.4.3"
3240

33-
??? note "tar files from ProxySQL 2.0.15 to ProxySQL 2.3.2"
41+
| Name | Description |
42+
| ------------------------------------------------- | ------------------------------------- |
43+
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
3444

35-
| Name | Description |
36-
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
37-
| proxysql-2.0.XX-Linux-x86_64.glibc2.12.tar.gz | For every supported operating system but `xenial`. For CentOS 7, install OpenSSL 1.1.1, if needed. |
38-
| proxysql-2.x.xx-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
39-
| proxysql-2.0.XX-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only.
45+
??? note "tar files from ProxySQL 2.0.15 to ProxySQL 2.3.2"
4046

41-
See ProxySQL 2.0.15 and proxysql-admin
47+
| Name | Description |
48+
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
49+
| proxysql-2.0.XX-Linux-x86_64.glibc2.12.tar.gz | For every supported operating system but `xenial`. For CentOS 7, install OpenSSL 1.1.1, if needed. |
50+
| proxysql-2.x.xx-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
51+
| proxysql-2.0.XX-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only.
4252

43-
5. Navigate to the downloaded tar file.
53+
## Install the file
4454

45-
6. Extract the files with the following commands:
55+
1. Navigate to the downloaded tar file.
56+
57+
2. Extract the files with the following commands:
4658

4759
??? "Extract ProxySQL 2.0.14 or higher"
4860

4961
```{.bash data-prompt="$"}
50-
$ # Extract the files to the download destination directory
51-
$ tar xzf proxysql-2.X.X-<PLATFORM-ARCHITECTURE*>.tar.gz
52-
$ # Change to the directory that contains the extracted files
62+
$ tar xzf proxysql-<version>-Linux-<PLATFORM-ARCHITECTURE>-<glibc version>.tar.gz
5363
$ cd proxysql-<VERSION>-Linux-<PLATFORM-ARCHITECTURE>
5464
```
5565

@@ -62,24 +72,20 @@ Follow these steps:
6272
$ cd proxysql-<VERSION>-Linux-<PLATFORM-ARCHITECTURE>
6373
```
6474

65-
7. Create a directory to store the _ProxySQL_ data.
75+
3. Create a directory to store the _ProxySQL_ data.
6676

6777
```{.bash data-prompt="$"}
6878
$ mkdir /home/user/data
6979
```
7080

71-
8. In the configuration file, update the `datadir` value to point
81+
4. In the configuration file, update the `datadir` value to point
7282
to the created data directory.
7383

7484
```{.text .no-copy}
7585
datadir="/home/user/data"
7686
```
7787

78-
9. Set the other options, as needed.
79-
80-
!!! admonition "See also"
81-
82-
[ProxySQL 2.x and proxysql-admin utility](proxysql-admin-tool-v2-config.md)
88+
5. Set the other options, as needed.
8389

8490
## MySQL 8.4 and Percona Server for MySQL 8.4 considerations
8591

‎docs/install-v2.md

Lines changed: 25 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,24 @@
1-
# Install Percona's build of ProxySQL 2.x.x and the admin utilities
1+
# Install Percona build of ProxySQL and the admin tools
22

33

4-
Select the same package installer used to install [Percona XtraDB Cluster](https://www.percona.com/doc/percona-xtradb-cluster/8.0/install/index.html) or other Percona software.
4+
Select the same package installer used to install [Percona XtraDB Cluster](https://www.percona.com/doc/percona-xtradb-cluster/8.0/install/index.html) or other Percona software to ensure compatibility.
5+
6+
Verify that you're installing the correct ProxySQL version for your environment, such as `proxysql2` or `proxysql3`.
57

68
=== "On a Debian-derived distribution"
79

8-
If you used APT to install Percona software, run the following command as sudo or as root:
10+
If you installed Percona software using APT, run the following command as sudo or as root. Make sure to use the correct package name for the version you installed, such as `proxysql2` or `proxysql3`.
911

1012
```{.bash data-prompt="$"}
1113
$ sudo apt install proxysql2
1214
```
15+
16+
or
17+
18+
```{.bash data-prompt="$"}
19+
$ sudo apt install proxysql3
20+
```
21+
1322
??? example "Expected output"
1423

1524
```{.text .no-copy}
@@ -27,12 +36,18 @@ Select the same package installer used to install [Percona XtraDB Cluster](https
2736

2837
=== "On a Red Hat-derived distribution"
2938

30-
If you used YUM to install Percona software, run the following command:
39+
If you installed Percona software using YUM, run the following command. Make sure to use the correct package name for the version you installed, such as `proxysql2` or `proxysql3`.
3140

3241
```{.bash data-prompt="$"}
3342
$ sudo yum install proxysql2
3443
```
3544

45+
or
46+
47+
```{.bash data-prompt="$"}
48+
$ sudo yum install proxysql3
49+
```
50+
3651
??? example "Expected output"
3752

3853
```{.text .no-copy}
@@ -63,7 +78,7 @@ Select the same package installer used to install [Percona XtraDB Cluster](https
6378

6479
## Verify the pxc_scheduler_handler installation
6580

66-
If you have installed [ProxySQL 2.3.2-2.1](release-notes-2.3.2-1.md) or later, verify the pxc_scheduler_handler installation with the following command:
81+
If you have installed [ProxySQL 2.3.2-2.1](release-notes-2.3.2-1.md) or later, verify the [pxc_scheduler_handler](psh-overview.md) installation with the following command:
6782

6883
```{.bash data-prompt="$"}
6984
$ percona-scheduler-admin --debug
@@ -79,7 +94,11 @@ Running this command without the [pxc_scheduler_handler configuration file](psh-
7994

8095
## Run Docker
8196

82-
To run ProxySQL2 in Docker, download the latest image at [percona/proxysql2](https://hub.docker.com/r/percona/proxysql2).
97+
To run the Percona build of ProxySQL in Docker, do the following:
98+
99+
* ProxySQL2 in Docker, download the latest image at [percona/proxysql2](https://hub.docker.com/r/percona/proxysql2).
100+
101+
* ProxySQL3 in Docker, download the latest image at [percona/proxysql3](https://hub.docker.com/r/percona/proxysql3).
83102

84103
## MySQL 8.4 and Percona Server for MySQL 8.4 considerations
85104

‎docs/proxysql-admin-tool-changes.md

Lines changed: 73 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,43 +1,68 @@
1-
# ProxySQL Admin tool changes
1+
# Percona build of ProxySQL Admin tool changes
22

33
## Added features
44

5-
* New option `--use-ssl` to use SSL for connections between ProxySQL and the backend database servers
5+
### `--use-ssl`
66

7-
* New option `--max-transactions-behind` to determine the maximum number of writesets
8-
that can be queued before the node is SHUNNED to avoid stale reads. The default value is 100
7+
Enables SSL connections between ProxySQL and the backend database servers
98

10-
* New operation `--update-cluster` to update the cluster membership by adding
11-
server nodes as found. (Note that nodes are added but not removed). The
12-
`--writer-hg` option may be used to specify which Galera hostgroup to
13-
update. The `--remove-all-servers` option instructs to remove all servers
14-
from the mysql_servers table before updating the cluster.
9+
### `--max-transactions-behind`
1510

16-
* Hostgroups can be specified on the command-line: `--writer-hg`,
17-
`--reader-hg`, `--backup-writer-hg`, and `--offline-hg`. Previously,
18-
these host groups were only read from the configuration file.
11+
Specifies the maximum number of writesets that can be queued before the node is SHUNNED to avoid stale reads. The default value is `100`.
1912

20-
* The `--enable` and `--update-cluster` options used simultaneously have
21-
special meaning. If the cluster has not been enabled, then `--enable` is
22-
run. If the cluster has already been enabled, then `--update-cluster` is run.
13+
### `--update-cluster`
2314

24-
* New command `--is-enabled` to see if a cluster has been enabled. This
25-
command checks for the existence of a row in the mysql_Galera_hostgroups
26-
table. The `--writer-hg` option may be used to specify the writer hostgroup
27-
used to search the mysql_galera_hostgroups table.
15+
Updates the cluster membership by adding newly discoveredserver nodes. Note: This operation adds nodes but does not remove them. Use [`--writer-hg`] option may be used to specify which Galera hostgroup to update. The `--remove-all-servers` option instructs to remove all servers from the mysql_servers table before updating the cluster.
2816

29-
* New command `--status` to display Galera hostgroup information. This command
30-
lists all rows in the current `mysql_galera_hostgroups` table as well as all servers that belong to these hostgroups. With the `--writer-hg` option, only the information for the Galera hostgroup with that writer hostgroup is displayed.
17+
### Hostgroup options on the command-line
3118

32-
* New option `--login-file` reads login credentials from an encrypted file.
33-
If the `--login-password` or `login-password-file` options are not
34-
specified, the user is prompted for the password.
19+
Hostgroups can now be set with command-line options:
3520

36-
* New option `--login-password` is the key used to decrypt the encrypted
37-
login-file. You cannot use the option with the `--login-password-file`.
21+
* `--writer-hg`
3822

39-
* New option `--login-password-file` reads the key from a file using the
40-
specified path. You cannot use the option with `login-password`.
23+
24+
* `--reader-hg`
25+
26+
* `--backup-writer-hg`
27+
28+
* `--offline-hg`.
29+
30+
These options were previously only available through the configuration file.
31+
32+
### Combined use of `--enable` and `--update-cluster`
33+
34+
When used together:
35+
36+
* If the cluster is not yet enabled, then `--enable` is
37+
executed.
38+
39+
* If the cluster is already enabled, then `--update-cluster` is executed.
40+
41+
### `--is-enabled`
42+
43+
Checks whether a cluster has been enabled by querying the `mysql_galera_hostgroups` table. Optionally, use the `--writer-hg` option to specify the writer hostgroup for the lookup.
44+
45+
46+
### `--status`
47+
48+
Displays the current Galera hostgroup configuration. This option lists all rows in the current `mysql_galera_hostgroups` table, along with the servers assigned to each hostgroup.
49+
50+
Use the `--writer-hg` option to limit the result to a specific hostgroup.
51+
52+
### `--login-file`
53+
54+
Reads login credentials from an encrypted file.
55+
If neither `--login-password` nor `--login-password-file` is specified, the user is prompted to enter the decryption password interactively.
56+
57+
### `--login-password`
58+
59+
Specifies the decryption key used to unlock the credentials stored in the `--login-file`.
60+
This option is mutually exclusive with `--login-password-file`.
61+
62+
### `--login-password-file`
63+
64+
Reads the decryption key from a file located at the specified path.
65+
This option is mutually exclusive with `--login-password`.
4166

4267
## Changed features
4368

@@ -69,24 +94,32 @@
6994
Galera cluster associated with that hostgroup overriding the value specified
7095
in the configuration file.
7196

72-
## Removed features
97+
## Removed Features
98+
99+
### Asynchronous slave reader support
100+
101+
The `--include-slaves` option is no longer supported. Asynchronous slave reader support has been removed.
102+
103+
### Node priority lists
104+
105+
ProxySQL v2 no longer supports specifying a list of nodes in priority order. Only a single node is supported.
106+
107+
### Automatic cluster membership updates
108+
109+
Cluster membership is no longer updated automatically. The `galera_proxysql_checker` and `galera_node_monitor` scripts are no longer run in the scheduler.
73110

74-
* Asynchronous slave reader support has been removed: the `--include-slaves`
75-
option is not supported.
111+
### `pxc_maint_mode` check
76112

77-
* A list of nodes in the priority order is not supported in *ProxySQL* v2. Only
78-
a single node is supported at this time.
113+
The check for the `pxc_maint_mode` variable has been removed and is no longer supported.
79114

80-
* Since the galera_proxysql_checker and galera_node_monitor scripts are no
81-
longer run in the scheduler, automatic cluster membership updates are not
82-
supported.
115+
### Desynced node fallback
83116

84-
* Checking the pxc_maint_mode variable is no longer supported
117+
Falling back to desynced nodes when no synced nodes are available is no longer supported.
85118

86-
* Using desynced nodes if no other nodes are available is no longer supported.
119+
### Server status tracking in `mysql_servers`
87120

88-
* The server status is no longer maintained in the mysql_servers table.
121+
The `mysql_servers` table no longer maintains server status information.
89122

90123
## Limitations
91124

92-
* With `--writers-as-readers=backup` read-only nodes are not allowed. This is a limitation of ProxySQL 2.x. Note that backup is the default value of `--writers-as-readers` when `--mode=singlewrite`
125+
* With `--writers-as-readers=backup` read-only nodes are not allowed. This is a limitation of ProxySQL. Note that backup is the default value of `--writers-as-readers` when `--mode=singlewrite`

0 commit comments

Comments
 (0)