Merge pull request #296 from percona/ps-9161-8

PS-9161 Update APT and YUM topics with more explanation - 8.0

Author: patrickbirch

docs/apt-download-deb.md

@@ -1,45 +1,67 @@
 # Install Percona Server for MySQL 8.0 using downloaded DEB packages
 
+When installing packages manually, you must resolve all the dependencies and install missing packages yourself. You must install the following packages before manually installing Percona Server:
+
+* `mysql-common`
+
+* `libjemalloc1`
+
+* `libaio1`
+
+* `libmecab2`.
+
 Download the packages from [Percona Product Downloads](https://www.percona.com/downloads). If needed, [Instructions for the Percona Product Download](download-instructions.md) are available.
 
-The following example downloads Percona Server for MySQL 8.0.31-23 release packages for Debian 10:
-
-```{.bash data-prompt="$"}
-$ wget https://downloads.percona.com/downloads/Percona-Server-8.0/Percona-Server-8.0.31-23/binary/debian/buster/x86_64/Percona-Server-8.0.31-23-r71449379-buster-x86_64-bundle.tar
-```
-
-Unpack the download to get the packages:
-
-```{.bash data-prompt="$"}
-$ tar xvf Percona-Server-8.0.31-23-r71449379-buster-x86_64-bundle.tar
-```
-??? example "Expected output"
-
-    ```text
-    libperconaserverclient21_8.0.31-23-1.buster_amd64.deb
-    libperconaserverclient21-dev_8.0.31-23-1.buster_amd64.deb
-    percona-mysql-router_8.0.31-23-1.buster_amd64.deb
-    percona-server-client_8.0.31-23-1.buster_amd64.deb
-    percona-server-common_8.0.31-23-1.buster_amd64.deb
-    percona-server-dbg_8.0.31-23-1.buster_amd64.deb
-    percona-server-rocksdb_8.0.31-23-1.buster_amd64.deb
-    percona-server-server_8.0.31-23-1.buster_amd64.deb
-    percona-server-source_8.0.31-23-1.buster_amd64.deb
-    percona-server-test_8.0.31-23-1.buster_amd64.deb
+1. The following example uses `Wget` to download the Percona Server 8.0 bundle from the specified URL. The bundle is a tar archive containing the Percona Server 8.0.31-23 binary for Debian Buster (x86_64 architecture):
+
+    ```{.bash data-prompt="$"}
+    $ wget https://downloads.percona.com/downloads/Percona-Server-8.0/Percona-Server-8.0.31-23/binary/debian/buster/x86_64/Percona-Server-8.0.31-23-r71449379-buster-x86_64-bundle.tar
     ```
 
-Install Percona Server for MySQL using `dpkg`. Run this command as root or use the sudo command:
+2. The command line instruction uses the `tar` command to extract files from a tarball (a type of compressed file). The `tar` command is a Unix utility that stores and extracts files from an archive file known as a tarfile. 
+
+    The `xvf` option combines three separate options: `x`, `v`, and `f`. 
+
+    * `x` extract the files from the archive
 
-```{.bash data-prompt="$"}
-$ sudo dpkg -i *.deb
-```
+    * `v` verbose - print the file names as they are extracted
 
-!!! note
+    * `f` file - use the following argument as the name of the archive file
 
-    Percona Server for MySQL 8.0 comes with the TokuDB storage engine. You can find more information on how to install and enable the TokuDB storage in the TokuDB Installation guide.
+    The following command extracts the contents of the  `Percona-Server-8.0.31-23-r71449379-buster-x86_64-bundle.tar` file and prints the file names.
+
+    ```{.bash data-prompt="$"}
+    $ tar xvf Percona-Server-8.0.31-23-r71449379-buster-x86_64-bundle.tar
+    ```
+
+    ??? example "Expected output"
+
+        ```text
+        libperconaserverclient21_8.0.31-23-1.buster_amd64.deb
+        libperconaserverclient21-dev_8.0.31-23-1.buster_amd64.deb
+        percona-mysql-router_8.0.31-23-1.buster_amd64.deb
+        percona-server-client_8.0.31-23-1.buster_amd64.deb
+        percona-server-common_8.0.31-23-1.buster_amd64.deb
+        percona-server-dbg_8.0.31-23-1.buster_amd64.deb
+        percona-server-rocksdb_8.0.31-23-1.buster_amd64.deb
+        percona-server-server_8.0.31-23-1.buster_amd64.deb
+        percona-server-source_8.0.31-23-1.buster_amd64.deb
+        percona-server-test_8.0.31-23-1.buster_amd64.deb
+        ```
+
+3. Install Percona Server for MySQL using the `dpkg` utility to install Debian (.deb) packages. The installation requires either root or the `sudo` command. `sudo` allows you to run programs with the security privileges of another user, usually as the superuser.
+
+    `dpkg` is a package manager for Debian-based systems and can install, remove, and provide information about `.deb` packages. 
+
+    The `-i` option tells `dpkg` to install the package.
+
+    The `*.deb` is a wildcard that matches any file in the current directory that ends with the `.deb` extension. 
+
+
+    ```{.bash data-prompt="$"}
+    $ sudo dpkg -i *.deb
+    ```
 
-	Starting with Percona Server for MySQL 8.0.28-19 (2022-05-12), the TokuDB storage engine is no longer supported. We have removed the storage engine from the installation packages and disabled the storage engine in our binary builds. For more information, see the TokuDB Introduction.
+Starting with Percona Server for MySQL 8.0.28-19 (2022-05-12), the TokuDB storage engine is no longer supported. For more information, see the [TokuDB Introduction](tokudb-intro.md) and [TokuDB changes by Percona Server for MySQL version](tokudb-version-changes.md). 
 
-!!! warning
 
-    When installing packages manually like this, you’ll need to resolve all the dependencies and install missing packages yourself. The following packages will need to be installed before you can manually install Percona Server: `mysql-common`, `libjemalloc1`, `libaio1`, and `libmecab2`.

docs/apt-pinning.md

@@ -1,15 +1,22 @@
 # Apt pinning the Percona Server for MySQL 8.0 packages
 
-Pinning allows you to stay on a release and get packages from a different version. In some cases, you can pin selected packages and avoid accidentally upgrading all the packages. 
+Apt pinning is a feature in Debian and its derivatives like Ubuntu, allowing you to prioritize package versions from different repositories. When you pin the Percona Server for MySQL 8.0 packages, you tell your system's package manager to prefer this specific version over others available in different repositories. This ability is beneficial when you want to ensure that you're running a specific version of Percona Server for MySQL due to compatibility or stability reasons, despite newer versions available elsewhere.
 
+To apt pin Percona Server for MySQL 8.0, you must first open the `/etc/apt/preferences.d/` directory and create a new file for the Percona Server package. In this file, you will specify the package name followed by a pinning priority. A higher priority ensures that the version of Percona Server you wish to install is preferred over other versions. 
+
+You should include the version number of the Percona Server in the 'Package' field to identify the package. 
+
+Then, assign a priority in the 'Pin-Priority' field; a common practice is to set it above 1000 to prioritize it over other packages. 
 The pinning takes place in the `preference` file. To pin a package, set the `Pin-Priority` to higher numbers. 
 
 Make a new file `/etc/apt/preferences.d/00percona.pref`. For example, add the following to the `preference` file:
 
-```text
+```{.text .no-copy}
 Package: 
 Pin: release o=Percona Development Team
 Pin-Priority: 1001
 ```
 
-For more information about the pinning, you can check the official [debian wiki](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences).
+Save this file and update your package lists with `sudo apt update`. Finally, install Percona Server for MySQL 8.0 with `sudo apt install percona-server-server-8.0`, and apt will adhere to your pinning preferences.
+
+For more information, see [debian wiki on AptConfiguration](https://wiki.debian.org/AptConfiguration?action=show&redirect=AptPreferences).

docs/apt-repo.md

@@ -9,56 +9,67 @@ We gather [Telemetry data] in the Percona packages and Docker images.
 
 ## Install Percona Server for MySQL using APT
 
-1. Update the package repositories:
+1. This command line instruction uses the `apt` command to update the package lists for upgrades and new package installations.
+
+	*	`sudo` is a command that allows you to run programs with the security privileges of another user, by default, as the superuser. Updating the package lists typically requires superuser or 'root' privileges.
+
+	*	`apt` is a command-line interface that handles package management in Debian and its derivatives. 
+
+	* `update` option resynchronizes the package index files from the sources specified in the system's `sources.list` file. You should run this command regularly to get the latest package updates.
+
 
 	```{.bash data-prompt="$"}
 	$ sudo apt update
 	```
 
-2. Install the `curl` download utility if needed:
+2. This command line instruction uses superuser privileges to install the `curl` package using the `apt` package manager. `curl` is a command-line tool used to transfer data using various network protocols.
 
 	```{.bash data-prompt="$"}
 	$ sudo apt install curl
 	```
 
-3. Download the `percona-release` repository package:
+3. This command line instruction uses `curl` to download the `percona-release_latest.generic_all.deb` file from the `https://repo.percona.com/apt` location.
+
+	The `-0` option saves the downloaded file with the same name used in the URL.
 
 	```{.bash data-prompt="$"}
 	$ curl -O https://repo.percona.com/apt/percona-release_latest.generic_all.deb
 	```
 
-4. Install the downloaded package with `apt` as root or with sudo:
+4. The following command uses the `apt` command to install multiple packages. `gnupg2` is the GNU Privacy Guard that provides cryptographic privacy and authentication. `lsb-release` is a Linux utility that provides certain Linux Standard Base (LSB) and distribution-specific information. `./percona-release_latest.generic_all.deb` is a Debian package in the current directory. 
+
 
 	```{.bash data-prompt="$"}
 	$ sudo apt install gnupg2 lsb-release ./percona-release_latest.generic_all.deb
 	```
 
 
-5. Refresh the local cache to update the package information:
+5. The following command uses superuser privileges to update the package lists from the repositories so that the system knows about the latest versions of packages and their dependencies.
 
 	```{.bash data-prompt="$"}
 	$ sudo apt update
 	```
 
-6. Use `percona-release` to set up the repository for the Percona Server for MySQL 8.0 version:
+6. This command line instruction uses `percona-release` command, a tool provided by Percona, to set up a specific Percona Server version. 
 
 	```{.bash data-prompt="$"}
 	$ sudo percona-release setup ps80
 	```
 
-7. You can check the repository setup for the Percona original release list in `/etc/apt/sources.list.d/percona-original-release.list`. 
+7. You can check the repository setup for the Percona original release list in `/etc/apt/sources.list.d/percona-original-release.list`. The APT system uses this file to know where to find updates and new packages for Percona software.
 
-8. Install the server package with the `percona-release` command:
+8. This command uses the `apt` command to install the `percona-server-server` package.
 
 	```{.bash data-prompt="$"}
 	$ sudo apt install percona-server-server
 	```
 
 See [Configuring Percona repositories with `percona-release`](https://docs.percona.com/percona-software-repositories/percona-release.html) for more information.
 
---8<--- "storage-engines.md"
 
-Percona Server for MySQL contains user-defined functions from [Percona Toolkit](https://docs.percona.com/percona-toolkit/). These user-defined functions provide faster checksums. For more details on the user-defined functions, see [Percona Toolkit UDF functions](https://www.percona.com/doc/percona-server/8.0/management/udf_percona_toolkit.html).
+Starting with Percona Server for MySQL 8.0.28-19 (2022-05-12), the TokuDB storage engine is no longer supported. For more information, see the [TokuDB Introduction](tokudb-intro.md) and [TokuDB version changes](tokudb-version-changes.md). 
+
+Percona Server for MySQL contains user-defined functions from the [Percona Toolkit](https://docs.percona.com/percona-toolkit/). These user-defined functions provide faster checksums. For more details on the user-defined functions, see [Percona Toolkit UDF functions](udf-percona-toolkit.md).
 
 After the installation completes, run the following commands to create these functions:
 
@@ -70,13 +81,12 @@ mysql -e "CREATE FUNCTION murmur_hash RETURNS INTEGER SONAME 'libmurmur_udf.so'"
 
 ## Install the Percona Testing repository using APT
 
-Percona offers pre-release builds from the testing repository. To enable it, run
-percona-release with the `testing` argument. Run the following command as root or use the sudo command:
+Percona offers pre-release builds from the testing repository. As a superuser, run `percona-release` with the `testing` argument to enable it.
 
 ```{.bash data-prompt="$"}
 $ sudo percona-release enable ps80 testing
 ```
 
-These builds should not be run in production. This build may not contain all of the features available in the final release. The features may change without notice.
+Do not run testing repository builds in production. The build may not contain all the features available in the final release and may change without notice.
 
 [Telemetry data]: telemetry.md

docs/apt-uninstall-server.md

@@ -1,15 +1,39 @@
 # Uninstall Percona Server for MySQL 8.0 using the APT package manager
 
-To uninstall Percona Server for MySQL you’ll need to remove all the installed
-packages. Removing packages with apt remove does not remove the
-configuration and data files. Removing the packages with apt purge does remove the packages with configuration files and data files (all
-the databases). Depending on your needs you can choose which command better
-suits you.
+To uninstall Percona Server for MySQL, you must remove all the installed
+packages. Removing packages with `apt remove` does not remove the
+configuration and data files. Removing the packages with `apt purge` does remove the packages with configuration files and data files (all the databases). Depending on your needs, you can choose which command best suits you.
 
-1. Stop the Percona Server for MySQL service: `service mysql stop`
+1. To uninstall Percona Server for MySQL, you must stop the Percona Server for MySQL service:
 
-2. Remove the packages
+    ```{.bash data-prompt="$"} 
+    $ sudo systemctl stop mysql
+    ```
 
-    1. Remove the packages. This will leave the data files (databases, tables, logs, configuration, etc.) behind. In case you don’t need them you’ll need to remove them manually: `apt remove percona-server\`
+2. Remove the Percona Server for MySQL packages. You can use either command.
+
+    a. The command, `apt remove` removes only the packages. This operation does not remove the data files (databases, tables, logs, configuration, and other files). 
+        ```{.bash data-prompt="$"}
+        $ sudo apt remove percona-server\
+        ```
+
+        If you do not need these remaining files, remove them manually.
+
+    b. This command removes all the packages and any associated configuration files. This action ensures the complete removal of the packages from the system. 
+    
+        ```{.bash data-prompt="$"}
+        $ sudo apt purge percona-server\`
+        ```
+
+3. To ensure associated packages are removed, run the following command:
+
+    ```{.bash data-prompt="$"}
+    $ sudo apt autoremove
+    ```
+
+4. You can manually remove the data directory by executing the following command. Back up any of the necessary data before deleting the files.
+
+    ```{.bash data-prompt="$"}
+    $ sudo rm -rf /var/lib/mysql/
+    ```
 
-    2. Purge the packages. This command removes all the packages and deletes all the data files (databases, tables, logs, and so on.): `apt purge percona-server\`

docs/fast-updates.md

@@ -1,14 +1,7 @@
 # Fast updates with TokuDB
 
-!!! important
+Starting with Percona Server for MySQL 8.0.28-19 (2022-05-12), the TokuDB storage engine is no longer supported. For more information, see the [TokuDB Introduction](tokudb-intro.md) and [TokuDB version changes](tokudb-version-changes.md). 
 
-    Starting with [Percona Server for MySQL 8.0.28-19](release-notes/Percona-Server-8.0.28-19.md), the TokuDB storage engine is no longer supported. We have removed the storage engine from the installation packages and disabled the storage engine in our binary builds.
-
-    Starting with [Percona Server for MySQL 8.0.26-16](release-notes/Percona-Server-8.0.26-16.md), the binary builds and packages include but disable the TokuDB storage engine plugins. The tokudb_enabled option and the tokudb_backup_enabled option control the state of the plugins and have a default setting of FALSE. The result of attempting to load the plugins are the plugins fail to initialize and print a deprecation message.
-
-    We recommend [Migrating the data to the MyRocks storage engine](https://docs.percona.com/percona-server/latest/tokudb/removing_tokudb.html#migrate-myrocks). To enable the plugins to migrate to another storage engine, set the tokudb_enabled and tokudb_backup_enabled options to TRUE in your my.cnf file and restart your server instance. Then, you can load the plugins.
-
-    The TokuDB storage engine was declared as deprecated in [Percona Server for MySQL 8.0](release-notes/Percona-Server-8.0.13-3.md). For more information, see the Percona blog post: [Heads-Up: TokuDB Support Changes and Future Removal from Percona Server for MySQL 8.0](https://www.percona.com/blog/2021/05/21/tokudb-support-changes-and-future-removal-from-percona-server-for-mysql-8-0/).
 
 ## Introduction
 

docs/installation.md

@@ -1,18 +1,16 @@
 # Install Percona Server for MySQL
 
-Before installing, review the [Percona Server for MySQL 8.0 Release notes](release-notes/release-notes_index.md) for your version.
+Before installing, review the [Percona Server for MySQL 8.0 Release notes](release-notes/release-notes_index.md).
 
 We gather [Telemetry data] in the Percona packages and Docker images.
 
-We recommend using the repositories that Percona provides to simplify the installation process. The percona-release tool makes it easy to install and update your software and its dependencies using your operating system package manager.
+We recommend using the repositories that Percona provides to simplify the installation process. The `percona-release` tool makes installing and updating your software and its dependencies easy using your operating system package manager. The Percona Software repositories contain YUM (`RPM` packages for Red Hat Enterprise Linux and derivatives) and APT (`DEB` packages for Ubuntu and Debian) for Percona software such as Percona Server for MySQL, Percona XtraBackup, and Percona Toolkit.
 
-The Percona Software repositories contain YUM (`RPM` packages for Red Hat Enterprise Linux and derivatives) and APT (`DEB` packages for Ubuntu and Debian) for Percona software such as Percona Server for MySQL, Percona XtraBackup, and Percona Toolkit.
+For more information, see [Percona Software repositories and the percona-release tool].
 
-For more information see,  [Percona Software repositories and the percona-release tool].
+To get started quickly, use the [Quickstart guide]. You can find instructions for either Docker or installing with a package manager.
 
-To get started quickly, use the [Quickstart guide].You can find instructions to either use Docker or install Percona Server for MySQL using your package manager.
-
-The following guides describe the installation procedures for using the official Percona Software repositories for either the `.deb` and `.rpm` packages.
+The following guides describe the installation procedures for using the official Percona Software repositories.
 
 * [Install Percona Server for MySQL on Debian and Ubuntu](apt-repo.md)