PXB-3254 Document reduction in locks

	modified:   docs/lock-options.md
	new file:   docs/reduction-in-locks.md
	modified:   docs/xtrabackup-option-reference.md
	modified:   mkdocs-base.yml

docs/lock-options.md

@@ -1,5 +1,9 @@
 # lock-ddl-per-table option improvements
 
+!!! important
+
+    The lock-ddl-per-table option is deprecated in Percona Server for MySQL 8.0. Use --lock-ddl instead of this variable.
+
 To block DDL statements on an instance, Percona Server implemented LOCK
 TABLES FOR BACKUP. Percona XtraBackup uses this lock for the
 duration of the backup. This lock does not affect DML statements.
@@ -60,4 +64,3 @@ The following improvements have been added:
 
 * A `SELECT` query that acquires an MDL does not retrieve any data.
 
-

docs/reduction-in-locks.md

@@ -0,0 +1,98 @@
+# Reduced backup lock time
+
+!!! important
+
+    The `--lock-ddl=REDUCED` option is a [tech preview](./glossary.md#tech-preview). Before using this option in production, we recommend that you test restoring production from physical backups in your environment, and also use the alternative backup method for redundancy.
+
+Percona Server for MySQL implemented `LOCK TABLES FOR BACKUP` to block Data Definition Language (DDL) statements on a server. Percona XtraBackup utilizes this lock during the backup process to ensure that any `DDL` event does not corrupt the backup. The lock does not affect the Data Manipulation Language (DML) statements.
+
+## How the backup lock works
+
+With the [`--lock-ddl=ON`](./xtrabackup-option-reference.md/#lock-ddl) option the backup lock is enabled by default from the start of the backup process.
+
+* Set a backup lock: Set a backup lock on the server to prevent any `DDL` operations, ensuring no new tables are created, renamed, or dropped during the backup.
+
+* Copy the redo logs: Transfer all redo logs from the checkpoint up to the current Log Sequence Number (LSN) and start tracking new entries.
+
+* Identify and copy all InnoDB tablespace, `.ibd`, files. This step takes most of the time and is performed under the lock.
+
+* Copy non-InnoDB files.
+
+* Gather sync point: Collect synchronization points from all engines (InnoDB LSN, binlog, Global Transaction Identifier (GTID), etc.) by querying the log status.
+
+* Stop the redo follow thread: Cease the redo fllow thread once it has copied up to the sync point.
+
+* Release the backup lock on the server.
+
+If the backup lock is disabled with the [`--lock-ddl=OFF`](./xtrabackup-option-reference.md/#lock-ddl) option, a backup continues while concurrent DDL events are executed. These backups may be invalid and may fail at either the `backup` or the `--prepare` step.
+
+## The `--lock-ddl=REDUCED` option overview
+
+[Percona XtraBackup 8.4.0-2](./release-notes/8.4.0-2.md) adds the [`--lock-ddl=REDUCED`](./xtrabackup-option-reference.md/#lock-ddl) option to reduce the time the server remains locked by `xtrabackup`. Now, you can execute more `DDL` operations concurrently while the backup is in progress. The backup lock is now taken after copying the `.ibd` files and before copying the `non-InnoDB` files.
+
+The new backup design includes the following phases:
+
+### Phase 1: `Operations performed without the lock`
+
+1. Copy all redo logs from checkpoint up to the current `LSN` and start tracking new entries.
+2. Start the redo log thread.
+3. Track file operations from the redo log by parsing the `MLOG_FILE_*` records.
+4. Copy of all the `.ibd` files.
+
+### Phase 2: `Operations performed under the lock`
+
+1. Acquire the backup lock (Lock Tables For Backup (LTFB)/Lock Instance For Backup (LIFB)) to prevent new DDL operations, such as creating or altering tables.
+2. Check the file operations that were tracked and recopy the tablespaces.
+3. Create additional `meta` files to perform the required actions (deletions or renames) on the already copied files. This approach ensures that the backup remains consistent and accurate without disrupting the streaming process. This step is required for taking streaming backups.
+
+    The meta files are the following:
+
+    | File         | Description                                                                                                      |
+    |--------------|------------------------------------------------------------------------------------------------------------------|
+    | `.new`       | For files that need to be recopied due to encryption or `ADD INDEX` operations.                                  |
+    | `.del`       | For deleted files. If a file has been copied, create a `space_id.del` file.                                      |
+    | `.ren`       | For renamed files after copying. Create a `space_id.ren` file.                                                   |
+    | `.crpt`      | For files that cannot be fully copied due to encryption changes. These will be recopied, and a `.crpt` file will be created for the existing file. |
+    | `.new.meta`  | Similar to `.new`, but for incremental backups.                                                                  |
+    | `.new.delta` | Similar to `.new`, but for incremental backups. Create `t1.ibd.meta` and `t1.ibd.delta` instead of `t1.ibd`.      |
+
+4. Gather a sync point from all engines (InnoDB LSN, binlog, GTID, etc.) by querying the `log_status`.
+5. Stop the redo follow thread once it copies at least up to sync point at step 4.
+6. Release the backup lock (LTFB/LIFB).
+
+### Phase 3. Processing the new metadata files during `--prepare` phase before crash recovery starts.
+
+1. The `.crpt` files are removed matching the name after stripping the extension. This step is crucial before the IBD scan because these files are incomplete (they could even be zero size).
+2. Perform a scan to create a mapping of `space_id` to file names.
+3. The `space_id.del` deletes the file matching the `space_id`. In case of incremental backups, also deletes the corresponding `.new.meta` and `.new.delta` files.
+4. The `space_id.ren` renames the file matching the `space_id` to the name specified in the file.
+5. The `.new` extension replaces the file that matches the name without the `.new` extension.
+6. The `.new.meta/.delta` replace the meta and delta files that match the name without the `.new` in the name.
+
+After the Phase 3 is completed, the regular crash recovery starts.
+
+### Limitations
+
+1. The `ALTER INSTANCE ROTATE MASTER KEY` command should not be executed during [Phase 1](#phase-1-operations-performed-without-the-lock) if there are encrypted tables, as it will cause the backup to fail.
+
+2. The number of open file handles in your Operation System (OS) should be configured to match the number of files in the server data directory.
+
+3. When using the `--lock-ddl=REDUCED` option, backups may be larger in size because new `DDL` operations are executed concurrently on the server, and the files they generate are included in the backup. Additionally, certain DDL operations, such as `ADD INDEX` or encryption changes to existing data files, will cause these data files to be recopied, further increasing the backup size.
+
+### Benefits
+
+The `--lock-ddl=REDUCED` option key features are as follows:
+
+* Reduced locking: Rather than holding the backup lock throughout the entire backup process, it is only acquired for a very short period of time.
+
+* DDL statements: The server remains accessible for `DDL` operations during the backup process.
+
+* Consistency: Consistency is maintained by using the redo log to track file operations. During the backup process new metadata files are created to ensure consistency. In the `--prepare` phase, these metadata files are processed first to bring the database to a consistent state.
+
+
+
+
+
+
+
+

docs/xtrabackup-option-reference.md

@@ -27,7 +27,6 @@ $ xtrabackup --prepare --target-dir=/data/backup/mysql/
 For all modes, the default options are read from the xtrabackup and
 mysqld configuration groups from the following files in the given order:
 
-
 1. `/etc/my.cnf`
 
 
@@ -598,18 +597,24 @@ Usage: `--lock-ddl`
 
 Enabled by default to ensure that any DDL event does not corrupt the backup. Any DML events continue to occur. A DDL lock protects table and view definitions.
 
-If the option is disabled, a backup continues while concurrent DDL events are executed. These backups are invalid and fail in the Prepare step.
+The available values are the following:
+
+|Option| Description|
+|`--lock-ddl=ON`| The backup lock is enabled and is taken at the beginning of the backup.|
+|`--lock-ddl=OFF`|The backup lock is not taken.|
+|`--lock-ddl=REDUCED`|This option value is a [tech preview](./glossary.md#tech-preview). The option value has been added in [Percona XtraBackup 8.4.0-2](./release-notes/8.4.0-2.md) to reduce the time the instance remains under backup lock. The backup lock is taken after copying the `.ibd` files and before copying the `non-InnoDB` files.|
+
+If the backup lock is disabled with the `--lock-ddl=OFF` option, a backup continues while concurrent DDL events are executed. These backups may be invalid and may fail at either the `backup` or the `--prepare` step.
 
 Use a [safe-slave-backup](#safe-slave-backup) option to stop a SQL replica thread before copying the InnoDB files.
 
 ### lock-ddl-per-table
 
 Usage: `--lock-ddl-per-table`
 
-Deprecated. Use the [`–lock-ddl`](#lock-ddl) option instead
+Deprecated in Percona XtraBackup 8.0. Use the [`–lock-ddl`](#lock-ddl) option instead
 <!--26-1-24-->
-Lock DDL for each table before xtrabackup starts to copy
-it and until the backup is completed.
+Lock DDL for each table before xtrabackup starts to copy it and until the backup is completed.
 
 ### lock-ddl-timeout
 

mkdocs-base.yml

@@ -159,14 +159,14 @@ nav:
         - lru-dump-backup.md
         - throttling-backups.md
         - store-backup-history.md
+        - reduction-in-locks.md
       - Prepare features:
         - dictionary-cache.md
       - Restore features:
         - point-in-time-recovery.md
         - restore-individual-tables.md
       - flush-tables-with-read-lock.md
       - log-enhancements.md
-      - lock-options.md
       - smart-memory-estimation.md
       - working-with-binary-logs.md
   - Binaries: