PBM Restore vs mongorestore Restore Options (drop, preserveUUID, bypassDocumentValidation)

MongoDB Percona Backup for MongoDB
1

Hi Percona Team,

We are currently evaluating Percona Backup for MongoDB (PBM) as a replacement for our existing MongoDB backup/restore solution.

Environment

  • MongoDB Community Edition 8.2.1
  • MongoDB Community Kubernetes Operator
  • PBM 2.14.0
  • S3-compatible object storage
  • Logical backups with PITR enabled

Previously, we used mongodump/mongorestore with the following restore command:

mongorestore \
  --uri="${MONGODB_URI}" \
  --authenticationDatabase=admin \
  --gzip \
  --archive="${BACKUP_FILE}" \
  --oplogReplay \
  --drop \
  --bypassDocumentValidation \
  --preserveUUID \
  --username="${MONGODB_USERNAME}" \
  --password="${MONGODB_PASSWORD}"

This gave us explicit control over important restore behaviours such as:

  • --drop
  • --preserveUUID
  • --bypassDocumentValidation
  • --oplogReplay

After migrating to PBM, restore is simply executed as:

pbm restore <backup-name>

Question

Does PBM internally perform the equivalent of the following mongorestore options?

  • --drop
  • --preserveUUID
  • --bypassDocumentValidation
  • --oplogReplay

If not:

  1. What is the recommended PBM approach for environments that previously relied on these options?
  2. How does PBM handle collection UUID preservation during restore, especially when replaying oplog/PITR entries?
  3. Is there any supported mechanism to bypass document validation during PBM restore when schema validators have changed since the backup was taken?
  4. Is PBM intentionally designed to avoid exposing these low-level restore options, or is there an alternative workflow?

Background

During our testing we encountered situations such as:

Namespace '<database>.<collection>' and UUID '<uuid>' point to different collections

and also environments where schema validation could potentially reject restored documents.

With mongorestore, these situations could often be handled using:

  • --drop
  • --preserveUUID
  • --bypassDocumentValidation

We are trying to understand how these scenarios are expected to be handled when using PBM as the primary backup and restore solution.

We would appreciate any clarification on how PBM internally handles these restore scenarios,
whether there are design considerations behind not exposing these options directly.
And what the recommended best practices are for organizations migrating from a traditional mongodump/mongorestore workflow.

Thank you!

2

Hi @svas

First of all - welcome to our Percona Community Forum! Congrats on your first question post :wink: . Hope to see you more often!

Before I answer your question - an important note - PBM doesn’t support yet MongoDB 8.2 or 8.3. We’ve already found some issues with these versions that we’re fixing. I hope that the next PBM release will solve them all :slight_smile:

PBM is designed as a cluster-consistent backup solution, not a wrapper around mongorestore. It manages coordination across all replica set members and shards, which requires deterministic behavior. Exposing Drop, PreserveUUID, or BypassDocumentValidation as user-configurable flags would risk data inconsistency across nodes — for example, if one shard dropped collections and another didn’t, the cluster state would become corrupted. The opinionated defaults (Drop: true, BypassDocumentValidation: true, PreserveUUID: true) represent the only safe, consistent restore path for a distributed MongoDB deployment.

And now - to questions:

You can see how we run mongorestore here: percona-backup-mongodb/pbm/snapshot/restore.go at main · percona/percona-backup-mongodb · GitHub

Especially take a look at this part:

mopts.OutputOptions = &mongorestore.OutputOptions{
    BulkBufferSize:           batchSize,
    BypassDocumentValidation: true,       
    Drop:                     true,       
    NumInsertionWorkers:      numInsertionWorkersPerCol,
    NumParallelCollections:   numParallelColls,
    PreserveUUID:             preserveUUID, 
    StopOnError:              true,
    WriteConcern:             "majority",
    NoIndexRestore:           true,
}

Drop is almost always true. One exception: Drop is set to false during namespace cloning operations (when --ns-from/--ns-to mapping is active).

BypassDocumentValidation is also always true in all logical restores.

As for the preserveUUID :
This is conditionally set depending on whether namespace cloning is in use. In a standard restore (no namespace mapping), preserveUUID is true. When namespace cloning is active, it is set to false because collections are created under new names, so the original UUIDs no longer apply.

And finally for oplogReplay :
PBM does not use mongorestore’s built-in --oplogReplay. Instead, it has its own oplog application engine (applyOplog()) that handles both backup-embedded oplog and live PITR oplog chunks. This gives PBM much more precise control — it can replay to a specific MongoDB timestamp tuple (epoch + ordinal), not just “replay whatever is in the dump.”

As for the issue your are running - this might be case with 8.2 incompatibility - we’d need to check. I assume you don’t mess with data during the restore :wink: Can you share some more details about that? Is that a full restore? Or selective? We would appreciate your Steps to Reproduce so we can potentially fix that on our way to support 8.3 version.

For the migration from mongodump/mongorestore → just install PBM agents on all your MongoDB hosts - and you’re good to go!

PS Also explore our Percona Kubernetes Operator for MongoDB - it’s awesome too! And I’m sure it will help you a ton!