Upgrading to Replica Sets

Upgrading From a Single Server

If you're running MongoDB on a single server, upgrading to replica sets is trivial (and a good idea!). First, we'll initiate a new replica set with a single node. We need a name for the replica set - in this case we're using foo. Start by shutting down the server and restarting with the --replSet option, and our set name:

$ ./mongod --replSet foo

Add the --rest option too (just be sure that port is secured): the <host>:28017/_replSet diagnostics page is incredibly useful.

The server will allocate new local data files before starting back up. Consider pre-allocating those files if you need to minimize downtime.

Next we'll connect to the server from the shell and initiate the replica set:

$ ./mongo
MongoDB shell version: ...
connecting to: test
> rs.initiate();
{
    "info2" : "no configuration explicitly specified -- making one",
    "info" : "Config now saved locally.  Should come online in about a minute.",
    "ok" : 1
}

The server should now be operational again, this time as the primary in a replica set consisting of just a single node. The next step is to add some additional nodes to the set.

Upgrading From Replica Pairs or Master/Slave

The best way to upgrade is to simply restart the current master as a single server replica set, and then add any slaves after wiping their data directory. To find the master in a replica pair, run db.isMaster().

s> db.isMaster() 
{
        "ismaster" : 0,
        "remote" : "localhost:27018",
        "info" : "direct negotiation",
        "maxBsonObjectSize" : 16777216,
        "ok" : 1
}

Once you know the master, shut down the mongod processes on the master and slave.

m$ killall mongod
s$ killall mongod

Backup your /data/db directories, just in case.

m$ cp /data/db/* /to_somewhere_backup/
s$ cp /data/db/* /to_slave_backup/

Now, start up the master with the --replSet option, and initialize a one-member replica set.

m$ mongod --rest --replSet mysetname
m$ mongo
m> rs.initiate()

Now there are two paths we can take: either resyncing the slaves from scratch or using their existing data. Resyncing takes longer. Using the existing data is only possible if the slave was up-to-date before the replica pair was shut down and you add it to the replica set before the master has handled "too many" new writes (the size of the oplog determines what "too many" is).

Resyncing the Slaves

To resync, clear the data directory:

s$ rm -r /data/db/* # if you're using a non-default dbpath, this may be somewhere else
s$ # /data/db is now empty

Then start up the slave with the --replSet option.

s$ mongod --rest --replSet mysetname

In the database shell, add the slave as a new member in the replica set.

m> // still in the mongo shell on the master
m> rs.add("s") // "s" is your slave host name
m> rs.status(); // see also http://localhost:28017/_replSet

Adding An Arbiter

If there are an even number of replica set members, we should add an arbiter to break ties on elections and know who is up in a network partition. An arbiter is very lightweight and can run on virtually any server (including 32 bit servers). We use different directories and ports here so that the server is still available as a "normal" mongod server if that is desired and also to avoid confusion. The /data/arb directory will be very small in content size.

arb$ mkdir /data/arb
arb$ mongod --rest --replSet mysetname --dbpath /data/arb --port 30000

Then add the arbiter to your replica set:

m> rs.addArb("arb:30000"); // replace 'arb' with your arb host name
m> rs.status()

Upgrading Drivers

There are new versions of most MongoDB Drivers which support replica sets elegantly. See the documentation pages for the specific driver of interest.