Skip to content
logo
Percona Backup for MongoDB
Upgrade PBM
Initializing search
    percona/pbm-docs
    percona/pbm-docs
    • Home
      • How PBM works
      • Components
      • Supported MongoDB versions
      • Supported MongoDB deployments
      • Install
      • Set up and configure
      • Overview
      • Physical backups
      • Incremental physical backups
      • Logical backups
      • Selective backups
      • Point-in-Time Recovery
      • Start a backup
      • List backups
      • Restore a backup
      • View restore progress
      • Cancel a backup
      • Delete backups
      • View backup logs
      • Replay oplog from arbitrary start time
      • Architecture
      • Authentication
        • Overview
        • Remote backup configuration examples
      • Schedule backups
      • Configure PBM remotely
      • Upgrade PBM
        • Important notes
        • Prerequisites
          • 1. Install percona-release
          • 2. Enable the repository
        • Upgrade to the latest version
          • 1. Stop pbm-agent
          • 2. Install new packages
          • 3. Reload the systemd process
          • 4. Update permissions
          • 5. Start pbm-agent
          • 1. Stop pbm-agent
          • 2. Install new packages
          • 3. Reload the systemd process
          • 4. Update permissions
          • 5. Start pbm-agent
        • Upgrade to a specific version
          • 1. List available versions
          • 2. Stop pbm-agent
          • 3. Install packages
          • 4. Update permissions
          • 5. Start pbm-agent
          • 1. List available versions
          • 2. Stop pbm-agent
          • 3. Install packages
          • 4. Update permissions
          • 5. Start pbm-agent
      • Troubleshoot PBM
      • Automate access to S3 buckets for 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.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)
    • Submitting bug reports or feature requests
    • Copyright and Licensing
    • Trademark policy

    • Important notes
    • Prerequisites
      • 1. Install percona-release
      • 2. Enable the repository
    • Upgrade to the latest version
      • 1. Stop pbm-agent
      • 2. Install new packages
      • 3. Reload the systemd process
      • 4. Update permissions
      • 5. Start pbm-agent
      • 1. Stop pbm-agent
      • 2. Install new packages
      • 3. Reload the systemd process
      • 4. Update permissions
      • 5. Start pbm-agent
    • Upgrade to a specific version
      • 1. List available versions
      • 2. Stop pbm-agent
      • 3. Install packages
      • 4. Update permissions
      • 5. Start pbm-agent
      • 1. List available versions
      • 2. Stop pbm-agent
      • 3. Install packages
      • 4. Update permissions
      • 5. Start pbm-agent

    Upgrade Percona Backup for MongoDB¶

    Similar to installing, the recommended and most convenient way to upgrade PBM is from the Percona repository.

    You can upgrade Percona Backup for MongoDB either to the latest version or to a specific version. Since all packages of Percona Backup for MongoDB are stored in the same repository, the following steps apply to both upgrade scenarios:

    1. Enable Percona repository.
    2. Stop pbm-agent.
    3. Install new version packages (the old ones are automatically removed).
    4. Start pbm-agent.

    Important notes¶

    1. Backward compatibility between data backup and restore is supported for upgrades within one major version only (for example, from 1.1.x to 1.2.y). When you upgrade Percona Backup for MongoDB over several major versions (for example, from 1.0.x to 1.2.y), we recommend to make a backup right after the upgrade.

    2. Percona Backup for MongoDB v1.5.0 and later is incompatible with Percona Backup for MongoDB v1.4.1 and earlier due to different processing of system collections Users and Roles during backup / restore operations. After the upgrade to Percona Backup for MongoDB v1.5.0 and later, make sure to make a fresh backup.

    3. Starting from v1.7.0, the user running the pbm-agent process is changed from pbm to mongod. This is done for the following reasons:

      • To make physical backups and restores, the user running the pbm-agent process must have the read / write permissions to the MongoDB dataDir.

      • To use the filesystem-based backup storage, the user running the pbm-agent process must also have the read / write permissions to the backup directory.

    4. Starting from version 1.3.0, Percona Backup for MongoDB packages are stored in the pbm repository and the tools repository for backward compatibility.

    5. Upgrade Percona Backup for MongoDB on all nodes where it is installed.

    Important

    Run all commands as root or via sudo.

    Prerequisites¶

    1. Install percona-release¶

    Install percona-release tool. If you have installed it before, update it to the latest version.

    2. Enable the repository¶

    Run the following command as root or via sudo

    sudo percona-release enable pbm release
    

    Note

    For apt-based systems, run sudo apt update to update the local cache.

    Upgrade to the latest version¶

    1. Stop pbm-agent¶

    sudo systemctl stop pbm-agent
    

    2. Install new packages¶

    sudo apt install percona-backup-mongodb
    

    3. Reload the systemd process¶

    Starting from v1.7.0, reload the systemd process to update the unit file with the following command:

    sudo systemctl daemon-reload
    

    4. Update permissions¶

    For a filesystem-based backup storage, grant read / write permissions to the backup directory to the mongod user.

    5. Start pbm-agent¶

    sudo systemctl start pbm-agent
    

    1. Stop pbm-agent¶

    sudo systemctl stop pbm-agent
    

    2. Install new packages¶

    sudo yum install percona-backup-mongodb
    

    3. Reload the systemd process¶

    Starting from v1.7.0, reload the systemd process to update the unit file with the following command:

    sudo systemctl daemon-reload
    

    4. Update permissions¶

    For a filesystem-based backup storage, grant read / write permissions to the backup directory to the mongod user.

    5. Start pbm-agent¶

    sudo systemctl start pbm-agent
    

    Upgrade to a specific version¶

    1. List available versions¶

    sudo apt-cache madison percona-backup-mongodb
    

    Output:

    percona-backup-mongodb | 1.8.1-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    percona-backup-mongodb | 1.8.0-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    percona-backup-mongodb | 1.7.0-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    percona-backup-mongodb | 1.6.1-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    percona-backup-mongodb | 1.6.0-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    percona-backup-mongodb | 1.5.0-1.stretch | http://repo.percona.com/tools/apt stretch/main amd64 Packages
    

    2. Stop pbm-agent¶

    sudo systemctl stop pbm-agent
    

    3. Install packages¶

    Install a specific version packages. For example, to upgrade to Percona Backup for MongoDB 1.7.0, run the following command:

    sudo apt install percona-backup-mongodb=1.7.0-1.stretch
    

    4. Update permissions¶

    For a filesystem-based backup storage, grant read / write permissions to the backup directory to the mongod user.

    5. Start pbm-agent¶

    sudo systemctl start pbm-agent
    

    1. List available versions¶

    sudo yum list percona-backup-mongodb --showduplicates
    

    Output:

    Available Packages
    percona-backup-mongodb.x86_64    1.8-1.el7            pbm-release-x86_64
    percona-backup-mongodb.x86_64    1.8.0-1.el7          pbm-release-x86_64
    percona-backup-mongodb.x86_64    1.7.0-1.el7          pbm-release-x86_64
    percona-backup-mongodb.x86_64    1.6.1-1.el7          pbm-release-x86_64
    percona-backup-mongodb.x86_64    1.6.0-1.el7          pbm-release-x86_64
    percona-backup-mongodb.x86_64    1.5.0-1.el7          pbm-release-x86_64
    

    2. Stop pbm-agent¶

    sudo systemctl stop pbm-agent
    

    3. Install packages¶

    Install a specific version packages. For example, to upgrade to Percona Backup for MongoDB 1.7.1, run the following command:

    sudo yum install percona-backup-mongodb-1.7.1-1.el7
    

    4. Update permissions¶

    For a filesystem-based backup storage, grant read / write permissions to the backup directory to the mongod user.

    5. Start pbm-agent¶

    sudo systemctl start pbm-agent
    

    Note

    If MongoDB runs under a different user than mongod (the default configuration for Percona Server for MongoDB), use the same user to run the pbm-agent. For filesystem-based storage, grant the read / write permissions to the backup directory for this user.

    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: March 23, 2023
    Created: March 23, 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.