Skip to content

This documentation is for the end of life version of Percona Server for MongoDB and is no longer supported. You may want to see the current documentation.

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:

  • stopping the mongod service,

  • removing the old binaries,

  • installing the new server version binaries, and

  • 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 4.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: 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.

  1. Stop the mongod service:

    $ sudo systemctl stop mongod

  2. Check for installed packages:

    $ sudo dpkg -l | grep mongod

    Output

    ii  mongodb-org            4.0.4    amd64      MongoDB document-oriented database system (metapackage)
ii  mongodb-org-mongos     4.0.4    amd64      MongoDB sharded cluster query router
ii  mongodb-org-server     4.0.4    amd64      MongoDB database server
ii  mongodb-org-shell      4.0.4    amd64      MongoDB shell client
ii  mongodb-org-tools      4.0.4    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 using apt.

  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 mongod start

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:

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.

    $ sudo apt install percona-server-mongodb

  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 4.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.