Skip to content
logo
Percona Server for MongoDB 5.0
Upgrading Percona Server for MongoDB
Initializing search
    percona/psmdb-docs
    percona/psmdb-docs
    • Home
    • Percona Server for MongoDB feature comparison
      • Overview
      • Installing Percona Server for MongoDB on Debian and Ubuntu
      • Installing Percona Server for MongoDB on Red Hat Enterprise Linux and CentOS
      • Installing Percona Server for MongoDB from binary tarball
      • Running Percona Server for MongoDB in a Docker Container
        • Percona Memory Engine
        • Hot Backup
        • $backupCursor and $backupCursorExtend aggregation stages
        • Authentication overview
        • Enable SCRAM authentication
        • Set up LDAP authentication with SASL
        • Set up x.509 authentication and LDAP authorization
        • Set up Kerberos authentication
        • AWS IAM authentication
        • Setting up AWS IAM authentication
        • LDAP authorization
        • Set up LDAP authentication and authorization using NativeLDAP
        • Data at rest encryption
        • HashiCorp Vault integration
        • Using the Key Management Interoperability Protocol (KMIP)
        • Local key management using a keyfile
        • Migrating from key file encryption to HashiCorp Vault encryption
      • Auditing
      • Profiling Rate Limit
      • Log Redaction
      • Additional text search algorithm - ngram
      • Tune parameters
        • Upgrade from 4.4 to 5.0
        • Upgrading Percona Server for MongoDB
          • Upgrading from MongoDB 5.0 Community Edition
            • Prerequisites
          • Minor upgrade of Percona Server for MongoDB
          • Upgrading to Percona Server for MongoDB with data at rest encryption enabled
      • Uninstall Percona Server for MongoDB
      • Percona Server for MongoDB 5.0 Release Notes
      • Percona Server for MongoDB 5.0.15-13 (2023-03-16)
      • Percona Server for MongoDB 5.0.14-12 (2022-12-08)
      • Percona Server for MongoDB 5.0.13-11 (2022-10-12)
      • Percona Server for MongoDB 5.0.11-10 (2022-09-01)
      • Percona Server for MongoDB 5.0.10-9 (2022-08-09)
      • Percona Server for MongoDB 5.0.9-8 (2022-06-20)
      • Percona Server for MongoDB 5.0.8-7 (2022-05-10)
      • Percona Server for MongoDB 5.0.7-6 (2022-04-20)
      • Percona Server for MongoDB 5.0.6-5 (2022-02-10)
      • Percona Server for MongoDB 5.0.5-4 (2021-12-28)
      • Percona Server for MongoDB 5.0.4-3 (Release Candidate) (2021-12-08)
      • Percona Server for MongoDB 5.0.3-2 (Release Candidate) (2021-10-14)
      • Percona Server for MongoDB 5.0.2-1 (Release Candidate) (2021-08-16)
    • Glossary
    • Copyright and licensing information
    • Trademark policy

    • Upgrading from MongoDB 5.0 Community Edition
      • Prerequisites
    • Minor upgrade of Percona Server for MongoDB
    • Upgrading to Percona Server for MongoDB with data at rest encryption enabled

    Upgrading Percona Server for MongoDB¶

    An in-place upgrade is done by keeping the existing data in the server. It involves changing out the MongoDB binaries. Generally speaking, the upgrade steps include:

    1. Stopping the mongod service
    2. Removing the old binaries
    3. Installing the new server version binaries
    4. Restarting the mongod service with the same dbpath data directory.

    An in-place upgrade is suitable for most environments except the ones that use ephemeral storage and/or host addresses.

    This document provides upgrade instructions for the following use cases:

    • Upgrading from MongoDB 5.0 Community Edition

    • Minor upgrade of Percona Server for MongoDB

    Upgrading from MongoDB 5.0 Community Edition¶

    NOTE: MongoDB creates a user that belongs to two groups, which is a potential security risk. This is fixed in Percona Server for MongoDB: the user is included only in the mongod group. To avoid problems with current MongoDB setups, existing user group membership is not changed when you migrate to Percona Server for MongoDB. Instead, a new mongod user is created during installation, and it belongs to the mongod group.

    This section describes an in-place upgrade of a mongod instance. If you are using data at rest encryption, refer to the Upgrading to Percona Server for MongoDB with data at rest encryption enabled section.

    Prerequisites¶

    Before you start the upgrade, update the MongoDB configuration file (/etc/mongod.conf) to contain the following settings.

    processManagement:
       fork: true
       pidFilePath: /var/run/mongod.pid
    

    Troubleshooting tip: The pidFilePath setting in mongod.conf must match the PIDFile option in the systemd mongod service unit. Otherwise, the service will kill the mongod process after a timeout.

    WARNING: Before starting the upgrade, we recommend to perform a full backup of your data.

    To upgrade a replica set or a sharded cluster, use the rolling restart method. It allows you to perform the upgrade with minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.

    Before you start the upgrade, update the MongoDB configuration file (/etc/mongod.conf) to contain the following settings.

    processManagement:
       fork: true
       pidFilePath: /var/run/mongod.pid
    

    Troubleshooting tip: The pidFilePath setting in mongod.conf must match the PIDFile option in the systemd mongod service unit. Otherwise, the service will kill the mongod process after a timeout.

    Warning

    Before starting the upgrade, we recommend to perform a full backup of your data.

    1. Stop the mongod service:

      $ sudo systemctl stop mongod
      
    2. Check for installed packages:

      $ sudo dpkg -l | grep mongod
      

      Output:

      ii  mongodb-org            5.0.2    amd64   MongoDB open source document-oriented database system (metapackage)
      ii  mongodb-org-database   5.0.2    amd64   MongoDB open source document-oriented database system (metapackage)
      ii  mongodb-org-database-tools-extra 5.0.2   amd64   Extra MongoDB database tools
      ii  mongodb-org-mongos     5.0.2    amd64   MongoDB sharded cluster query router
      ii  mongodb-org-server     5.0.2    amd64   MongoDB database server
      ii  mongodb-org-shell      5.0.2    amd64   MongoDB shell client
      ii  mongodb-org-tools      5.0.2    amd64   MongoDB tools
      
    3. Remove the installed packages:

      $ sudo apt remove \
        mongodb-org \
        mongodb-org-mongos \
        mongodb-org-server \
        mongodb-org-shell \
        mongodb-org-tools
      
    4. Remove log files:

      $ sudo rm -r /var/log/mongodb
      
    5. Install Percona Server for MongoDB

    6. Verify that the configuration file includes the correct options. For example, Percona Server for MongoDB stores data files in /var/lib/mongodb by default. If you used another dbPath data directory, edit the configuration file accordingly

    7. Start the mongod service:

      $ sudo systemctl start mongod
      
    1. Stop the mongod service:

      $ sudo systemctl stop mongod
      
    2. Check for installed packages:

      $ sudo rpm -qa | grep mongo
      

      Output:

      mongodb-org-shell-5.0.2-1.el8.x86_64
      mongodb-org-database-5.0.0-1.el8.x86_64
      mongodb-org-5.0.0-1.el8.x86_64
      mongodb-database-tools-100.4.1-1.x86_64
      mongodb-org-server-5.0.2-1.el8.x86_64
      mongodb-org-mongos-5.0.2-1.el8.x86_64
      mongodb-org-tools-5.0.0-1.el8.x86_64
      
    3. Remove the installed packages:

      $ sudo yum remove \
      mongodb-org-tools-5.0.0-1.el8.x86_64 \
      mongodb-org-shell-5.0.2-1.el8.x86_64 \
      mongodb-org-database-5.0.0-1.el8.x86_64 \
      mongodb-org-5.0.0-1.el8.x86_64 \
      mongodb-database-tools-100.4.1-1.x86_64 \
      mongodb-org-server-5.0.2-1.el8.x86_64 \
      mongodb-org-mongos-5.0.2-1.el8.x86_64 \
      
    4. Remove log files:

      $ sudo rm -r /var/log/mongodb
      
    5. Install Percona Server for MongoDB

      Note

      When you remove old packages, your existing configuration file is saved as /etc/mongod.conf.rpmsave. If you want to use this configuration with the new version, replace the default /etc/mongod.conf file. For example, existing data may not be compatible with the default WiredTiger storage engine.

    6. Start the mongod service:

      $ sudo systemctl start mongod
      

    To upgrade a replica set or a sharded cluster, use the rolling restart method. It allows you to perform the upgrade with minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.

    See also

    MongoDB Documentation:

    • Upgrade a Replica Set
    • Upgrade a Sharded Cluster

    Minor upgrade of Percona Server for MongoDB¶

    To upgrade Percona Server for MongoDB to the latest version, follow these steps:

    1. Stop the mongod service:

      $ sudo systemctl stop mongod
      
    2. Install the latest version packages. Use the command relevant to your operating system.

    3. Start the mongod service:

      $ sudo systemctl start mongod
      

    To upgrade a replica set or a sharded cluster, use the rolling restart method. It allows you to perform the upgrade with minimum downtime. You upgrade the nodes one by one, while the whole cluster / replica set remains operational.

    Upgrading to Percona Server for MongoDB with data at rest encryption enabled¶

    Steps to upgrade from MongoDB 5.0 Community Edition with data encryption enabled to Percona Server for MongoDB are different. mongod requires an empty dbPath data directory because it cannot encrypt data files in place. It must receive data from other replica set members during the initial sync. Please refer to the Switching storage engines for more information on migration of encrypted data. Contact us for working at the detailed migration steps, if further assistance is needed.

    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: February 6, 2023
    Created: December 8, 2022
    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.