Skip to content

PSQLADM-570 [DOCS] - Remove 2.x from the titles in preparation of 3.x… #137

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

PSQLADM-570 [DOCS] - Remove 2.x from the titles in preparation of 3.x… #137

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 4 additions & 9 deletions docs/build-psh.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,5 @@
# Build the pxc_scheduler_handler tool

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.

The pxc_scheduler_handler tool has two main files: the `pxc_scheduler_handler` binary and the `percona_scheduler_admin` script.

The `pxc_scheduler_handler` does the following tasks:
Expand Down Expand Up @@ -39,12 +34,12 @@ $ build_scheduler.sh

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

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

* Consumes network and system resources
* Consumes additional network and system resources

* Returns the same results since multiple versions use the same configuration file
* Returns identical results because both use the same configuration file

## Create an account

Expand Down
10 changes: 7 additions & 3 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,11 +12,15 @@ The ProxySQL service runs as a daemon and is monitored by a watchdog process cap

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.

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
!!! note

[ProxySQL 3.0.1 contains a PostgreSQL module in beta.](https://github.com/sysown/proxysql/releases) The Percona build of ProxySQL is only tested with Percona Server for MySQL.

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
[ProxySQL Installation](https://proxysql.com/documentation/installing-proxysql/).

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

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

Expand Down
78 changes: 42 additions & 36 deletions docs/install-proxysql2-tarball.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,55 +1,65 @@
# Install Percona's build of ProxySQL 2.x.x binary tarball
# Install Percona build of ProxySQL binary tarball

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.
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.

## Version changes

### CentOS 6

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/)

### OpenSSL 1.1.1

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.

Follow these steps:
## Format

The tar file binary have the following format:

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

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

3. In the _Select Platform_ field, select **Linux - Generic**.
proxysql-3.0.1-Linux-x86_64.glibc2.31.tar.gz

## Download the file

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

??? note "tar files for ProxySQL 2.4.4 and higher"
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`.

| Name | Description |
| ------------------------------------------------- | ------------------------------------- |
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
|proxysql-2-<version>-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
|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. |
??? note "tar files for ProxySQL 2.4.4 and higher"

??? note "tar files from ProxySQL 2.3.2-1.2 to ProxySQL 2.4.3"
| Name | Description |
| ------------------------------------------------- | ------------------------------------- |
| proxysql-2-<version>-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only |
|proxysql-2-<version>-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
|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. |

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

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

| Name | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 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. |
| proxysql-2.x.xx-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
| proxysql-2.0.XX-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only.
??? note "tar files from ProxySQL 2.0.15 to ProxySQL 2.3.2"

See ProxySQL 2.0.15 and proxysql-admin
| Name | Description |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| 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. |
| proxysql-2.x.xx-Linux-x86_64.glibc2.17.tar.gz | For every supported operating system |
| proxysql-2.0.XX-Linux-x86_64.glibc2.23.xenial.tar.gz | For Ubuntu 16.04 `xenial` only.

5. Navigate to the downloaded tar file.
## Install the file

6. Extract the files with the following commands:
1. Navigate to the downloaded tar file.

2. Extract the files with the following commands:

??? "Extract ProxySQL 2.0.14 or higher"

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

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

7. Create a directory to store the _ProxySQL_ data.
3. Create a directory to store the _ProxySQL_ data.

```{.bash data-prompt="$"}
$ mkdir /home/user/data
```

8. In the configuration file, update the `datadir` value to point
4. In the configuration file, update the `datadir` value to point
to the created data directory.

```{.text .no-copy}
datadir="/home/user/data"
```

9. Set the other options, as needed.

!!! admonition "See also"

[ProxySQL 2.x and proxysql-admin utility](proxysql-admin-tool-v2-config.md)
5. Set the other options, as needed.

## MySQL 8.4 and Percona Server for MySQL 8.4 considerations

Expand Down
31 changes: 25 additions & 6 deletions docs/install-v2.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,24 @@
# Install Percona's build of ProxySQL 2.x.x and the admin utilities
# Install Percona build of ProxySQL and the admin tools


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.
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.

Verify that you're installing the correct ProxySQL version for your environment, such as `proxysql2` or `proxysql3`.

=== "On a Debian-derived distribution"

If you used APT to install Percona software, run the following command as sudo or as root:
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`.

```{.bash data-prompt="$"}
$ sudo apt install proxysql2
```

or

```{.bash data-prompt="$"}
$ sudo apt install proxysql3
```

??? example "Expected output"

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

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

If you used YUM to install Percona software, run the following command:
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`.

```{.bash data-prompt="$"}
$ sudo yum install proxysql2
```

or

```{.bash data-prompt="$"}
$ sudo yum install proxysql3
```

??? example "Expected output"

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

## Verify the pxc_scheduler_handler installation

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:
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:

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

## Run Docker

To run ProxySQL2 in Docker, download the latest image at [percona/proxysql2](https://hub.docker.com/r/percona/proxysql2).
To run the Percona build of ProxySQL in Docker, do the following:

* ProxySQL2 in Docker, download the latest image at [percona/proxysql2](https://hub.docker.com/r/percona/proxysql2).

* ProxySQL3 in Docker, download the latest image at [percona/proxysql3](https://hub.docker.com/r/percona/proxysql3).

## MySQL 8.4 and Percona Server for MySQL 8.4 considerations

Expand Down
113 changes: 73 additions & 40 deletions docs/proxysql-admin-tool-changes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,43 +1,68 @@
# ProxySQL Admin tool changes
# Percona build of ProxySQL Admin tool changes

## Added features

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

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

* New operation `--update-cluster` to update the cluster membership by adding
server nodes as found. (Note that nodes are added but not removed). The
`--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.
### `--max-transactions-behind`

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

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

* New command `--is-enabled` to see if a cluster has been enabled. This
command checks for the existence of a row in the mysql_Galera_hostgroups
table. The `--writer-hg` option may be used to specify the writer hostgroup
used to search the mysql_galera_hostgroups table.
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.

* New command `--status` to display Galera hostgroup information. This command
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.
### Hostgroup options on the command-line

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

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

* New option `--login-password-file` reads the key from a file using the
specified path. You cannot use the option with `login-password`.

* `--reader-hg`

* `--backup-writer-hg`

* `--offline-hg`.

These options were previously only available through the configuration file.

### Combined use of `--enable` and `--update-cluster`

When used together:

* If the cluster is not yet enabled, then `--enable` is
executed.

* If the cluster is already enabled, then `--update-cluster` is executed.

### `--is-enabled`

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.


### `--status`

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.

Use the `--writer-hg` option to limit the result to a specific hostgroup.

### `--login-file`

Reads login credentials from an encrypted file.
If neither `--login-password` nor `--login-password-file` is specified, the user is prompted to enter the decryption password interactively.

### `--login-password`

Specifies the decryption key used to unlock the credentials stored in the `--login-file`.
This option is mutually exclusive with `--login-password-file`.

### `--login-password-file`

Reads the decryption key from a file located at the specified path.
This option is mutually exclusive with `--login-password`.

## Changed features

Expand Down Expand Up @@ -69,24 +94,32 @@
Galera cluster associated with that hostgroup overriding the value specified
in the configuration file.

## Removed features
## Removed Features

### Asynchronous slave reader support

The `--include-slaves` option is no longer supported. Asynchronous slave reader support has been removed.

### Node priority lists

ProxySQL v2 no longer supports specifying a list of nodes in priority order. Only a single node is supported.

### Automatic cluster membership updates

Cluster membership is no longer updated automatically. The `galera_proxysql_checker` and `galera_node_monitor` scripts are no longer run in the scheduler.

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

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

* Since the galera_proxysql_checker and galera_node_monitor scripts are no
longer run in the scheduler, automatic cluster membership updates are not
supported.
### Desynced node fallback

* Checking the pxc_maint_mode variable is no longer supported
Falling back to desynced nodes when no synced nodes are available is no longer supported.

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

* The server status is no longer maintained in the mysql_servers table.
The `mysql_servers` table no longer maintains server status information.

## Limitations

* 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`
* 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`
Loading