diff --git a/docs/about-xtrabackup.md b/docs/about-xtrabackup.md index c4b5c26a..d0a4484f 100644 --- a/docs/about-xtrabackup.md +++ b/docs/about-xtrabackup.md @@ -24,7 +24,7 @@ With Percona XtraBackup you can: ## Support -Percona’s enterprise-grade commercial [MySQL Support :octicons-link-external-16:](http://www.percona.com/mysql-support/) contracts include support for Percona XtraBackup. We recommend support for critical production deployments. +Percona’s enterprise-grade commercial [MySQL Support :octicons-link-external-16:](https://www.percona.com/services/expert-support/) contracts include support for Percona XtraBackup. We recommend support for critical production deployments. ## Supported storage engines diff --git a/docs/backup-strategy.md b/docs/backup-strategy.md index f6dbf60c..62736038 100644 --- a/docs/backup-strategy.md +++ b/docs/backup-strategy.md @@ -91,7 +91,7 @@ You must test the effectiveness of your backups and demonstrate that you can rec |--------|---------| | Perform Regular Test Restores | The most reliable way to test backups is to periodically restore the data to a separate system. This verifies the backup's integrity and the restoration process's functionality. | | Monitor Backup Reports | Regularly review backup reports and logs for any errors or failures during the backup process. This can help identify issues early before they become critical problems. | -| Check for Data Consistency | Compare the original data with the backed-up data to ensure consistency. This can be done by checking file sizes, using checksums, or employing other data validation techniques. You can use [pt-table-checksum](https://docs.percona.com/percona-toolkit/latest/pt-table-checksum.html) from Percona Toolkit. | +| Check for Data Consistency | Compare the original data with the backed-up data to ensure consistency. This can be done by checking file sizes, using checksums, or employing other data validation techniques. You can use [pt-table-checksum](https://docs.percona.com/percona-toolkit/pt-table-checksum.html) from Percona Toolkit. | | Simulate Disaster Scenarios | Conducting a simulated disaster recovery exercise can help determine how well your backup system will perform under stress and identify any gaps in your recovery plan. | | Audit Backup Procedures | Regular audits of the backup procedures can ensure that the backups are being performed in accordance with the established policies and that the backup system is functioning as expected. | | Validate Backup Configuration | Ensure that the backup configuration is correct and that all necessary data is being backed up. This includes checking backup schedules, retention policies, and the scope of the data backed up. | diff --git a/docs/glossary.md b/docs/glossary.md index b75e8194..653522a5 100644 --- a/docs/glossary.md +++ b/docs/glossary.md @@ -186,7 +186,7 @@ To support simultaneous compression and streaming, Percona XtraBackup uses the x ## XtraDB -Percona XtraDB is an enhanced version of the InnoDB storage engine, designed to better scale on modern hardware. Percona XtraDB includes features which are useful in a high performance environment. It is fully backward-compatible, and is a drop-in replacement for the standard InnoDB storage engine. For more information, see [The Percona XtraDB Storage Engine :octicons-link-external-16:](https://www.percona.com/doc/percona-server/innovation-release/percona-xtradb.html). +Percona XtraDB is an enhanced version of the InnoDB storage engine, designed to better scale on modern hardware. Percona XtraDB includes features which are useful in a high performance environment. It is fully backward-compatible, and is a drop-in replacement for the standard InnoDB storage engine. For more information, see [The Percona XtraDB Storage Engine :octicons-link-external-16:](https://docs.percona.com/percona-server/8.4/percona-xtradb.html). ## Zstandard (ZSTD) diff --git a/docs/how-xtrabackup-works.md b/docs/how-xtrabackup-works.md index aa2250fd..51d1ccfe 100644 --- a/docs/how-xtrabackup-works.md +++ b/docs/how-xtrabackup-works.md @@ -16,7 +16,7 @@ The `--register-redo-log-consumer` parameter is disabled by default. When enable Percona XtraBackup remembers the LSN when it starts, and then copies the data files. The operation takes time, and the files may change, then LSN reflects the state of the database at different points in time. Percona XtraBackup also runs a background process that watches the transaction log files, and copies any changes. Percona XtraBackup does this continually. The transaction logs are written in a round-robin fashion, and can be reused. -Percona XtraBackup uses [Backup locks :octicons-link-external-16:](https://docs.percona.com/percona-server/innovation-release/backup-locks.html) where available as a lightweight alternative to `FLUSH TABLES WITH READ LOCK`. MySQL {{vers}} allows acquiring an instance level backup lock via the `LOCK INSTANCE FOR BACKUP` statement. +Percona XtraBackup uses [Backup locks :octicons-link-external-16:](https://docs.percona.com/percona-server/8.4/backup-locks.html) where available as a lightweight alternative to `FLUSH TABLES WITH READ LOCK`. MySQL {{vers}} allows acquiring an instance level backup lock via the `LOCK INSTANCE FOR BACKUP` statement. Locking is only done for MyISAM and other non-InnoDB tables after Percona XtraBackup finishes backing up all InnoDB/XtraDB data and diff --git a/docs/index.md b/docs/index.md index d282958f..465f1634 100644 --- a/docs/index.md +++ b/docs/index.md @@ -8,7 +8,7 @@ Percona XtraBackup is an open source hot backup utility for MySQL-based servers that keep your database fully available during planned maintenance windows. Whether it is a 24x7 highly loaded server or a low-transaction-volume -Percona XtraBackup is designed to make backups seamless without disrupting the performance of the server in a production environment. Percona XtraBackup (PXB) is a 100% open source backup solution with [commercial support :octicons-link-external-16:](https://www.percona.com/mysql-support/) available for organizations who want to benefit from comprehensive, responsive, and cost-flexible database support for MySQL. +Percona XtraBackup is designed to make backups seamless without disrupting the performance of the server in a production environment. Percona XtraBackup (PXB) is a 100% open source backup solution with [commercial support :octicons-link-external-16:](https://www.percona.com/services/expert-support/) available for organizations who want to benefit from comprehensive, responsive, and cost-flexible database support for MySQL. ## Percona XtraBackup features diff --git a/docs/innodb-btree-check.md b/docs/innodb-btree-check.md new file mode 100644 index 00000000..ff79808d --- /dev/null +++ b/docs/innodb-btree-check.md @@ -0,0 +1,245 @@ +# InnoDB B-tree integrity validation during prepare + +## Overview + +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 8.4.0-6 introduces the `--check-tables` option. + +## 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. + +Checksum validation detects physical corruption within individual pages, including: + +* Torn-page corruption + +* Write corruption + +* Transfer corruption + +* Storage or filesystem corruption + +When the server modifies a page while XtraBackup copies it, XtraBackup retries the copy until the checksum becomes consistent. The retry process prevents partially modified pages from entering the backup. + +A successful backup therefore guarantees checksum-valid pages, but checksum validation alone cannot guarantee a fully valid restore. + +### Corruption can happen after backup creation + +A backup can become corrupted after creation because of storage or filesystem issues. + +During `--prepare`, XtraBackup only re-validates pages involved in redo application. Pages outside redo processing may never undergo another checksum check. + +For this reason, running `CHECK TABLE` after restore remains a recommended practice. `CHECK TABLE` forces page reads and validates both checksums and structural consistency. + +### Checksums do not verify page relationships + +Checksum validation only confirms that the bytes within a page match the checksum stored in the page header. + +XtraBackup does not validate B-tree structure or relationships between pages during backup. As a result, structurally corrupted pages can still enter the backup if those pages remain checksum-valid on the source server. + +Structural corruption rarely occurs and usually results from server bugs, backup tool bugs, storage failures, or filesystem-level corruption. + +Structural corruption can break B-tree page relationships, page metadata consistency, and external LOB references. For a complete list of detected corruption conditions, see [Detected corruption conditions](#detected-corruption-conditions). + +## How `--check-tables` works + +The `--check-tables` option executes `btr_validate_index()` on every index that is present and active in the InnoDB data dictionary for each `.ibd` tablespace, using the number of threads specified by [`--parallel`](xtrabackup-option-reference.md#parallel). `--check-tables` detects structural inconsistencies that page checksum verification cannot detect. The option applies only to InnoDB tables. + +Percona XtraBackup runs validation during the `--prepare` phase after applying the redo log. The validation process operates in read-only mode against backup files and does not modify backup contents. Validation continues after detecting corruption so that Percona XtraBackup can report all problematic tables and indexes in a single run. + +For each tablespace, Percona XtraBackup: + +1. Loads index metadata + +2. Identifies committed indexes + +3. Executes `btr_validate_index()` on each index + +4. Traverses B-tree pages and validates structural relationships + +5. Reports detected inconsistencies + +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) + +* Transportable tablespace export with [`--export`](xtrabackup-option-reference.md#export) + +### Detected corruption conditions + +The validation process performs the following structural checks: + +| Check | Detected condition | +|------|---------------------| +| Broken sibling links | Invalid sibling-page or parent-page navigation pointers | +| `PAGE_INDEX_ID` mismatches | Page index ID does not match index metadata | +| Minimum-record flag validation | Minimum-record flag is missing or invalid | +| Parent-child pointer validation | Child page boundaries do not match parent node structure | +| External LOB validation | Shared, freed, or out-of-bounds LOB page references | +| All-zero page detection | Page contains only zero bytes | +| PRIMARY and secondary index record-count validation | Record count mismatch between the PRIMARY index and secondary indexes | + +### Offloading `CHECK TABLE` + +Similar to the InnoDB `CHECK TABLE` command, the `--check-tables` option validates InnoDB tables. However, Percona XtraBackup performs this validation offline on backup files during the `--prepare` phase, avoiding any performance impact on a live production server. + +Validation during `--prepare` moves structural integrity verification from restored database instances to the backup preparation workflow. A backup or staging host can run validation without starting MySQL on the restored backup. + +Using `--check-tables` during `--prepare` provides the following operational benefits: + +* Eliminates the need to start a MySQL server on restored backups solely for structural validation + +* Moves validation workload away from running production systems + +* Detects structural corruption earlier in the backup validation workflow + +* Detects corruption before restore or deployment + +### Parallel execution + +The `--check-tables` option uses the existing `--parallel` infrastructure from Percona XtraBackup. Worker threads process tablespaces independently. + +Each worker thread: + +1. Retrieves a tablespace from the shared queue + +2. Loads metadata for the tablespace + +3. Validates committed indexes + +4. Reports validation results + +### Limitations + +The `--check-tables` option has the following limitations: + +* Validation applies only to InnoDB tables and does not validate MyISAM or RocksDB tables + +* Validation runs only during `--prepare` + +* Validation increases CPU and I/O usage on the backup host + +* Runtime depends on the number of tablespaces and indexes + +* For incremental backups, use `--check-tables` only during the final prepare stage because the option verifies all tables and indexes each time it runs + +## Usage + +The `--check-tables` option uses the thread count specified by `--parallel`. Start with `--parallel=8` and adjust the value according to CPU availability and disk I/O capacity on the backup host. + +### Validate a full backup + +```bash +xtrabackup --prepare --check-tables \ + --target-dir=/backups/full \ + --parallel=8 +``` + +### 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. + +```bash +xtrabackup --prepare --check-tables \ + --target-dir=/backups/full \ + --parallel=8 +``` + +### Validate and export tablespaces + +```bash +xtrabackup --prepare --export --check-tables \ + --target-dir=/backups/full \ + --parallel=8 +``` + +## Output + +A successful validation operation typically ends with a message similar to: + +```text +2026-05-15T15:41:57.808327+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/replication_group_member_actions +2026-05-15T15:41:57.808630+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/replication_group_configuration_version +2026-05-15T15:41:57.808810+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/server_cost +2026-05-15T15:41:57.808998+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/engine_cost +2026-05-15T15:41:57.809190+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/proxies_priv +2026-05-15T15:41:57.809511+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/ndb_binlog_index +2026-05-15T15:41:58.051499+01:00 0 [Note] [MY-011825] [Xtrabackup] All table checks passed. +``` + +A failed validation operation returns a non-zero exit code. During validation, XtraBackup logs each table as it processes it: + +```text +2026-05-15T13:42:23.691691+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: test/t1 +2026-05-15T13:42:23.697349+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: test/t_lob +2026-05-15T13:42:23.782555+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/dd_properties +2026-05-15T13:42:23.782835+01:00 2 [Note] [MY-011825] [Xtrabackup] Checking: mysql/innodb_dynamic_metadata +... +``` + +If validation detects corruption, XtraBackup reports the affected tables and ends with the following summary message: + +```text +2026-05-15T13:42:24.670469+01:00 0 [ERROR] [MY-011825] [Xtrabackup] Table check failed. The backup may be corrupted. +``` + +The log contains detailed information for each detected inconsistency. + +### Corruption examples + +1. Sibling page relationships corruption. + + ??? example "Expected output" + + ```{.text .no-copy} + 2026-05-15T13:42:20.270268+01:00 2 [ERROR] [MY-013051] [InnoDB] + In pages [page id: space=2, page number=5] + and [page id: space=2, page number=6] + of index PRIMARY of table test.t1 + + InnoDB: broken FIL_PAGE_NEXT or FIL_PAGE_PREV links + ``` + +2. Parent-to-child page references corruption. + + ??? example "Expected output" + + ```{.text .no-copy} + 2026-05-15T13:38:12.343921+01:00 2 [ERROR] [MY-011825] [InnoDB] + B-tree corruption: page 0 is empty but is not the root page + in index PRIMARY. Possible all-zero (unflushed) page. + ``` + +3. Page ownership metadata corruption. + + ??? example "Expected output" + + ```{.text .no-copy} + 2026-05-15T13:38:12.343894+01:00 2 [ERROR] [MY-011866] [InnoDB] + Page index id 0 != data dictionary index id 204 + ``` + +4. Minimum-record markers corruption. + + ??? example "Expected output" + + ```{.text .no-copy} + 2026-05-15T13:42:27.237530+01:00 2 [ERROR] [MY-014011] [InnoDB] + Minimum record flag is wrongly set to rec on page '4' + at level '0' for index 'PRIMARY' of table 'sys/sys_config'. + ``` + +5. External LOB page ownership corruption. + + ??? example "Expected output" + + ```{.text .no-copy} + 2026-05-15T13:42:34.475996+01:00 2 [ERROR] [MY-011825] [InnoDB] Invalid record! External LOB first page cannot be shared between two records + 2026-05-15T13:42:34.476009+01:00 2 [ERROR] [MY-011825] [InnoDB] The external LOB first page is [page id: space=4294967294, page number=1002] + 2026-05-15T13:42:34.476014+01:00 2 [ERROR] [MY-011825] [InnoDB] The first occurrence of the external LOB first page is in record : page_no: 992 with heap_no: 4 + ``` diff --git a/docs/release-notes/8.4.0-1.md b/docs/release-notes/8.4.0-1.md index b4556890..31f75b38 100644 --- a/docs/release-notes/8.4.0-1.md +++ b/docs/release-notes/8.4.0-1.md @@ -8,7 +8,7 @@ Percona XtraBackup 8.4.0-1 is based on MySQL 8.4 Long Term Supported (LTS) Relea Use the [Percona XtraBackup 8.0 series] to take backups of [Percona Server for MySQL 8.0.x] and MySQL 8.0.x series. -Use the Percona XtraBackup Innovation series, the latest version is [8.3.0-1], to take backups of Percona Server for MySQL Innovation series and MySQL Innovation series. +Use the Percona XtraBackup Innovation series, the latest version is 8.3.0-1, to take backups of Percona Server for MySQL Innovation series and MySQL Innovation series. ## Improvements @@ -38,8 +38,7 @@ Download product binaries, packages, and tarballs at [Percona Product Downloads] [Percona XtraBackup 8.0 series]: https://docs.percona.com/percona-xtrabackup/8.0/ [Percona Server for MySQL 8.0.x]: https://docs.percona.com/percona-server/8.0/ -[8.3.0-1]: https://docs.percona.com/percona-xtrabackup/innovation-release/ [Quickstart Guide for Percona XtraBackup]: ..//quickstart-overview.md -[keyring_vault]: https://docs.percona.com/percona-server/innovation-release/use-keyring-vault-component.html -[Keyring file component]: https://docs.percona.com/percona-server/innovation-release/use-keyring-file.html?h=#use-the-keyring-file-component -[Keyring file plugin]: https://docs.percona.com/percona-server/innovation-release/use-keyring-file.html?h=#use-the-keyring-file-plugin \ No newline at end of file +[keyring_vault]: https://docs.percona.com/percona-server/8.4/use-keyring-vault-component.html +[Keyring file component]: https://docs.percona.com/percona-server/8.4/use-keyring-file.html?h=#use-the-keyring-file-component +[Keyring file plugin]: https://docs.percona.com/percona-server/8.4/use-keyring-file.html?h=#use-the-keyring-file-plugin \ No newline at end of file diff --git a/docs/release-notes/8.4.0-2.md b/docs/release-notes/8.4.0-2.md index f52f1a82..458d3ef5 100644 --- a/docs/release-notes/8.4.0-2.md +++ b/docs/release-notes/8.4.0-2.md @@ -6,7 +6,7 @@ Get started with [Quickstart Guide for Percona XtraBackup]. Percona XtraBackup 8.4.0-2 merges the MySQL 8.4 code base and introduces Percona XtraBackup 8.4.0-2 Pro build, in addition to the regular community builds. -Percona XtraBackup 8.4.0-2 Pro build includes the [capabilities](../pxb-pro.md#capabilities) that are typically requested by large enterprises. These Pro builds are specifically created and tested by Percona, and the corresponding packages are supported only for Percona customers with a valid subscription. +Percona XtraBackup 8.4.0-2 Pro build includes the capabilities that are typically requested by large enterprises. These Pro builds are specifically created and tested by Percona, and the corresponding packages are supported only for Percona customers with a valid subscription. Percona XtraBackup 8.4.0-2 Pro build is available for the following platforms: diff --git a/docs/release-notes/8.4.0-3.md b/docs/release-notes/8.4.0-3.md index 8eaa7047..01273b4b 100644 --- a/docs/release-notes/8.4.0-3.md +++ b/docs/release-notes/8.4.0-3.md @@ -10,7 +10,7 @@ We recommend that you download the Percona XtraBackup for the same platform as t ## Improvements -[PXB-3427](https://perconadev.atlassian.net/browse/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-3427](https://perconadev.atlassian.net/browse/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](https://perconadev.atlassian.net/browse/PXB-3199): The `xbcloud put` operations were updated to include support for [ObjectLock-enabled AWS S3 buckets](https://docs.aws.amazon.com/AmazonS3/latest/userguide/object-lock.html) (Thanks to volver for contributing the fix for this issue.) diff --git a/docs/xtrabackup-binary-overview.md b/docs/xtrabackup-binary-overview.md index 23f50f44..0d563ca5 100644 --- a/docs/xtrabackup-binary-overview.md +++ b/docs/xtrabackup-binary-overview.md @@ -74,6 +74,6 @@ Explore the following sections for more guidance: * Configuration options appear on [configure xtrabackup](configure-xtrabackup.md) -* Command-line options: A comprehensive list of command-line options is available on [xtrabackup option reference](xtrabackup-option-reference.html) +* Command-line options: A comprehensive list of command-line options is available on [xtrabackup option reference](xtrabackup-option-reference.md) * Implementation details: Review technical insights and architecture on [xtrabackup implementation details](xtrabackup-implementation-details.md) diff --git a/docs/xtrabackup-option-reference.md b/docs/xtrabackup-option-reference.md index 22cd1466..b28cf40d 100644 --- a/docs/xtrabackup-option-reference.md +++ b/docs/xtrabackup-option-reference.md @@ -110,6 +110,22 @@ If a privilege is not needed for the current operation but is missing and may be xtrabackup: Warning: missing required privilege REPLICATION CLIENT on *.* ``` +### check-tables + +Usage: `--check-tables` + +Introduced in Percona XtraBackup 8.4.0-6. + +Enables InnoDB B-tree structural validation during the `--prepare` phase after redo log application completes. + +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`. + +If validation detects corruption, xtrabackup reports the affected tables and returns a non-zero exit code after completing all checks. + +For more information, see [InnoDB B-tree integrity validation during prepare](innodb-btree-check.md). + ### close-files Usage: `--close-files` diff --git a/docs/yum-repo.md b/docs/yum-repo.md index 6f3b8f2b..193ab356 100644 --- a/docs/yum-repo.md +++ b/docs/yum-repo.md @@ -3,9 +3,7 @@ Ready-to-use packages are available from the Percona XtraBackup software repositories and the [Percona Software Downloads :octicons-link-external-16:](https://www.percona.com/downloads). The Percona yum repository supports popular `RPM`-based operating systems, including the `Amazon Linux AMI`. -The easiest way to install the Percona Yum repository is to install an `RPM` that configures yum and installs the [Percona GPG key :octicons-link-external-16:](https://www.percona.com/downloads/RPM-GPG-KEY-percona). - -Specific information on the supported platforms, products, and versions is described in [Percona Software and Platform Lifecycle :octicons-link-external-16:](https://www.percona.com/services/policies/percona-software-platform-lifecycle#mysql). +Specific information on the supported platforms, products, and versions is described in [Percona Software and Platform Lifecycle :octicons-link-external-16:](https://www.percona.com/release-lifecycle-overview/#mysql).