Sharded Cluster Offline: Individual Shards

This guide explains how to do an offline data migration from basic MongoDB to Percona TokuMX, for a sharded cluster, converting the existing data in MongoDB to Percona TokuMX on a shard-by-shard basis.

For other migration strategies, start with Migrating to TokuMX. Instructions

  1. Shut down MongoDB

    Shut down the existing MongoDB servers on each machine in the sharded cluster (shards, config servers, and routers) to make sure you get a consistent backup.

  2. Migrate shards individually

    Migrate each shard to Percona TokuMX offline, following the guide Replica Set Offline (with downtime). You can do this for each shard concurrently.

  3. Back up a config server

    Back up one of the MongoDB config servers with mongodump.

    You will need the dbpath from /etc/mongodb.conf (this is often /var/lib/mongodb) and you will need to choose a location for the backup (here, /var/lib/configdb.backup).

    One config server only:

    $ sudo mongodump --dbpath /var/lib/mongodb --out /var/lib/configdb.backup
  4. Uninstall MongoDB from config servers

    Uninstall MongoDB from the config servers. You can also remove the old dbpath since you have a backup.

  5. Install Percona TokuMX on config servers

    Install Percona TokuMX from tarballs or from packages on the config servers and make sure it starts properly.

    Take a moment to transfer any important configuration from your basic MongoDB configuration file (usually /etc/mongodb.conf) to your Percona TokuMX configuration file (usually /etc/tokumx.conf). If you do this, be sure to restart the config servers.

  6. Import your backup of the config servers

    Import the backup to each config server with mongorestore.


    If you are running with the configsvr option, remember that this makes the port 27019 instead of the default.

    On the machine with the backup:

    $ mongorestore --host localhost:27019 /var/lib/configdb.backup
    $ mongorestore --host cfg2.domain:27019 /var/lib/configdb.backup
    $ mongorestore --host cfg3.domain:27019 /var/lib/configdb.backup
  7. Configure routers

    Copy any relevant configuration from /etc/mongodb.conf to /etc/tokumx.conf on all mongos router machines.


    If your config servers have different hostnames now, you will need to update the configdb settings for all your mongos configurations. See Migrate Config Servers with Different Hostnames for more details.

    If your shard servers have different hostnames now, you will need to update their hostnames in the config servers’ databases. Connect to the config servers and update the shards’ metadata.

    On config servers:

    Connect to the config servers with a connection string similar to what’s used for the mongos --configdb option:

    $ mongo localhost:27019,cfg2.domain:27019,cfg3.domain:27019/config

    Update the metadata:

    > db.shards.update({_id: <shard name>},
         {$set: {host: "<replset name>/<hostnames>"}})
  8. Start Percona TokuMX routers

    Start the Percona TokuMX mongos server on all router machines, and start your application.