In this blog post, we will discuss how we can migrate from the enterprise/community edition of MongoDB to Percona Server for MongoDB. But before we begin, let’s take a second to explain why you should migrate to Percona Server for MongoDB.
Percona Server for MongoDB is a free, source available, drop-in replacement for MongoDB, but with enterprise-grade functionality. It delivers high-performance and reliability to enterprises looking to achieve optimum performance, without being tied into an expensive proprietary software vendor relationship. Percona Server for MongoDB, alongside Percona Backup for MongoDB, is part of Percona Distribution for MongoDB, a holistic enterprise MongoDB solution that ensures data availability for applications while improving security and simplifying the development of new applications in the
most demanding public, private, and hybrid cloud environments.
Anyway, let’s get back to the purpose of the blog: migrating from the enterprise/community edition of MongoDB to Percona Server for MongoDB.
Before starting the migration process it’s recommended that you perform a full backup (if you don’t have one already). See this post for MongoDB backup best practices.
The migration procedure:
- Backup the config files of the Mongo process.
- Stop the Mongo process. If it’s a replica set, then do it in a rolling fashion.
- Remove the package of MongoDB community/enterprise edition. For the replica set, do it in a rolling fashion.
- Install the Percona Server for MongoDB (PSMDB). It can be downloaded from here. Do it in a rolling fashion for a replica set and start the Mongo service.
Detailed migration plan:
Migrate standalone MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL):
1. Backup the mongo config and service file:
1 | sudo cp /etc/mongod.conf /etc/mongod.conf_bkp |
Debian:
1 | sudo cp /lib/systemd/system/mongod.service /lib/systemd/system/mongod.service_bkp |
RHEL/CentOS:
1 | sudo cp /usr/lib/systemd/system/mongod.service /usr/lib/systemd/system/mongod.service_bkp |
2. Stop mongo service first and then remove mongodb-community/enterprise packages and repo:
To stop mongo services, connect to admin database and shutdown as below:
1 2 3 | >use admin >db.shutdownServer() |
Remove the package:
Debian:
1 2 | sudo apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server mongodb-org-shell mongodb-org-tools sudo rm /etc/apt/sources.list.d/mongodb-org-4.0.list |
RHEL/CentOS:
1 | sudo yum erase $(rpm -qa | grep mongodb-org) |
If it’s OpsManager then:
a. Unmanage the project in OpsManager GUI.
b. Make sure to uncheck enforce users in Opsmanager GUI.
c. Disable the automation agent with the below:
1 | sudo apt disable mongodb-mms-automation-agent |
d. Remove the automation agent with:
1 | sudo systemctl remove mongodb-mms-automation-agent |
3. Configure percona repo and install Percona Server for MongoDB (PSMDB):
Debian:
1 2 3 | sudo wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb |
Enable the repo:
1 2 3 | sudo percona-release enable psmdb-44 release sudo apt-get update |
Install the package:
1 | sudo apt-get install percona-server-mongodb |
RHEL/CentOS:
1 | sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm |
Enable the repo:
1 | sudo percona-release setup pdmdb-44 |
Install the package:
1 | sudo yum install percona-server-mongodb |
4. Copy back the mongod config and service file:
1 | sudo cp /etc/mongod.conf_bkp /etc/mongod.conf |
Debian:
1 | sudo cp /lib/systemd/system/mongod.service_bkp /lib/systemd/system/mongod.service |
RHEL/CentOS:
1 | sudo cp /usr/lib/systemd/system/mongod.service_bkp /usr/lib/systemd/system/mongod.service |
NOTE: Kindly check that the permissions and ownership of the data directory, keyfile, and log directory are properly updated for the mongod user.
Also, if the SELinux policy is enabled, then set the necessary SELinux policy for dbPath, keyFile, and logs as below:
1 2 3 4 5 6 | sudo semanage fcontext -a -t mongod_var_lib_t '/dbPath/mongod.*' sudo chcon -Rv -u system_u -t mongod_var_lib_t '/dbPath/mongod' sudo restorecon -R -v '/dbPath/mongod' sudo semanage fcontext -a -t mongod_log_t '/logPath/log.*' sudo chcon -Rv -u system_u -t mongod_log_t '/logPath/log' sudo restorecon -R -v '/logPath/log' |
5. Enable and start mongod service:
1 2 3 4 | sudo systemctl daemon-reload sudo systemctl enable mongod sudo systemctl start mongod sudo systemctl status mongod |
Migrate Replica set MongoDB Enterprise/Community edition to Percona Server for MongoDB (Debian/RHEL):
This migration process involves stopping the Mongo process in the hidden/secondary node first, removing the MongoDB community/enterprise edition packages, installing Percona Server for MongoDB, and starting it with the same data files. Then, step down the current primary node and repeat the same process.
a. Make sure to check the current Primary and Secondary/hidden nodes.
1 | db.isMaster().primary |
b. Start with the hidden node (if there is no hidden node then start with one of the secondary nodes with the least priority) first.
c. Repeat steps from 1 to 5 from the section Migrate standalone MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL).
d. Wait for each node to be synced with Primary. Verify it with
1 | rs.printSecondaryReplicationInfo() |
e. Once completed for all secondary nodes, step down the current primary with
1 | rs.stepDown() |
f. Wait for the new node to be elected as a Primary node and repeat steps 1 to 5 from the section Migrate standalone MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL) and wait for the former primary node to be synced with the newly elected Primary.
Migrate Sharded cluster MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL):
1. Stop the balancer first:
1 | sh.stopBalancer() |
2. Back up the configuration and service files for shards, CSRS, and Query router.
Backup the mongo config and service file for shards and CSRS:
1 | sudo cp /etc/mongod.conf /etc/mongod.conf_bkp |
Debian:
1 | sudo cp /lib/systemd/system/mongod.service /lib/systemd/system/mongod.service_bkp |
For router:
1 2 3 | sudo cp /etc/mongos.conf /etc/mongos.conf_bkp sudo cp /lib/systemd/system/mongos.service /lib/systemd/system/mongos.service_bkp |
RHEL/CentOS:
1 | sudo cp /usr/lib/systemd/system/mongod.service /usr/lib/systemd/system/mongod.service_bkp |
For router:
1 2 | sudo cp /etc/mongos.conf /etc/mongos.conf_bkp sudo cp /usr/lib/systemd/system/mongos.service /usr/lib/systemd/system/mongos.service_backup |
3. Start with the hidden node of the CSRS first (if there is no hidden node then start with one of the secondary nodes).
Repeat steps a to f from the section Migrate Replica set MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL).
Once migrated, the CSRS to Percona Server for MongoDB moves to Shards for the migration. Repeat steps a to f from the section Migrate Replica set MongoDB community/enterprise edition to Percona Server for MongoDB (Debian/RHEL).
4. After the migration of the CSRS and Shards, start migrating the MongoS. Connect to one router at a time and execute the below steps followed by the remaining routers.
5. Stop mongo service and then remove mongodb-community/enterprise packages and repo:
1 | sudo systemctl stop mongos |
Debian:
1 2 | sudo apt-get remove mongodb-org mongodb-org-mongos mongodb-org-server mongodb-org-shell mongodb-org-tools sudo rm /etc/apt/sources.list.d/mongodb-org-4.0.list |
RHEL/CentOS:
1 | sudo yum erase $(rpm -qa | grep mongodb-org) |
6. Configure percona repos and install Percona Server for MongoDB (PSMDB):
Debian:
1 2 | sudo wget https://repo.percona.com/apt/percona-release_latest.$(lsb_release -sc)_all.deb sudo dpkg -i percona-release_latest.$(lsb_release -sc)_all.deb |
Enable the repo:
1 2 | sudo percona-release enable psmdb-44 release sudo apt-get update |
Install the package:
1 | sudo apt-get install percona-server-mongodb |
RHEL/CentOS:
1 | sudo yum install https://repo.percona.com/yum/percona-release-latest.noarch.rpm |
Enable the repo:
1 | sudo percona-release setup pdmdb-44 |
Install the package:
1 | sudo yum install percona-server-mongodb |
Copy back the config and service file:
1 | sudo cp /etc/mongos.conf_bkp /etc/mongos.conf |
Debian:
1 | sudo cp /lib/systemd/system/mongos.service_bkp /lib/systemd/system/mongos.service |
RHEL/CentOS:
1 | sudo cp /usr/lib/systemd/system/mongos.service_bkp /usr/lib/systemd/system/mongos.service |
NOTE: Kindly check that the permissions and ownership of keyfile and log directory are properly updated for the mongod user.
7. Enable and start mongos service:
1 2 3 4 | sudo systemctl daemon-reload sudo systemctl enable mongos sudo systemctl start mongos sudo systemctl status mongos |
8. Re-enable the balancer with below:
1 | sh.startBalancer() |
Conclusion:
To learn more about the enterprise-grade features available in the license-free Percona Server for MongoDB, we recommend going through our blog MongoDB: Why Pay for Enterprise When Open Source Has You Covered?
We also encourage you to try our products for MongoDB like Percona Server for MongoDB, Percona Backup for MongoDB, or Percona Operator for MongoDB.
