PBM-1715 Parallel file processing for backups and restores

.cache/plugin/git-committers/page-authors.json

@@ -0,0 +1 @@
+{"cache_date": "2026-06-11", "page_authors": {"docs/index.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/404.md": {"last_commit_date": "2023-12-08", "authors": []}, "docs/CODE_OF_CONDUCT.md": {"last_commit_date": "2026-02-09", "authors": []}, "docs/about-docs.md": {"last_commit_date": "2025-02-19", "authors": []}, "docs/copyright.md": {"last_commit_date": "2024-12-09", "authors": []}, "docs/get-help.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/installation.md": {"last_commit_date": "2024-08-07", "authors": []}, "docs/intro.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/pmm.md": {"last_commit_date": "2025-02-12", "authors": []}, "docs/release-notes.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/system-requirements.md": {"last_commit_date": "2025-01-23", "authors": []}, "docs/trademark-policy.md": {"last_commit_date": "2023-12-08", "authors": []}, "docs/details/architecture.md": {"last_commit_date": "2024-09-10", "authors": []}, "docs/details/authentication.md": {"last_commit_date": "2026-03-05", "authors": []}, "docs/details/azure.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/details/cli.md": {"last_commit_date": "2024-03-04", "authors": []}, "docs/details/control-collections.md": {"last_commit_date": "2024-05-16", "authors": []}, "docs/details/deployments.md": {"last_commit_date": "2024-05-16", "authors": []}, "docs/details/endpoint-map.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/details/filesystem-storage.md": {"last_commit_date": "2025-07-16", "authors": []}, "docs/details/gcs.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/details/minio.md": {"last_commit_date": "2026-03-16", "authors": []}, "docs/details/oss.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/details/pbm-agent.md": {"last_commit_date": "2024-09-10", "authors": []}, "docs/details/s3-storage.md": {"last_commit_date": "2026-04-08", "authors": []}, "docs/details/storage-configuration.md": {"last_commit_date": "2026-03-16", "authors": []}, "docs/details/versions.md": {"last_commit_date": "2025-12-03", "authors": []}, "docs/details/workload-identity-auth.md": {"last_commit_date": "2026-02-24", "authors": []}, "docs/features/backup-sharding.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/features/backup-types.md": {"last_commit_date": "2024-11-19", "authors": []}, "docs/features/comparison.md": {"last_commit_date": "2025-05-23", "authors": []}, "docs/features/incremental-backup.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/features/known-limitations.md": {"last_commit_date": "2026-04-29", "authors": []}, "docs/features/logical.md": {"last_commit_date": "2024-09-02", "authors": []}, "docs/features/multi-storage.md": {"last_commit_date": "2026-04-29", "authors": []}, "docs/features/physical.md": {"last_commit_date": "2026-04-29", "authors": []}, "docs/features/point-in-time-recovery.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/features/restore-new-env.md": {"last_commit_date": "2025-09-23", "authors": []}, "docs/features/restore-remapping.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/features/selective-backup.md": {"last_commit_date": "2026-02-24", "authors": []}, "docs/features/snapshots.md": {"last_commit_date": "2026-03-26", "authors": []}, "docs/features/split-merge-backup.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/install/backup-storage.md": {"last_commit_date": "2026-03-26", "authors": []}, "docs/install/configure-authentication.md": {"last_commit_date": "2026-06-10", "authors": []}, "docs/install/docker.md": {"last_commit_date": "2026-06-10", "authors": []}, "docs/install/initial-setup.md": {"last_commit_date": "2024-09-10", "authors": []}, "docs/install/repos.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/install/secure-credentials-systemd.md": {"last_commit_date": "2026-04-01", "authors": []}, "docs/install/source.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/install/start-pbm-agent.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/install/tarball.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/manage/automate-s3-access.md": {"last_commit_date": "2025-11-13", "authors": []}, "docs/manage/change-nodes.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/manage/configure-remotely.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/manage/logpath.md": {"last_commit_date": "2025-12-24", "authors": []}, "docs/manage/overview.md": {"last_commit_date": "2023-12-08", "authors": []}, "docs/manage/start-agent-with-config.md": {"last_commit_date": "2025-12-24", "authors": []}, "docs/manage/uninstalling.md": {"last_commit_date": "2023-03-29", "authors": []}, "docs/manage/upgrading.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/reference/backup-options.md": {"last_commit_date": "2026-06-11", "authors": []}, "docs/reference/config.md": {"last_commit_date": "2026-04-17", "authors": []}, "docs/reference/configuration-options.md": {"last_commit_date": "2026-04-08", "authors": []}, "docs/reference/glossary.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/reference/logging-options.md": {"last_commit_date": "2025-02-19", "authors": []}, "docs/reference/pbm-agent-config-options.md": {"last_commit_date": "2025-12-24", "authors": []}, "docs/reference/pbm-commands.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/reference/pitr-options.md": {"last_commit_date": "2025-12-01", "authors": []}, "docs/reference/restore-options.md": {"last_commit_date": "2026-06-11", "authors": []}, "docs/release-notes/0.5.0.md": {"last_commit_date": "2023-01-19", "authors": []}, "docs/release-notes/1.0.0.md": {"last_commit_date": "2024-12-06", "authors": []}, "docs/release-notes/1.1.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.1.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.1.3.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.2.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.2.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.3.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.3.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.3.2.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.3.3.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.3.4.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.4.0.md": {"last_commit_date": "2023-05-09", "authors": []}, "docs/release-notes/1.4.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.5.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.6.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.6.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.7.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.8.0.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/1.8.1.md": {"last_commit_date": "2022-08-18", "authors": []}, "docs/release-notes/2.0.0.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/release-notes/2.0.1.md": {"last_commit_date": "2025-05-23", "authors": []}, "docs/release-notes/2.0.2.md": {"last_commit_date": "2022-10-27", "authors": []}, "docs/release-notes/2.0.3.md": {"last_commit_date": "2023-03-29", "authors": []}, "docs/release-notes/2.0.4.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/release-notes/2.0.5.md": {"last_commit_date": "2023-03-29", "authors": []}, "docs/release-notes/2.1.0.md": {"last_commit_date": "2025-03-12", "authors": []}, "docs/release-notes/2.10.0.md": {"last_commit_date": "2025-07-02", "authors": []}, "docs/release-notes/2.11.0.md": {"last_commit_date": "2025-09-25", "authors": []}, "docs/release-notes/2.12.0.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/release-notes/2.13.0.md": {"last_commit_date": "2026-03-02", "authors": []}, "docs/release-notes/2.14.0.md": {"last_commit_date": "2026-04-29", "authors": []}, "docs/release-notes/2.2.0.md": {"last_commit_date": "2025-02-20", "authors": []}, "docs/release-notes/2.2.1.md": {"last_commit_date": "2023-07-27", "authors": []}, "docs/release-notes/2.3.0.md": {"last_commit_date": "2023-09-25", "authors": []}, "docs/release-notes/2.3.1.md": {"last_commit_date": "2023-12-08", "authors": []}, "docs/release-notes/2.4.0.md": {"last_commit_date": "2024-03-21", "authors": []}, "docs/release-notes/2.4.1.md": {"last_commit_date": "2024-03-26", "authors": []}, "docs/release-notes/2.5.0.md": {"last_commit_date": "2024-05-16", "authors": []}, "docs/release-notes/2.6.0.md": {"last_commit_date": "2025-04-09", "authors": []}, "docs/release-notes/2.7.0.md": {"last_commit_date": "2024-10-09", "authors": []}, "docs/release-notes/2.8.0.md": {"last_commit_date": "2025-06-26", "authors": []}, "docs/release-notes/2.9.0.md": {"last_commit_date": "2025-02-19", "authors": []}, "docs/release-notes/2.9.1.md": {"last_commit_date": "2025-03-27", "authors": []}, "docs/troubleshoot/index.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/troubleshoot/faq.md": {"last_commit_date": "2026-01-02", "authors": []}, "docs/troubleshoot/pbm-pmm.md": {"last_commit_date": "2026-06-10", "authors": []}, "docs/troubleshoot/pbm-report.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/troubleshoot/restore-partial.md": {"last_commit_date": "2025-06-26", "authors": []}, "docs/troubleshoot/status.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/troubleshoot/troubleshooting.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/backup-external.md": {"last_commit_date": "2026-04-16", "authors": []}, "docs/usage/backup-incremental.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/backup-physical.md": {"last_commit_date": "2026-06-11", "authors": []}, "docs/usage/backup-priority.md": {"last_commit_date": "2025-08-19", "authors": []}, "docs/usage/backup-selective.md": {"last_commit_date": "2026-02-24", "authors": []}, "docs/usage/cancel-backup.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/compression.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/delete-backup.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/describe-backup.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/list-backup.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/logs.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/oplog-replay.md": {"last_commit_date": "2025-12-04", "authors": []}, "docs/usage/pitr-physical.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/pitr-selective.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/pitr-tutorial.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/restore-external-agent-restart.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/restore-external.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/restore-incremental.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/restore-physical.md": {"last_commit_date": "2026-06-11", "authors": []}, "docs/usage/restore-progress.md": {"last_commit_date": "2025-11-04", "authors": []}, "docs/usage/restore-selective.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/restore.md": {"last_commit_date": "2026-04-28", "authors": []}, "docs/usage/schedule-backup.md": {"last_commit_date": "2025-12-29", "authors": []}, "docs/usage/start-backup.md": {"last_commit_date": "2025-11-04", "authors": []}}}

docs/reference/backup-options.md

@@ -13,6 +13,7 @@ backup:
     startingStatus: 60
   oplogSpanMin: <float64>
   numParallelCollections: <int>
+  numParallelFiles: <int>
 ```
 
 ## priority
@@ -121,3 +122,14 @@ The duration (in minutes) of oplog slices saved with the logical backup snapshot
 The number of parallel collections to process during a logical backup. By default, the number of parallel collections is half of the number of CPU cores. By setting the value for this option you define the new default.
 Available starting with version 2.7.0.
 
+
+## backup.numParallelFiles
+
+*Type*: int <br>
+*Default*: 1 <br>
+*Storage*: Filesystem / NFS only <br>
+*Backup type:* Physical only
+
+The number of files to copy in parallel during a physical backup to filesystem or NFS storage.
+
+The default value is `1`, which copies files sequentially.

docs/reference/restore-options.md

@@ -6,6 +6,7 @@ restore:
   numInsertionWorkers: <int>
   numParallelCollections: <int>
   numDownloadWorkers: <int>
+  numParallelFiles: <int>
   maxDownloadBufferMb: <int>
   downloadChunkMb: <int>
   mongodLocation: <string>
@@ -99,4 +100,16 @@ This is useful when you want to:
 
 - Prevent restore operations from waiting indefinitely
 - Enforce time limits in automated workflows
-- Fail fast if the balancer cannot be stopped
+- Fail fast if the balancer cannot be stopped
+
+
+### restore.numParallelFiles
+
+*Type*: int <br>
+*Default*: 1 <br>
+*Storage*: Filesystem / NFS only <br>
+*Restore type:* Physical only
+
+The number of files to copy in parallel during a physical restore from filesystem or NFS storage.
+
+The default value is `1`, which copies files sequentially.

docs/usage/backup-physical.md

@@ -18,6 +18,26 @@ pbm backup --type=physical
 
 Starting with [2.4.0](../release-notes/2.4.0.md), PBM doesn't stop [point-in-time recovery oplog slicing](../features/point-in-time-recovery.md#oplog-slicing), if it's enabled, but runs it in parallel. This ensures [point-in-time recovery](pitr-tutorial.md) to any timestamp if it takes too long (e.g. hours) to make a backup snapshot.
 
+## Parallel file copy for filesystem or NFS storage
+
+For physical backups stored on a filesystem or NFS mount, you can control how many files PBM processes in parallel during the backup operation. Increasing parallelism can improve performance by allowing multiple files to be copied simultaneously.
+
+To copy files in parallel, set `backup.numParallelFiles` in the PBM configuration:
+
+```yaml
+backup:
+  numParallelFiles: 4
+```
+
+Or pass `--num-parallel-files`:
+
+```sh
+pbm backup --type=physical --num-parallel-files=4
+```
+
+!!! note
+    Parallel file copy applies to **physical backups to filesystem or NFS storage only**. It has no effect on logical backups or on S3-compatible storage.
+
 ## Next steps
 
 [List backups](../usage/list-backup.md){.md-button}

docs/usage/restore-physical.md

@@ -151,6 +151,25 @@ restore:
 * `maxDownloadBufferMb` - the maximum size of memory buffer to store the downloaded data chunks for decompression and ordering. It is calculated as `numDownloadWorkers * downloadChunkMb * 16`
 * `downloadChunkMb` is the size of the data chunk to download (by default, 32 MB)
 
+### Parallel file copy for filesystem or NFS storage
+
+By default, PBM copies backup files sequentially during a physical restore from filesystem or NFS storage. On fast NFS mounts, this limits restore throughput regardless of available network bandwidth.
+
+To copy files in parallel, set `restore.numParallelFiles` in the PBM configuration:
+
+```yaml
+restore:
+  numParallelFiles: 4
+```
+
+Or pass `--num-parallel-files`:
+
+```sh
+pbm restore <backup_name> --num-parallel-files=4
+```
+
+!!! note
+    Parallel file copy applies to **physical restores from filesystem or NFS storage only**. It has no effect on logical restores or on S3-compatible storage.
 
 ## Next steps