How to convert your localhost standalone MongoDB cluster into a replica set using run-rs npm package on Mac OS

In my journey to learn more about MongoDB, also as I'm working on a project involving transactions, I need to ensure that all the operations done within a transaction should either happen all together or fail all together, to ensure database consistency.

Starting from MongoDB v4.4 and above, it's possible to work with transactions, but before that, a MongoDB replica set is required (in short: replica sets are backup copies of your primary MongoDB cluster you are doing transactions on. In case of a mid transaction failure, these copies can be used to restore the previous state of the primary MongoDB cluster).

I was looking for tutorials on how to set up a MongoDB replica set on localhost, but couldn't find anything relevant, this is why I'w writing this blogpost to try and save you days of researches.

Prerequisites

On my Mac OS I have these packages versions installed:

➜  ~ node --version
v16.14.2

➜  ~ npm --version
8.5.0

➜  ~ brew --version
Homebrew 3.4.3

➜  ~ mongo --version
MongoDB shell version v5.0.6

# Npm globally installed packages
➜  ~ npm list -g
/usr/local/lib
├── npm@8.5.0
├── run-rs@0.7.6
└── ...

NOTE:

• To see the changes of the conversion, you should have the MongoDB Compass installed (MongoDB Compass is the MongoDB UI).
• Installing MongoDB is done via the command line and it is required to have brew installed.
• Installing run-rs is done with npm i -g run-rs.

The basic installation of MongoDB on localhost is a standalone cluster, so in MongoDB Compass, when you connect to your localhost MongoDB cluster, in the left panel you will see Standalone under CLUSTER.

Steps to convert your standalone MongoDB cluster into a replica set

1. Stop MongoDB service : brew services stop mongodb-community (check that the service is stopped with brew services list).
2. In a separate terminal, run sudo run-rs --mongod (--mongod flag means to use the already installed MongoDB version instead of creating a brand new MongoDB installation).
3. Open MongoDB Compass and connect to your localhost cluster (it should connect even though the mongodb-community service is stopped).
4. in the left panel of MongoDB Compass, you should see Secondary or Primary under CLUSTER.

Congrats: you have successfully set up a replica set, and can now work with transactions.

NOTE:

• Remember when switching back to a standalone MongoDB cluster , all the data saved in the replica set will be lost, so you should have some scripts ready to populate your MongoDB replica set with a database, collections and documents.

Reconvert back a MongoDB replica set cluster into a standalone one

• Stop the terminal running run-rs command.
• (in this state, aka: the run-rs is shut down, and the mongodb-community service is also shutdown, if you take a look at MongoDB Compass, you will see in the left panel Unknown under CLUSTER. If you have closed MongoDB Compass, open it again and try to connect to your localhost cluster, it won't work and you will get a connection error connect ECONNREFUSED 127.0.0.1:27017).
• Start again the MongoDB service : brew services start mongodb-community.
• Go to your MongoDB Compass and connect to your localhost cluster, you will notice in the left panel Standalone under CLUSTER.

Congrats: you switched back to standalone MongoDB cluster.

NOTE:

• The data saved in the standalone MongoDB cluster won't be lost if you switch back and forth to a replica set.

I hope these steps will help you set up a MongoDB replicat set on your localhost machine. Note that if you have created your cluster on the cloud (aka on MongoDB Atlass), the created cluster is automatically set up as replica set and ready to compute transactions.

To be honest, I'm not sure if these steps can be used on Windows or Linux OS, you need to give it a try.

And finally, I'm open to any suggestions in order to improve this article, leave them in the comment section.