From fc87ea6b2fec16b6ebda4bb8dcdf40a3e872513d Mon Sep 17 00:00:00 2001 From: Alina Derkach Date: Thu, 29 Oct 2026 19:19:42 +0100 Subject: [PATCH] PXB-3911 [DOCS] Document --apply-redo-only alias to --apply-log-only (9.7) modified: docs/encrypted-innodb-tablespace-backups.md modified: docs/innodb-btree-check.md modified: docs/prepare-full-backup.md modified: docs/prepare-incremental-backup.md modified: docs/xbcloud-binary-overview.md modified: docs/xtrabackup-option-reference.md --- docs/encrypted-innodb-tablespace-backups.md | 16 +++++--- docs/innodb-btree-check.md | 8 +++- docs/prepare-full-backup.md | 12 ++++-- docs/prepare-incremental-backup.md | 42 +++++++++++---------- docs/xbcloud-binary-overview.md | 12 ++++-- docs/xtrabackup-option-reference.md | 19 ++++++++-- 6 files changed, 72 insertions(+), 37 deletions(-) diff --git a/docs/encrypted-innodb-tablespace-backups.md b/docs/encrypted-innodb-tablespace-backups.md index 9eb37966d..b6d2e6d8e 100644 --- a/docs/encrypted-innodb-tablespace-backups.md +++ b/docs/encrypted-innodb-tablespace-backups.md @@ -184,18 +184,22 @@ xtrabackup --backup --target-dir=/data/backups/inc2 \ #### Phase 2: Prepare -The `--prepare` step for incremental backups requires the keyring configuration. Use [`--apply-log-only`](xtrabackup-option-reference.md#apply-log-only) for all incremental backups except the last one to prevent rolling back transactions that might be committed in subsequent incremental backups. +##### Version changes -Beginning with the full backup, prepare the full backup and then apply the incremental differences. Prepare the base backup with [`--apply-log-only`](xtrabackup-option-reference.md#apply-log-only). Use the appropriate configuration file name for your keyring component (see [Configuration file name requirements](#configuration-file-name-requirements)): +Percona XtraBackup 9.7.2-2 renames the `--apply-log-only` option to [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Percona XtraBackup still accepts `--apply-log-only` but prints a deprecation warning. A future Long-Term Support (LTS) release will remove `--apply-log-only`, so update your scripts to use `--apply-redo-only`. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + +The `--prepare` step for incremental backups requires the keyring configuration. Use [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only) for all incremental backups except the last one. The option prevents the rollback of transactions that a later incremental backup might commit. + +Beginning with the full backup, prepare the full backup and then apply the incremental differences. Prepare the base backup with [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Use the appropriate configuration file name for your keyring component (see [Configuration file name requirements](#configuration-file-name-requirements)): ```shell -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base ``` Apply the first incremental backup to the full backup using [`--incremental-dir`](xtrabackup-option-reference.md#incremental-dir): ```shell -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ --incremental-dir=/data/backups/inc1 ``` @@ -206,7 +210,7 @@ xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ An example of the backup command using the `--parallel` option: ```shell - xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ + xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ --incremental-dir=/data/backups/inc1 --parallel=4 ``` @@ -230,7 +234,7 @@ xtrabackup --prepare --target-dir=/data/backups/base \ !!! note - Use [`--apply-log-only`](xtrabackup-option-reference.md#apply-log-only) when merging all 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. + Use [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only) for every incremental backup except the last one. The previous command applies the last incremental backup, so the command does not include `--apply-redo-only`. If you use `--apply-redo-only` on the last step, the backup stays consistent, but the server runs the rollback phase. #### Phase 3: Restore diff --git a/docs/innodb-btree-check.md b/docs/innodb-btree-check.md index 53f548e63..4f55d1350 100644 --- a/docs/innodb-btree-check.md +++ b/docs/innodb-btree-check.md @@ -4,6 +4,10 @@ The [`--check-tables`](xtrabackup-option-reference.md#check-tables) option validates the structural integrity of InnoDB B-tree indexes during the [`--prepare`](xtrabackup-option-reference.md#prepare) phase. Validation during `--prepare` helps detect corrupted indexes before restore or production deployment. +### Version changes + +Percona XtraBackup 9.7.2-2 renames the `--apply-log-only` option to [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Percona XtraBackup still accepts `--apply-log-only` but prints a deprecation warning. A future Long-Term Support (LTS) release will remove `--apply-log-only`, so update your scripts to use `--apply-redo-only`. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + ## Why checksum validation is not enough Percona XtraBackup verifies InnoDB page checksums during `--backup`. These checks ensure that the backup contains checksum-valid pages at backup time. @@ -64,7 +68,7 @@ The option also works with: * [Parallel execution](#parallel-execution) through [`--parallel`](xtrabackup-option-reference.md#parallel) -* Workflows that use [`--apply-log-only`](xtrabackup-option-reference.md#apply-log-only) +* Workflows that use [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only) * Transportable tablespace export with [`--export`](xtrabackup-option-reference.md#export) @@ -142,7 +146,7 @@ xtrabackup --prepare --check-tables \ ### Validate an incremental backup -The `--check-tables` option can be used together with `--apply-log-only`. However, because validation scans all tables and indexes each time it runs, it's recommended using the option during the final prepare stage of an incremental backup. +You can use `--check-tables` together with `--apply-redo-only`. Validation scans all tables and indexes on every run, so use `--check-tables` during the final prepare stage of an incremental backup. ```bash xtrabackup --prepare --check-tables \ diff --git a/docs/prepare-full-backup.md b/docs/prepare-full-backup.md index f0ec17aae..eaba38df8 100644 --- a/docs/prepare-full-backup.md +++ b/docs/prepare-full-backup.md @@ -1,18 +1,22 @@ # Prepare a full backup +## Version changes + +Percona XtraBackup 9.7.2-2 renames the `--apply-log-only` option to [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Percona XtraBackup still accepts `--apply-log-only` but prints a deprecation warning. A future Long-Term Support (LTS) release will remove `--apply-log-only`, so update your scripts to use `--apply-redo-only`. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + ## Command reference Quick syntax for preparing a full backup: ```bash -xtrabackup --prepare --target-dir= [--apply-log-only] [--parallel=] +xtrabackup --prepare --target-dir= [--apply-redo-only] [--parallel=] ``` | Flag | Required | Description | |------|----------|-------------| | `--prepare` | Yes | Runs xtrabackup in prepare mode (applies redo/undo logs for a consistent snapshot). | | `--target-dir=` | Yes | Directory containing the backup to prepare. | -| `--apply-log-only` | No | Apply log only; do not roll back uncommitted transactions. Use when this backup will be the base for incremental backups. | +| `--apply-redo-only` | No | Applies the redo log without rolling back uncommitted transactions. Use the option when the backup is the base for incremental backups. Replaces the deprecated `--apply-log-only` option. | | `--parallel=` | No | Use N threads to speed up prepare (for example, `--parallel=4`). | Example (full backup, then restore): @@ -24,7 +28,7 @@ xtrabackup --prepare --target-dir=/data/backups/ Example (base for incremental backups): ```bash -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/ +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/ ``` --- @@ -70,7 +74,7 @@ It is not recommended to interrupt xtrabackup process while preparing backup bec !!! note - If you intend the backup to be the basis for further incremental backups, you should use the `--apply-log-only` option when preparing the backup, or you will not be able to apply incremental backups to it. See the documentation on preparing incremental backups for more details. + If you plan to apply incremental backups to the backup, use the `--apply-redo-only` option when you prepare the backup. Without the option, you cannot apply incremental backups. For details, see [Prepare an incremental backup](prepare-incremental-backup.md). ## Next step diff --git a/docs/prepare-incremental-backup.md b/docs/prepare-incremental-backup.md index c3a586798..1e67e77a1 100644 --- a/docs/prepare-incremental-backup.md +++ b/docs/prepare-incremental-backup.md @@ -30,24 +30,28 @@ The `--prepare` step for incremental backups differs from the prepare step for f When preparing an incremental chain, you must delay the rollback of uncommitted transactions until you apply the final incremental backup. A transaction that was uncommitted when one backup was created might be committed in a later incremental backup. -Use `--apply-log-only` to apply redo without rolling back uncommitted transactions. +### Version changes + +Percona XtraBackup 9.7.2-2 renames the `--apply-log-only` option to [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Percona XtraBackup still accepts `--apply-log-only` but prints a deprecation warning. A future Long-Term Support (LTS) release will remove `--apply-log-only`, so update your scripts to use `--apply-redo-only`. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + +Use `--apply-redo-only` to apply the redo log without rolling back uncommitted transactions. !!! warning - 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. + If you skip `--apply-redo-only`, Percona XtraBackup rolls back uncommitted transactions, and you cannot apply more incremental backups. Prepare an incremental backup chain in the following order: -1. Prepare the full backup with `--apply-log-only`. -2. Apply each intermediate incremental backup in order with `--apply-log-only`. -3. Apply the final incremental backup without `--apply-log-only`. +1. Prepare the full backup with `--apply-redo-only`. +2. Apply each intermediate incremental backup in order with `--apply-redo-only`. +3. Apply the final incremental backup without `--apply-redo-only`. ## Prepare the full backup -Start by preparing the full backup with `--apply-log-only` to prevent the rollback phase: +Start by preparing the full backup with `--apply-redo-only` to prevent the rollback phase: ```shell -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base ``` The log sequence number (LSN) identifies a point in the database redo log. Incremental backups use LSNs to identify which changes occurred after the base backup. @@ -83,7 +87,7 @@ Percona XtraBackup applies the changes from each incremental backup to `/data/ba Apply the first incremental backup to the full backup: ```shell -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ --incremental-dir=/data/backups/inc1 ``` @@ -91,7 +95,7 @@ xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ The command applies the delta files from `/data/backups/inc1` to the files in `/data/backups/base`, moving the full backup forward to the state of the first incremental backup. Percona XtraBackup then applies the redo log. -Because another incremental backup follows `inc1`, use `--apply-log-only` to prevent the rollback phase. +Because another incremental backup follows `inc1`, use `--apply-redo-only` to prevent the rollback phase. The final data remains in `/data/backups/base`, not in the incremental directory. @@ -102,7 +106,7 @@ You should see output similar to the following: ```text 2026-10-13T17:24:35.387201-00:00 0 [Note] [MY-011825] [Xtrabackup] incremental backup from 36621132 is enabled. 2026-10-13T17:24:35.387458-00:00 0 [Note] [MY-011825] [Xtrabackup] cd to /data/backups/base/ - 2026-10-13T17:24:35.388208-00:00 0 [Note] [MY-011825] [Xtrabackup] This target seems to be already prepared with --apply-log-only. + 2026-10-13T17:24:35.388208-00:00 0 [Note] [MY-011825] [Xtrabackup] This target seems to be already prepared with --apply-redo-only. 2026-10-13T17:24:35.412988-00:00 0 [Note] [MY-011825] [Xtrabackup] xtrabackup_logfile detected: size=8388608, start_lsn=(37463526) ... 2026-10-13T17:24:35.668534-00:00 1 [Note] [MY-011825] [Xtrabackup] page size for /data/backups/inc1//ibdata1.delta is 16384 bytes @@ -119,7 +123,7 @@ Percona XtraBackup does not support using the same incremental backup directory After applying `/data/backups/inc1`, apply `/data/backups/inc2` to the same base backup. -In this example, `inc2` is the final incremental backup. Apply it without `--apply-log-only`: +In this example, `inc2` is the final incremental backup. Apply it without `--apply-redo-only`: ```shell xtrabackup --prepare --target-dir=/data/backups/base \ @@ -130,19 +134,19 @@ The command applies the changes from `inc2` to `/data/backups/base` and complete !!! note - 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. + Use `--apply-redo-only` for every incremental backup except the last one. The previous command applies the last incremental backup, so the command does not include `--apply-redo-only`. If you use `--apply-redo-only` on the last step, the backup stays consistent, but the server runs the rollback phase. After you apply the final incremental backup, `/data/backups/base` contains the prepared backup with all changes through `inc2`. -If your backup chain contains more incremental backups, apply them in order. Use `--apply-log-only` for every intermediate incremental backup and omit it only when applying the final incremental backup. +If your backup chain contains more incremental backups, apply them in order. Use `--apply-redo-only` for every intermediate incremental backup and omit the option only for the final incremental backup. For example: ```text -base → --apply-log-only -inc1 → --apply-log-only -inc2 → --apply-log-only -inc3 → final incremental, no --apply-log-only +base → --apply-redo-only +inc1 → --apply-redo-only +inc2 → --apply-redo-only +inc3 → final incremental, no --apply-redo-only ``` ## Speed up the prepare step with --parallel @@ -154,11 +158,11 @@ Using `--parallel=X` has effect on the prepare phase. It will use X threads to a To apply an intermediate incremental backup with four worker threads, run: ```shell -xtrabackup --prepare --parallel=4 --apply-log-only --target-dir=/data/backups/base \ +xtrabackup --prepare --parallel=4 --apply-redo-only --target-dir=/data/backups/base \ --incremental-dir=/data/backups/inc1 ``` -You can also use `--parallel` when applying the final incremental backup. Omit `--apply-log-only` for the final step: +You can also use `--parallel` when applying the final incremental backup. Omit `--apply-redo-only` for the final step: ```shell xtrabackup --prepare --parallel=4 --target-dir=/data/backups/base \ diff --git a/docs/xbcloud-binary-overview.md b/docs/xbcloud-binary-overview.md index ab8769597..6c2b704a5 100644 --- a/docs/xbcloud-binary-overview.md +++ b/docs/xbcloud-binary-overview.md @@ -4,6 +4,8 @@ xbcloud is a cloud storage utility that works with Percona XtraBackup to upload, ## What's in this document +* [Version changes](#version-changes) - Option changes in recent releases + * [What xbcloud does](#what-xbcloud-does) - Core operations and capabilities * [Supported cloud storage providers](#supported-cloud-storage-providers) - Available storage options @@ -329,6 +331,10 @@ inc_backup_20240101_1200 #### Step 3: Restore incremental backups +##### Version changes + +Percona XtraBackup 9.7.2-2 renames the `--apply-log-only` option to [`--apply-redo-only`](xtrabackup-option-reference.md#apply-redo-only). Percona XtraBackup still accepts `--apply-log-only` but prints a deprecation warning. A future Long-Term Support (LTS) release will remove `--apply-log-only`, so update your scripts to use `--apply-redo-only`. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + To restore from incremental backups, you must download and prepare them in sequence: ```shell @@ -336,13 +342,13 @@ To restore from incremental backups, you must download and prepare them in seque xbcloud get --storage=s3 --s3-bucket=my-backups --s3-region=us-west-2 \ full_backup_20240101 | xbstream -xv -C /tmp/restore -xtrabackup --prepare --apply-log-only --target-dir=/tmp/restore +xtrabackup --prepare --apply-redo-only --target-dir=/tmp/restore # Download and apply the incremental backup xbcloud get --storage=s3 --s3-bucket=my-backups --s3-region=us-west-2 \ inc_backup_20240101_1200 | xbstream -xv -C /tmp/inc1 -xtrabackup --prepare --apply-log-only --target-dir=/tmp/restore \ +xtrabackup --prepare --apply-redo-only --target-dir=/tmp/restore \ --incremental-dir=/tmp/inc1 # Final prepare step @@ -354,7 +360,7 @@ xtrabackup --prepare --target-dir=/tmp/restore Accelerate the prepare phase for incremental backups with many InnoDB Data (IBD) files by using the `--parallel` option to process delta files concurrently. When using `--parallel` in the prepare phase, always specify a numeric value. The recommended minimum value is 4 (for example, `--parallel=4`). ```shell - xtrabackup --prepare --apply-log-only \ + xtrabackup --prepare --apply-redo-only \ --target-dir=/tmp/restore \ --incremental-dir=/tmp/inc1 --parallel=4 diff --git a/docs/xtrabackup-option-reference.md b/docs/xtrabackup-option-reference.md index 034d8e678..4af8cbaa4 100644 --- a/docs/xtrabackup-option-reference.md +++ b/docs/xtrabackup-option-reference.md @@ -65,8 +65,21 @@ and XtraDB. See [`--innodb-miscellaneous`](#innodb-miscellaneous) for more infor Usage: `--apply-log-only` -This option causes only the redo stage to be performed when preparing a -backup. It is essential for incremental backups. +Deprecated in Percona XtraBackup 9.7.2-2. Use [`--apply-redo-only`](#apply-redo-only) instead. + +The `--apply-log-only` option works the same way as `--apply-redo-only`. When you use `--apply-log-only`, Percona XtraBackup prints a deprecation warning at startup. A future Long-Term Support (LTS) release will remove the option. + +### apply-redo-only + +Usage: `--apply-redo-only` + +Introduced in Percona XtraBackup 9.7.2-2. + +During the `--prepare` phase, Percona XtraBackup applies the redo log and does not roll back uncommitted transactions. Use the `--apply-redo-only` option when you prepare a full backup or an incremental backup that more incremental backups follow. Do not use the option for the final incremental backup. + +The `--apply-redo-only` option replaces the deprecated [`--apply-log-only`](#apply-log-only) option. Both names work the same way. If you pass both options in the same command, Percona XtraBackup reports an error and does not start. + +For details, see [Prepare an incremental backup](prepare-incremental-backup.md). ### backup @@ -118,7 +131,7 @@ Enables InnoDB B-tree structural validation during the `--prepare` phase after r The option runs `btr_validate_index()` on every committed index in each `.ibd` tablespace in the backup. Validation detects structural inconsistencies that page checksum verification cannot detect, including broken B-tree relationships, invalid page metadata, and inconsistent external LOB references. -Percona XtraBackup runs validation in read-only mode and does not modify backup data. The option supports `--apply-log-only`, `--parallel`, and `--export`. +Percona XtraBackup runs validation in read-only mode and does not modify backup data. The option supports `--apply-redo-only`, `--parallel`, and `--export`. If validation detects corruption, xtrabackup reports the affected tables and returns a non-zero exit code after completing all checks.