Tips for Upgrading Percona Server for MongoDB

Agus Syafaat


Percona Server for MongoDB is a MongoDB open source distribution powered by Percona. It is a free, fully compatible and drop in replacement for MongoDB Community edition. It also provides “enterprise grade” features that would otherwise only be available in the Enterprise Edition of MongoDB, for example: LDAP Authentication and Authorization, Audit Logging, Kerberos Authentication.

Upgrading Percona Server for MongoDB is really straightforward. In this blog, we will discuss some upgrade tips and show an example of how to upgrade from version 3.6 to version 4.0.

Upgrade Preparation

Before you run the upgrade, you might want to do some preparation. Always check compatibility changes in documentation and on your application side; check the documentation related to changes and improvement features, obsolete functionality (if any). 

Check the driver compatibility matrix for MongoDB to understand if you need to upgrade the driver too.

Prepare a step by step checklist on how the upgrade will be executed. Write down the action plan, parties need to be involved in the documentation, rollback plan for worst case scenarios.

Upgrading Percona Server for MongoDB

It’s always good to test your upgrade in the development or staging environment before you move to the production environment. You can build exactly the same MongoDB architecture as production, test and restore the data from the last backup. After that, you can test the upgrade and validate your upgrade plan, not only that you can get an estimation on how long the upgrade will take and also verify if the application is compatible with the new version of the database.

The upgrade process just installs the new package from the percona repository, this is how to upgrade on CentOS based from version 3.6 to version 4.0.

Step One

If you haven’t installed Percona Repository, you can install percona-release-latest.

[root@n8 ~]# yum install

Loaded plugins: fastestmirror

percona-release-latest.noarch.rpm                                                                                   |  19 kB  00:00:00

Examining /var/tmp/yum-root-evWD4w/percona-release-latest.noarch.rpm: percona-release-1.0-25.noarch

Marking /var/tmp/yum-root-evWD4w/percona-release-latest.noarch.rpm to be installed

Resolving Dependencies

--> Running transaction check

---> Package percona-release.noarch 0:1.0-25 will be installed

--> Finished Dependency Resolution

Dependencies Resolved


 Package                          Arch                    Version                    Repository                                       Size



 percona-release                  noarch                  1.0-25                     /percona-release-latest.noarch                   31 k

Transaction Summary


Install  1 Package

Total size: 31 k

Installed size: 31 k

Is this ok [y/d/N]: y

Step Two

After installing Percona repository, enable Percona Server for MongoDB 4.0

[root@n8 ~]# percona-release enable psmdb-40

* Enabling the Percona Server for MongoDB 4.0 repository

<*> All done!

Step Three

Install the new package percona-server-mongodb, it will automatically remove the old package and install new package:

[root@n8 ~]# yum install percona-server-mongodb

Loaded plugins: fastestmirror

Repository percona-release-noarch is listed more than once in the configuration

base                                                                                                                | 3.6 kB  00:00:00

extras                                                                                                              | 2.9 kB  00:00:00

percona-release                                                                                                     | 2.9 kB  00:00:00

percona-release-noarch                                                                                              | 2.9 kB  00:00:00

percona-release-x86_64                                                                                              | 2.9 kB  00:00:00

prel-release-noarch                                                                                                 | 2.9 kB  00:00:00

psmdb-40-release-x86_64                                                                                             | 2.9 kB  00:00:00

updates                                                                                                             | 2.9 kB  00:00:00

(1/3): prel-release-noarch/7/primary_db                                                                             | 2.5 kB  00:00:00

(2/3): psmdb-40-release-x86_64/7/primary_db                                                                         |  47 kB  00:00:01

(3/3): percona-release-x86_64/7/primary_db                                                                          | 1.1 MB  00:00:03

Loading mirror speeds from cached hostfile

 * base:

 * extras:

 * updates:

Resolving Dependencies

--> Running transaction check

---> Package Percona-Server-MongoDB-36.x86_64 0:3.6.19-8.0.el7 will be obsoleted

---> Package percona-server-mongodb.x86_64 0:4.0.20-14.el7 will be obsoleting

--> Processing Dependency: percona-server-mongodb-tools = 4.0.20-14.el7 for package: percona-server-mongodb-4.0.20-14.el7.x86_64

--> Processing Dependency: percona-server-mongodb-mongos = 4.0.20-14.el7 for package: percona-server-mongodb-4.0.20-14.el7.x86_64

--> Processing Dependency: percona-server-mongodb-shell = 4.0.20-14.el7 for package: percona-server-mongodb-4.0.20-14.el7.x86_64

--> Processing Dependency: percona-server-mongodb-server = 4.0.20-14.el7 for package: percona-server-mongodb-4.0.20-14.el7.x86_64

--> Running transaction check

---> Package Percona-Server-MongoDB-36-mongos.x86_64 0:3.6.19-8.0.el7 will be obsoleted

---> Package Percona-Server-MongoDB-36-server.x86_64 0:3.6.19-8.0.el7 will be obsoleted

---> Package Percona-Server-MongoDB-36-shell.x86_64 0:3.6.19-8.0.el7 will be obsoleted

---> Package Percona-Server-MongoDB-36-tools.x86_64 0:3.6.19-8.0.el7 will be obsoleted

---> Package percona-server-mongodb-mongos.x86_64 0:4.0.20-14.el7 will be obsoleting

---> Package percona-server-mongodb-server.x86_64 0:4.0.20-14.el7 will be obsoleting

---> Package percona-server-mongodb-shell.x86_64 0:4.0.20-14.el7 will be obsoleting

---> Package percona-server-mongodb-tools.x86_64 0:4.0.20-14.el7 will be obsoleting

--> Finished Dependency Resolution

Dependencies Resolved


 Package                                     Arch                 Version                      Repository                             Size



 percona-server-mongodb                      x86_64               4.0.20-14.el7                psmdb-40-release-x86_64               4.9 k

     replacing  Percona-Server-MongoDB-36.x86_64 3.6.19-8.0.el7

 percona-server-mongodb-mongos               x86_64               4.0.20-14.el7                psmdb-40-release-x86_64               8.9 M

     replacing  Percona-Server-MongoDB-36-mongos.x86_64 3.6.19-8.0.el7

 percona-server-mongodb-server               x86_64               4.0.20-14.el7                psmdb-40-release-x86_64                19 M

     replacing  Percona-Server-MongoDB-36-server.x86_64 3.6.19-8.0.el7

 percona-server-mongodb-shell                x86_64               4.0.20-14.el7                psmdb-40-release-x86_64               9.8 M

     replacing  Percona-Server-MongoDB-36-shell.x86_64 3.6.19-8.0.el7

 percona-server-mongodb-tools                x86_64               4.0.20-14.el7                psmdb-40-release-x86_64                28 M

     replacing  Percona-Server-MongoDB-36-tools.x86_64 3.6.19-8.0.el7

Transaction Summary


Install  5 Packages

Total download size: 66 M

Is this ok [y/d/N]: y

Downloading packages:

(1/5): percona-server-mongodb-4.0.20-14.el7.x86_64.rpm                                                              | 4.9 kB  00:00:05

(2/5): percona-server-mongodb-mongos-4.0.20-14.el7.x86_64.rpm                                                       | 8.9 MB  00:00:39

(3/5): percona-server-mongodb-shell-4.0.20-14.el7.x86_64.rpm                                                        | 9.8 MB  00:00:42

(4/5): percona-server-mongodb-server-4.0.20-14.el7.x86_64.rpm                                                       |  19 MB  00:01:23

(5/5): percona-server-mongodb-tools-4.0.20-14.el7.x86_64.rpm                                                        |  28 MB  00:02:00


Total                                                                                                      332 kB/s |  66 MB  00:03:22

Running transaction check

Running transaction test

Transaction test succeeded

Running transaction

  Installing : percona-server-mongodb-shell-4.0.20-14.el7.x86_64                                                                      1/10

  Installing : percona-server-mongodb-server-4.0.20-14.el7.x86_64                                                                     2/10

warning: /etc/mongod.conf created as /etc/mongod.conf.rpmnew

 * To start the service, configure your engine and start mongod

 ** WARNING: Access control is not enabled for the database.

 ** Read and write access to data and configuration is unrestricted.

 ** To fix this please use /usr/bin/

  Installing : percona-server-mongodb-mongos-4.0.20-14.el7.x86_64                                                                     3/10

  Installing : percona-server-mongodb-tools-4.0.20-14.el7.x86_64                                                                      4/10

  Installing : percona-server-mongodb-4.0.20-14.el7.x86_64                                                                            5/10

  Erasing    : Percona-Server-MongoDB-36-3.6.19-8.0.el7.x86_64                                                                        6/10

  Erasing    : Percona-Server-MongoDB-36-server-3.6.19-8.0.el7.x86_64                                                                 7/10

  Erasing    : Percona-Server-MongoDB-36-shell-3.6.19-8.0.el7.x86_64                                                                  8/10

  Erasing    : Percona-Server-MongoDB-36-mongos-3.6.19-8.0.el7.x86_64                                                                 9/10

  Erasing    : Percona-Server-MongoDB-36-tools-3.6.19-8.0.el7.x86_64                                                                 10/10

  Verifying  : percona-server-mongodb-server-4.0.20-14.el7.x86_64                                                                     1/10

  Verifying  : percona-server-mongodb-tools-4.0.20-14.el7.x86_64                                                                      2/10

  Verifying  : percona-server-mongodb-mongos-4.0.20-14.el7.x86_64                                                                     3/10

  Verifying  : percona-server-mongodb-shell-4.0.20-14.el7.x86_64                                                                      4/10

  Verifying  : percona-server-mongodb-4.0.20-14.el7.x86_64                                                                            5/10

  Verifying  : Percona-Server-MongoDB-36-server-3.6.19-8.0.el7.x86_64                                                                 6/10

  Verifying  : Percona-Server-MongoDB-36-tools-3.6.19-8.0.el7.x86_64                                                                  7/10

  Verifying  : Percona-Server-MongoDB-36-mongos-3.6.19-8.0.el7.x86_64                                                                 8/10

  Verifying  : Percona-Server-MongoDB-36-shell-3.6.19-8.0.el7.x86_64                                                                  9/10

  Verifying  : Percona-Server-MongoDB-36-3.6.19-8.0.el7.x86_64                                                                       10/10


  percona-server-mongodb.x86_64 0:4.0.20-14.el7                        percona-server-mongodb-mongos.x86_64 0:4.0.20-14.el7

  percona-server-mongodb-server.x86_64 0:4.0.20-14.el7                 percona-server-mongodb-shell.x86_64 0:4.0.20-14.el7

  percona-server-mongodb-tools.x86_64 0:4.0.20-14.el7


  Percona-Server-MongoDB-36.x86_64 0:3.6.19-8.0.el7                    Percona-Server-MongoDB-36-mongos.x86_64 0:3.6.19-8.0.el7

  Percona-Server-MongoDB-36-server.x86_64 0:3.6.19-8.0.el7             Percona-Server-MongoDB-36-shell.x86_64 0:3.6.19-8.0.el7

  Percona-Server-MongoDB-36-tools.x86_64 0:3.6.19-8.0.el7


Step Four

Finally, start mongod services.

$ systemctl start mongod.service

The installation process on Ubuntu/Debian based is similar, you just need the command from APT package manager.

In a highly available MongoDB architecture, you can do a rolling upgrade to minimize the downtime. 

If your application already supports the latest MongoDB version, you can set the parameter 

setFeatureCompatibilityVersion after the upgrade was completed.

> db.adminCommand( { setFeatureCompatibilityVersion: "4.0" } )

Upgrade Verification

You can verify if the upgrade was successful by connecting directly to the MongoDB instance. Check if the database is running with the correct version:

> db.version()

Or you can check from the commandline:

[root@n8 lib]# mongod --version

db version v4.0.20-14

git version: b96ae5b9e6c70670b6880d4c5412167a7017713a

OpenSSL version: OpenSSL 1.0.2k-fips  26 Jan 2017

allocator: tcmalloc

modules: none

build environment:

    distarch: x86_64

    target_arch: x86_64

Subscribe below to be notified of fresh posts