Skip to content
logo
Percona Backup for MongoDB
Make a backup
Initializing search
    percona/pbm-docs
    percona/pbm-docs
    • Home
        • Overview
        • Logical backups and restores
        • Physical backups and restores
        • Selective backup and restore
        • Incremental physical backups
        • Point-in-time recovery
      • Comparison with MongoDB
      • How PBM works
        • PBM architecture
        • pbm-agent
        • PBM CLI
        • PBM control collections
          • Overview
          • Remote backup storage configuration examples
      • Authentication
      • Supported MongoDB deployments
      • Supported MongoDB versions
        • Overview
        • Method 1. From repositories
        • Method 2. Build from source
        • Method 3. Download tarballs
        • Method 4. Deploy on Kubernetes
      • Set up and configure
      • Make a backup
        • Before you start
        • Make a backup
          • Compressed backups
        • Backups in sharded clusters
          • Adjust node priority for backups
        • Next steps
        • Useful links
      • Restore a backup
      • Make a point-in-time restore
      • List backups
      • View detailed information about a backup
      • Schedule backups
      • Cancel a backup
      • Delete backups
      • View restore progress
      • Replay oplog from arbitrary start time
      • View backup logs
      • PBM configuration via pipelines
      • Automate access to S3 buckets for PBM
      • Diagnose PBM
      • Check status
      • Upgrade PBM
      • Remove PBM
    • FAQ
      • PBM commands
        • Configuration file
        • Remote backup storage options
        • Point-in-time recovery options
        • Backup options
        • Restore options
      • Glossary
      • Release notes index
      • Percona Backup for MongoDB 2.1.0 (2023-04-18)
      • Percona Backup for MongoDB 2.0.5 (2023-03-23)
      • Percona Backup for MongoDB 2.0.4 (2023-02-21)
      • Percona Backup for MongoDB 2.0.3 (2023-01-11)
      • Percona Backup for MongoDB 2.0.2 (2022-10-27)
      • Percona Backup for MongoDB 2.0.1 (2022-10-12)
      • Percona Backup for MongoDB 2.0.0 (2022-09-21)
      • Percona Backup for MongoDB 1.8.1 (2022-07-12)
      • Percona Backup for MongoDB 1.8.0 (2022-06-09)
      • Percona Backup for MongoDB 1.7.0 (2022-04-18)
      • Percona Backup for MongoDB 1.6.1 (2021-11-04)
      • Percona Backup for MongoDB 1.6.0 (2021-08-16)
      • Percona Backup for MongoDB 1.5.0 (2021-05-10)
      • Percona Backup for MongoDB 1.4.1 (2021-01-28)
      • Percona Backup for MongoDB 1.4.0 (2020-12-24)
      • Percona Backup for MongoDB 1.3.4 (2020-11-19)
      • Percona Backup for MongoDB 1.3.3 (2020-11-04)
      • Percona Backup for MongoDB 1.3.2 (2020-10-14)
      • Percona Backup for MongoDB 1.3.1 (2020-09-03)
      • Percona Backup for MongoDB 1.3.0 (2020-08-26)
      • Percona Backup for MongoDB 1.2.1 (2020-07-27)
      • Percona Backup for MongoDB 1.2.0 (2020-05-13)
      • Percona Backup for MongoDB 1.1.3 (2020-04-14)
      • Percona Backup for MongoDB 1.1.1 (2020-01-31)
      • Percona Backup for MongoDB 1.1.0 (2020-01-16)
      • Percona Backup for MongoDB 1.0.0 (2019-09-19)
      • Percona Backup for MongoDB 0.5.0 (2019-06-17)
    • Contribution guidelines
    • Copyright and licensing
    • Trademark policy

    • Before you start
    • Make a backup
      • Compressed backups
    • Backups in sharded clusters
      • Adjust node priority for backups
    • Next steps
    • Useful links

    Make a backup¶

    Before you start¶

    1. Install and set up Percona Backup for MongoDB
    2. Check that pbm agent is running with the pbm status command

    Make a backup¶

    To make a backup, run the following command:

    $ pbm backup --type=logical
    

    Logical backup is the default one so you can bypass the --type flag.

    During logical backups, Percona Backup for MongoDB copies the actual data to the backup storage.

    Starting with version 2.0.0, Percona Backup for MongoDB stores data in the new multi-file format where each collection has a separate file. The oplog is stored for all namespaces regardless whether this is a full or selective backup.

    Multi-format is now the default data format since it allows selective restore. Note, however, that you can make only full restores from backups made with earlier versions of Percona Backup for MongoDB.

    Version added: 1.7.0

    $ pbm backup --type=physical
    

    During a physical backup, Percona Backup for MongoDB copies the contents of the dbpath directory (data and metadata files, indexes, journal and logs) from every shard and config server replica set to the backup storage.

    Version added: 2.0.0

    Before you start, read about selective backups known limitations

    To make a selective backup, run the pbm backup command and provide the value for the --ns flag in the format <database.collection>. The --ns flag value is case sensitive. For example, to back up the “Payments” collection, run the following command:

    $ pbm backup --ns=staff.Payments
    

    To back up the “Invoices” database and all collections that it includes, run the pbm backup command as follows:

    $ pbm backup --ns=Invoices.*
    

    During the backup process, Percona Backup for MongoDB stores data in the new multi-file format where each collection has a separate file. The oplog is stored for all namespaces regardless whether this is a full or selective backup.

    Multi-format is now the default data format for both full and selective backups since it allows selective restore. Note, however, that you can make only full restores from backups made with earlier versions of Percona Backup for MongoDB.

    Version added: 2.0.3

    Before you start, read more about incremental backup

    To start incremental backups, first make a full incremental backup. It will serve as the base for subsequent incremental backups:

    $ pbm backup --type incremental --base
    

    The pbm-agent starts tracking the incremental backup history to be able to calculate and save the difference in data blocks. After that you can run regular incremental backups:

    $ pbm backup -type incremental
    

    The incremental backup history looks like this:

    Snapshots:
        2022-11-25T14:13:43Z 139.82MB <incremental> [restore_to_time: 2022-11-25T14:13:45Z]
        2022-11-25T14:02:07Z 255.20MB <incremental> [restore_to_time: 2022-11-25T14:02:09Z]
        2022-11-25T14:00:22Z 228.30GB <incremental> [restore_to_time: 2022-11-25T14:00:24Z]
        2022-11-24T14:45:53Z 220.13GB <incremental, base> [restore_to_time: 2022-11-24T14:45:55Z]
    

    Compressed backups¶

    By default, Percona Backup for MongoDB uses the s2 compression method when making a backup.

    You can start a backup with a different compression method by passing the --compression flag to the pbm backup command.

    For example, to start a backup with gzip compression, use the following command:

    $ pbm backup --compression=gzip
    

    Supported compression types are: gzip, snappy, lz4, pgzip, zstd. The none value means no compression is done during backup.

    As of version 1.7.0, you can configure the compression level for backups. Specify the value for the --compression-level flag.

    Default compression levels differ per compression method used.

    The following table shows available compression levels per compression method:

    Compression method Supported compression levels Default
    zstd 1 - fastest speed, 2 - default, 3 - better compression, 4 - best compression 2
    snappy no levels
    lz4 From 1 (fastest) to 16 1
    gzip and pgzip -1 - default compression, 0 - no compression, 1 - best speed, 9 - best compression -1

    Note that the higher value you specify, the more time and computing resources it will take to compress the data.

    Backups in sharded clusters¶

    For PBM v1.0 (only)

    Before running pbm backup on a cluster, stop the balancer.

    In sharded clusters, one of the pbm-agent processes for every shard and the config server replica set writes backup snapshots into the remote backup storage directly. For logical backups, pbm-agents also write oplog slices. To learn more about oplog slicing, see Point-in-Time Recovery.

    The mongos nodes are not involved in the backup process.

    The following diagram illustrates the backup flow.

    image

    Important

    If you reshard a collection in MongoDB 5.0 and higher versions, make a fresh backup to prevent data inconsistency and restore failure.

    Adjust node priority for backups¶

    In Percona Backup for MongoDB prior to version 1.5.0, the pbm-agent to do a backup is elected randomly among secondary nodes in a replica set. In sharded cluster deployments, the pbm-agent is elected among the secondary nodes in every shard and the config server replica sets. If no secondary node responds in a defined period, then the pbm-agent on the primary node is elected to do a backup.

    As of version 1.5.0, you can influence the pbm-agent election by assigning a priority to mongod nodes in the Percona Backup for MongoDB configuration file.

    backup:
      priority:
        "localhost:28019": 2.5
        "localhost:27018": 2.5
        "localhost:27020": 2.0
        "localhost:27017": 0.1
    

    The format of the priority array is <hostname:port>:<priority>.

    To define priority in a sharded cluster, you can either list all nodes or specify priority for one node in each shard and config server replica set. The hostname and port uniquely identifies a node so that Percona Backup for MongoDB recognizes where it belongs to and grants the priority accordingly.

    Note that if you listed only specific nodes, the remaining nodes will be automatically assigned priority 1.0. For example, you assigned priority 2.5 to only one secondary node in every shard and config server replica set of the sharded cluster.

    backup:
      priority:
        "localhost:27027": 2.5  # config server replica set
        "localhost:27018": 2.5  # shard 1
        "localhost:28018": 2.5  # shard 2
    

    The remaining secondaries and the primary nodes in the cluster receive priority 1.0.

    The mongod node with the highest priority makes the backup. If this node is unavailable, the next priority node is selected. If there are several nodes with the same priority, one of them is randomly elected to make the backup.

    If you haven’t listed any nodes for the priority option in the config, the nodes have the default priority for making backups as follows:

    • hidden nodes - priority 2.0
    • secondary nodes - priority 1.0
    • primary node - priority 0.5

    Important

    As soon as you adjust node priorities in the configuration file, it is assumed that you take manual control over them. The default rule to prefer secondary nodes over primary stops working.

    This ability to adjust node priority helps you manage your backup strategy by selecting specific nodes or nodes from preferred data centers. In geographically distributed infrastructures, you can reduce network latency by making backups from nodes in geographically closest locations.

    Next steps¶

    • List backups
    • Make a restore

    Useful links¶

    • Backup and restore types
    • Schedule backups

    Contact Us

    For free technical help, visit the Percona Community Forum.

    To report bugs or submit feature requests, open a JIRA ticket.

    For paid support and managed or consulting services , contact Percona Sales.


    Last update: May 31, 2023
    Created: May 31, 2023
    Percona LLC and/or its affiliates, © 2023
    Made with Material for MkDocs

    Cookie consent

    We use cookies to recognize your repeated visits and preferences, as well as to measure the effectiveness of our documentation and whether users find what they're searching for. With your consent, you're helping us to make our documentation better.