PXB-3639 [Docs] add --parallel option for incremental prepare 8.0

docs/accelerate-backup-process.md

@@ -23,8 +23,8 @@ If the data is stored on a single file, this option will have no effect.
 
 To use this feature, simply add the option to a local backup, for example:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --backup --parallel=4 --target-dir=/path/to/backup
+```shell
+xtrabackup --backup --parallel=4 --target-dir=/path/to/backup
 ```
 
 By using the *xbstream* in streaming backups, you can additionally speed up the
@@ -34,8 +34,8 @@ compression. The default value for this option is 1.
 
 To use this feature, simply add the option to a local backup, for example:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --backup --stream=xbstream --compress --compress-threads=4 --target-dir=./ > backup.xbstream
+```shell
+xtrabackup --backup --stream=xbstream --compress --compress-threads=4 --target-dir=./ > backup.xbstream
 ```
 
 Before applying logs, compressed files will need to be uncompressed.

docs/encrypted-innodb-tablespace-backups.md

@@ -79,8 +79,7 @@ keyring used when the backup was taken and prepared.
 
 ## Use `keyring_vault` plugin
 
-Keyring vault plugin settings are
-described [here](https://docs.percona.com/percona-server/8.0/using-keyring-plugin.html#using-keyring-plugin).
+How to use the keyring vault plugin is described [in this document](https://docs.percona.com/percona-server/8.0/using-keyring-plugin.html).
 
 ### Create a backup with the `keyring_vault` plugin
 
@@ -112,7 +111,7 @@ $ xtrabackup --prepare --target-dir=/data/backup \
 --keyring-vault-config=/etc/vault.cnf
 ```
 
-Review [using the keyring vault plugin](https://docs.percona.com/percona-server/8.0/using-keyring-plugin.html#using-keyring-plugin) for a description of keyring vault plugin settings.
+How to use the keyring vault plugin is described [in this document](https://docs.percona.com/percona-server/8.0/using-keyring-plugin.html).
 
 After *xtrabackup* completes the action, the following message confirms
 the action:
@@ -336,18 +335,38 @@ $ xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \
 --keyring-file-data=/var/lib/mysql-keyring/keyring
 ```
 
-The backup should be prepared with the keyring file and type that was used when backup was being taken. This means that if the keyring has been rotated, or you have upgraded from a plugin to a component between the base and incremental backup that you must use the keyring that was in use when the first incremental backup has been taken.
+!!! note
+
+    If you have many InnoDB Data (IBD) files, speed up the prepare phase for incremental backups  by using the `--parallel` option. This option lets you process multiple delta files simultaneously. When using `--parallel` in the prepare phase, always specify a numeric value. The recommended minimum value is 4 (for example, `--parallel=4`).
+
+    An example of the backup command using the `--parallel` option:
+
+    ```shell
+    xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \
+    --incremental-dir=/data/backups/inc1 \
+    --keyring-file-data=/var/lib/mysql-keyring/keyring --parallel=4
+    ```
+
+Prepare the backup using the same keyring file and type that were used when the backup was created. If the keyring has changed or you upgraded from a plugin to a component between the base and incremental backup, use the keyring from when the first incremental backup was made. If the original keyring is missing or has changed, recover or replace it before restoring. If you cannot recover the keyring, restore from a backup that matches the most recent available keyring.
 
 Preparing the second incremental backup is a similar process: apply the
 deltas
-to the (modified) base backup, and you will roll its data forward in 
+to the (modified) base backup, and you will roll the base backup's data forward in 
 time to the point of the second incremental backup:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --prepare --target-dir=/data/backups/base \
+```shell
+xtrabackup --prepare --target-dir=/data/backups/base \
 --incremental-dir=/data/backups/inc2 \
 --keyring-file-data=/var/lib/mysql-keyring/keyring
 ```
+
+You can also use the `--parallel` option here to speed up the process:
+
+```shell
+xtrabackup --prepare --target-dir=/data/backups/base \
+--incremental-dir=/data/backups/inc2 \
+--keyring-file-data=/var/lib/mysql-keyring/keyring --parallel=4
+```
 Use `--apply-log-only` when merging all incremental backups except the last one. That’s why the previous line does not contain the `--apply-log-only` option. Even if the `--apply-log-only` was used on the last step, backup would still be consistent but in that case  server would perform the rollback phase.
 
 The backup is now prepared and can be restored with `--copy-back` option.
@@ -391,8 +410,8 @@ The `--transition-key=<passphrase>` option should be used to make it possible fo
 The following example illustrates how the backup can be created in this
 case:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --backup --user=root -p --target-dir=/data/backup \
+```shell
+xtrabackup --backup --user=root -p --target-dir=/data/backup \
 --transition-key=MySecretKey
 ```
 
@@ -404,8 +423,8 @@ xtrabackup scrapes `--transition-key` so that its value is not visible in the `p
 
 The same passphrase should be specified for the prepare command:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --prepare --target-dir=/data/backup \
+```shell
+xtrabackup --prepare --target-dir=/data/backup \
 --transition-key=MySecretKey
 ```
 
@@ -417,16 +436,16 @@ because *xtrabackup* does not talk to the keyring in this case.
 
 When restoring a backup you will need to generate a new master key. Here is the example for `keyring_file` plugin or component:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
+```shell
+xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
 --transition-key=MySecretKey --generate-new-master-key \
 --keyring-file-data=/var/lib/mysql-keyring/keyring
 ```
 
 In case of `keyring_vault`, it will look like this:
 
-```{.bash data-prompt="$"}
-$ xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
+```shell
+xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
 --transition-key=MySecretKey --generate-new-master-key \
 --keyring-vault-config=/etc/vault.cnf
 ```
@@ -442,39 +461,39 @@ In this scenario, the three stages of the backup process look as follows.
 
 * Backup
 
-  ```{.bash data-prompt="$"}
-  $ xtrabackup --backup --user=root -p --target-dir=/data/backup \
+  ```shell
+  xtrabackup --backup --user=root -p --target-dir=/data/backup \
   --generate-transition-key
   ```
 
 * Prepare
 
     - `keyring_file` variant:
 
-      ```{.bash data-prompt="$"}
-      $ xtrabackup --prepare --target-dir=/data/backup \
+      ```shell
+      xtrabackup --prepare --target-dir=/data/backup \
       --keyring-file-data=/var/lib/mysql-keyring/keyring
       ```
 
     - `keyring_vault` variant:
 
-      ```{.bash data-prompt="$"}
-      $ xtrabackup --prepare --target-dir=/data/backup \
+      ```shell
+      xtrabackup --prepare --target-dir=/data/backup \
       --keyring-vault-config=/etc/vault.cnf
       ```
 
 * Copy-back
 
   - `keyring_file` variant:
 
-    ```{.bash data-prompt="$"}
-    $ xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
+    ```shell
+    xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
     --generate-new-master-key --keyring-file-data=/var/lib/mysql-keyring/keyring
     ```
 
   - `keyring_vault` variant:
 
-    ```{.bash data-prompt="$"}
-    $ xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
+    ```shell
+    xtrabackup --copy-back --target-dir=/data/backup --datadir=/data/mysql \
     --generate-new-master-key --keyring-vault-config=/etc/vault.cnf
     ```

docs/prepare-incremental-backup.md

@@ -1,30 +1,16 @@
 # Prepare an incremental backup
 
-The `--prepare` step for incremental backups is not the same
-as for full backups. In full backups, two types of operations are performed
-to
-make the database consistent: committed transactions are replayed from the
-log
-file against the data files, and uncommitted transactions are rolled back.
-You
-must skip the rollback of uncommitted transactions when preparing an
-incremental backup, because transactions that were uncommitted at the time
-of
-your backup may be in progress, and it’s likely that they will be committed
-in
-the next incremental backup. You should use the
-`--apply-log-only` option to prevent the rollback phase.
+The `--prepare` step for incremental backups differs from full backups. For full backups, committed transactions are replayed from the log file to the data files, and uncommitted transactions are rolled back to ensure consistency. When preparing an incremental backup, you must skip the rollback of uncommitted transactions, as these may still be in progress and could be committed in a subsequent incremental backup. Use the `--apply-log-only` option when preparing the first full backup to prevent the rollback phase from occurring.
 
 !!! warning
 
-    **If you do not use the** `--apply-log-only` **option to prevent the rollback phase, then your incremental backups will be useless**. After transactions have been rolled back, further incremental backups cannot be applied.
+    If you do not use the `--apply-log-only` option to prevent the rollback phase, then your incremental backups are unusable. After transactions have been rolled back, further incremental backups cannot be applied.
 
-Beginning with the full backup you created, you can prepare it, and then
-apply
-the incremental differences to it. Recall that you have the following
-backups:
+Start by preparing the full backup, then apply the incremental differences to that backup.  
 
-```
+For example, you could have the following backups:
+
+```text
 /data/backups/base
 /data/backups/inc1
 /data/backups/inc2
@@ -33,11 +19,11 @@ backups:
 To prepare the base backup, you need to run `--prepare` as
 usual, but prevent the rollback phase:
 
-```{.bash data-prompt="$"}
+```shell
 $ xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base
 ```
 
-The output should end with text similar to the following:
+The log sequence number should match the `to_lsn` of the base backup The output should end with text similar to the following:
 
 ??? example "Expected output"
 
@@ -46,25 +32,22 @@ The output should end with text similar to the following:
     161011 12:41:04 completed OK!
     ```
 
-The log sequence number should match the `to_lsn` of the base backup, which
-you saw previously.
-
 !!! warning
 
-    This backup is actually safe to restore as-is now, even though the rollback phase has been skipped. If you restore it and start *MySQL*, *InnoDB* will detect that the rollback phase was not performed, and it will do that in the background, as it usually does for a crash recovery upon start. It will notify you that the database was not shut down normally.
+    This backup is actually safe to restore as-is now, even though the rollback phase has been skipped. If you restore the backup and start the server, InnoDB detects that the rollback phase was not performed, and completes the rollback in the background, as InnoDB usually does for a crash recovery. InnoDB notifies you that the database was not shut down normally.
 
 To apply the first incremental backup to the full backup, run the following command:
 
-```{.bash data-prompt="$"}
+```shell
 $ xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \
 --incremental-dir=/data/backups/inc1
 ```
 
-This applies the delta files to the files in `/data/backups/base`, which
-rolls them forward in time to the time of the incremental backup. It then
-applies the redo log as usual to the result. The final data is in
-`/data/backups/base`, not in the incremental directory. You should see
-an output similar to:
+This command applies the delta files to the files in `/data/backups/base`, which
+rolls them forward in time to the time of the incremental backup. The redo log is then applied as usual. The final data is in
+`/data/backups/base`, not in the incremental directory.
+
+You should see an output similar to:
 
 ??? example "Expected output"
 
@@ -84,20 +67,46 @@ Again, the LSN should match what you saw from your earlier inspection of
 the first incremental backup. If you restore the files from
 `/data/backups/base`, you should see the state of the database as of the first incremental backup.
 
-!!! warning
+### Faster prepare step with --parallel
+
+For incremental backups with many InnoDB Data (IBD) files, you can significantly reduce prepare time by using the `--parallel` option. The `--parallel` option enables the concurrent processing of multiple delta files, thereby maximizing storage bandwidth. The `--parallel` option is especially beneficial when there are many IBD files, even if the IBD files didn't change between backups, as empty delta files are processed quickly in parallel. 
+
+!!! note "Version history"
+
+    Before Percona XtraBackup 8.0.35-33 and 8.4.0-3, the `--parallel` option didn't have any effect on the prepare phase.
+
+    Starting with Percona XtraBackup 8.0.35-33 and 8.4.0-3, using `--parallel=X` has effect on the prepare phase. It will now use X threads to apply the changes from `.delta` files to the IBD files. When using `--parallel` in the prepare phase, always specify a numeric value. The recommended minimum value is 4 (for example, `--parallel=4`).
+
+    Note that each thread operates on a single file. If you have a large delta file, there is still only one thread that processes that `.delta` file. Parallelization occurs at the file level, not within individual files.
+
+An example command with the `--parallel` option:
+
+```shell
+$ xtrabackup --prepare --parallel=4 --apply-log-only --target-dir=/data/backups/base \
+--incremental-dir=/data/backups/inc1
+```
+
+### Prepare a second inceremental backup
 
-    *Percona XtraBackup* does not support using the same incremental backup directory to prepare two copies of backup. Do not run `--prepare` with the same incremental backup directory (the value of –incremental-dir) more than once.
+Percona XtraBackup does not support using the same incremental backup directory to prepare two copies of backup. Do not run `--prepare` with the same incremental backup directory (the value of –incremental-dir) more than once.
 
 Preparing the second incremental backup is a similar process: apply the deltas
-to the (modified) base backup, and you will roll its data forward in time to the point of the second incremental backup:
+to the (modified) base backup, and you will roll the base backup's data forward in time to the point of the second incremental backup:
 
-```{.bash data-prompt="$"}
+```shell
 $ xtrabackup --prepare --target-dir=/data/backups/base \
 --incremental-dir=/data/backups/inc2
 ```
 
+You can also use the `--parallel` option here to speed up the process:
+
+```shell
+$ xtrabackup --prepare --parallel=4 --target-dir=/data/backups/base \
+--incremental-dir=/data/backups/inc2
+```
+
 !!! note
 
-    `--apply-log-only` should be used when merging the incremental backups except the last one. That’s why the previous line does not contain the `--apply-log-only` option. Even if the `--apply-log-only` was used on the last step, backup would still be consistent but in that case server would perform the rollback phase.
+    Use `--apply-log-only` when merging the incremental backups except for the last one. This is why the previous command does not include the `--apply-log-only` option. If `--apply-log-only` is used on the last step, backup remains consistent but the server performs the rollback phase.
 
 Once prepared incremental backups are the same as the full backups, and they can be [restored](restore-a-backup.md) in the same way.

docs/release-notes/8.0/8.0.35-33.0.md

@@ -16,7 +16,7 @@ We recommend that you download the Percona XtraBackup for the same platform as t
 
 ## Improvements
 
-* [PXB-3427]: Percona XtraBackup now prepares incremental backups faster. The `--prepare` command directly applies the `.delta` files. To speed up this process, use the `--parallel=X` option, replacing `X` with the number of threads you want to use simultaneously. This option applies the delta files concurrently.
+* [PXB-3427]: Percona XtraBackup now prepares incremental backups faster. The `--prepare` command directly applies the `.delta` files. To speed up this process, use the [`--parallel=X`](../../xtrabackup-option-reference.md#parallel) option, replacing `X` with the number of threads you want to use simultaneously. This option applies the delta files concurrently. For more information, see [Prepare an incremental backup](../../prepare-incremental-backup.md#faster-prepare-step-with---parallel).
 
 * [PXB-3199]: The `xbcloud put` operations were updated to include support for [ObjectLock-enabled AWS S3 buckets] (Thanks to volver for contributing the fix for this issue.).