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 from MongoDB 3.6 Community Edition to Percona Server for MongoDB

An in-place upgrade is done with existing data in the server. Generally speaking, this is stopping the mongod service, removing the old packages, installing the new server and starting it with the same db data directory. An in-place upgrade is suitable for most environments, except the ones that use ephemeral storage and/or host addresses.

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

Upgrading on Debian or Ubuntu

1. Stop the mongod service:

   $ sudo systemctl stop mongod
   

2. Check for installed packages:

   $ dpkg -l | grep mongod
   
   ii  mongodb-org                    3.6.2                              amd64        MongoDB open source document-oriented database system (metapackage)
   ii  mongodb-org-mongos             3.6.2                              amd64        MongoDB sharded cluster query router
   ii  mongodb-org-server             3.6.2                              amd64        MongoDB database server
   ii  mongodb-org-shell              3.6.2                              amd64        MongoDB shell client
   ii  mongodb-org-tools              3.6.2                              amd64        MongoDB tools
   

3. Remove installed packages:

   $ sudo apt-get 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 start mongod
   

Upgrading on Red Hat Enterprise Linux or CentOS

1. Stop the mongod service:

   $ sudo systemctl stop mongod
   

2. Check for installed packages:

   $ rpm -qa | grep mongo
   
   mongodb-org-mongos-3.6.2-1.el6.x86_64
   mongodb-org-shell-3.6.2-1.el6.x86_64
   mongodb-org-server-3.6.2-1.el6.x86_64
   mongodb-org-tools-3.6.2-1.el6.x86_64
   mongodb-org-3.6.2-1.el6.x86_64
   

3. Remove the installed packages:

   $ sudo yum remove \
   mongodb-org-mongos-3.6.2-1.el6.x86_64 mongodb-org-shell-3.6.2-1.el6.x86_64 \
   mongodb-org-server-3.6.2-1.el6.x86_64 mongodb-org-tools-3.6.2-1.el6.x86_64 \
   mongodb-org-3.6.2-1.el6.x86_64
   

4. Remove log files:

   $ sudo rm -r /var/log/mongodb
   

5. Install Percona Server for MongoDB using yum.

6. Start the mongod service:

   $ sudo systemctl start mongod
   

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.

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

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

Steps to upgrade from MongoDB 3.6 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.