Upgrading from MongoDB 4.0 Community Edition

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

An in-place upgrade is done with existing data in the server. Generally speaking, this is stopping the server, removing the old packages, installing the new server and starting it with the same data files. While an in-place upgrade may not be suitable for high-complexity environments, it should work in most cases.

Warning

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

The sections below describe an in-place upgrade of a standalone instance and a replica set. If using data-at-rest encryption please see extra note at end.

Upgrading a standalone instance or a single-node replica set

The upgrade procedure depends on the distribution you are using:

Upgrading on Debian or Ubuntu

Run the following commands as root or by using the sudo command

Important

Before you start the upgrading, update the MongoDB configuration file (/etc/mongod.conf) to contain the following settings. Otherwise the mongod service will not be able to start.

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

  1. Stop the mongod service: systemctl stop mongod

  2. Check for installed packages: dpkg -l | grep mongod

    Output

    ii  mongodb-org            4.2.7    amd64      MongoDB open source document-oriented database system (metapackage)
ii  mongodb-org-mongos     4.2.7    amd64      MongoDB sharded cluster query router
ii  mongodb-org-server     4.2.7    amd64      MongoDB database server
ii  mongodb-org-shell      4.2.7    amd64      MongoDB shell client
ii  mongodb-org-tools      4.2.7    amd64      MongoDB tools

  3. Remove the installed packages:

    $ apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server \
$ mongodb-org-shell mongodb-org-tools

  4. Remove log files: 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: systemctl start mongod

Upgrading on Red Hat Enterprise Linux or CentOS

Run the following commands as root or by using the sudo command

Important

Before you start the upgrading, update the MongoDB configuration file (/etc/mongod.conf) to contain the following settings. Otherwise the mongod service will not be able to start.

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

  1. Stop the mongod service: systemctl stop mongod

  2. Check for installed packages: rpm -qa | grep mongo

    Output

    mongodb-org-mongos-4.2.7-1.el6.x86_64
mongodb-org-shell-4.2.7-1.el6.x86_64
mongodb-org-server-4.2.7-1.el6.x86_64
mongodb-org-tools-4.2.7-1.el6.x86_64
mongodb-org-4.2.7-1.el6.x86_64

  3. Remove the installed packages:

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

  4. Remove log files: rm -r /var/log/mongodb

  5. Install Percona Server for MongoDB using yum.

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.

Upgrading a replica set

The rolling restart method allows upgrading a replica set from MongoDB 4.2 Community Edition to Percona Server for MongoDB with minimum downtime. You upgrade the nodes one by one while the whole cluster remains operational.

Upgrade some but not all replica set nodes

  1. Upgrade a node in a replica set as described in Upgrading a standalone instance or a single-node replica set. Use the instructions relevant to your operating system.

Note

It is better to upgrade the secondary node to avoid an extra election of the primary one. If you upgrade the primary node, run the rs.stepDown() command before shutting it down.

  1. Wait for the node to rejoin with the replica set members, resync and report that it is in the SECONDARY status.
  2. Optional: repeat the upgrade procedure on other (but not on all) nodes.

Test the Percona Server for MongoDB node in the primary role before all nodes are upgraded

This step is optional. Its purpose is to run a testing stage with the Percona Server for MongoDB node as primary whilst at least one of nodes still runs the old version. This will make rolling back a little quicker if you choose to do so.

  1. Use rs.stepDown() on the current primary node to start an election of a new primary among nodes with Percona Server for MongoDB installed. If you have multiple nodes of the previous version, use rs.freeze() on them to make sure one of Percona Server for MongoDB nodes becomes primary.

Upgrade the last node(s)

  1. If any of the previous version nodes is the current primary node, step it down: rs.stepDown().
  2. Wait for the remaining nodes to elect a new primary. Run rs.status() to verify that the former primary node reports as SECONDARY.
  3. Upgrade the node as described in Upgrading a standalone instance or a single-node replica set.

See also

MongoDB Documentation: Upgrade a Replica Set
https://docs.mongodb.com/manual/release-notes/4.2-upgrade-replica-set/

Note

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

Download PDF Manual

Table Of Contents

This Page

Percona Server for MongoDB Series