diff --git a/docs/encrypted-innodb-tablespace-backups.md b/docs/encrypted-innodb-tablespace-backups.md index e4844415..87c4e82c 100644 --- a/docs/encrypted-innodb-tablespace-backups.md +++ b/docs/encrypted-innodb-tablespace-backups.md @@ -188,19 +188,23 @@ 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 [`--prepare-incremental-from-dir`](xtrabackup-option-reference.md#prepare-incremental-from-dir): ```shell -xtrabackup --prepare --apply-log-only --target-dir=/data/backups/base \ ---prepare-incremental-from-dir=/data/backups/inc1 +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ +--incremental-dir=/data/backups/inc1 ``` !!! note @@ -210,8 +214,8 @@ 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 \ - --prepare-incremental-from-dir=/data/backups/inc1 --parallel=4 + xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ + --incremental-dir=/data/backups/inc1 --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. @@ -234,7 +238,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 53f548e6..4f55d135 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 f0ec17aa..eaba38df 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 a40125f3..697c6cb7 100644 --- a/docs/prepare-incremental-backup.md +++ b/docs/prepare-incremental-backup.md @@ -30,17 +30,21 @@ 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`. ## Version changes @@ -48,10 +52,10 @@ Percona XtraBackup 9.7.2-2 renames the `--incremental-dir` option to [`--prepare ## 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. @@ -87,15 +91,15 @@ 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 \ ---prepare-incremental-from-dir=/data/backups/inc1 +xtrabackup --prepare --apply-redo-only --target-dir=/data/backups/base \ +--incremental-dir=/data/backups/inc1 ``` `--target-dir` points to the full backup that you are preparing. `--prepare-incremental-from-dir` points to the incremental backup whose changes you want to apply. 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. @@ -106,7 +110,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 @@ -123,7 +127,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 \ @@ -134,19 +138,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 @@ -158,11 +162,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 \ ---prepare-incremental-from-dir=/data/backups/inc1 +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 538044f7..74c5b40f 100644 --- a/docs/xbcloud-binary-overview.md +++ b/docs/xbcloud-binary-overview.md @@ -335,6 +335,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 @@ -342,14 +346,14 @@ 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 \ ---prepare-incremental-from-dir=/tmp/inc1 +xtrabackup --prepare --apply-redo-only --target-dir=/tmp/restore \ +--incremental-dir=/tmp/inc1 # Final prepare step xtrabackup --prepare --target-dir=/tmp/restore @@ -360,7 +364,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 \ --prepare-incremental-from-dir=/tmp/inc1 --parallel=4 diff --git a/docs/xtrabackup-option-reference.md b/docs/xtrabackup-option-reference.md index 1ee19830..4a6f8663 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 @@ -128,7 +141,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.