Upgrade to MongoDB Enterprise (Sharded Cluster)

MongoDB Enterprise provides various features not available in theMongoDB Community edition, such as:

The following steps outline the procedure to upgrade a sharded clusterfrom the MongoDB Community Edition to the MongoDB Enterprise Edition.For example, the steps can be used to MongoDB 4.0 Community to MongoDB4.0 Enterprise.

Consideration

Warning

Do not use these instructions to upgrade to another release version.To upgrade release versions, refer to the appropriate releaseupgrade instructions, such as Upgrade to MongoDB 4.2.

Download Enterprise Binaries

Depending on your operating system, you can install the MongoDBEnterprise binaries by using a package manager or by downloading thebinaries manually.

  • Linux (Package Manager)
  • Linux (Manual Download)
  • Windows
  • macOS

If you have installed MongoDB Community using a packagemanager, follow the package manager instructions for youroperating system:

During the installation, the package manager will remove thecommunity packages; this will not affect the runningdeployment until you restart.

If you have not installed MongoDB using a package manager,you can manually download the MongoDB binaries from theMongoDB Download Center. Followthe manual instructions, including specific prerequisitesfor MongoDB Enterprise, for your operating system:

Important

Install to a location different from that of your currentCommunity edition.

In the upgrade procedure, you will use the existing datadirectory and, if applicable, the existing configurationfile.

Important

You cannot use the .msi to install the Enterpriseedition if you have the Community edition of the samerelease series installed on the same machine. That is, ifyou have version 4.0.0 Community edition installed, youcannot use the .msi to install the 4.0.0 or 4.0.1Enterprise edition.

To install, extract/unzip the file to a locationdifferent from that of your current Communityedition.

In the upgrade procedure, you will use the existingdata directory and, if applicable, the existingconfiguration file.

Install the binaries:

Extract the files to a location differentfrom that of your current Community edition. Fordetails on extracting the files, see macOS.

In the upgrade procedure, you will use the existingdata directory and, if applicable, the existingconfiguration file.

Procedure

To minimize downtime, you can upgrade from MongoDB Community toEnterprise Edition using a “rolling” upgrade by upgrading the membersindividually while the other members are available.

Disable the Balancer.

Connect a mongo shell to a mongos instance inthe sharded cluster, and run sh.stopBalancer() todisable the balancer:

  1. sh.stopBalancer()

Note

If a migration is in progress, the system will complete thein-progress migration before stopping the balancer. You can runsh.isBalancerRunning() to check the balancer’s currentstate.

To verify that the balancer is disabled, runsh.getBalancerState(), which returns false if the balanceris disabled:

  1. sh.getBalancerState()

Starting in MongoDB 4.2, sh.stopBalancer() also disablesauto-splitting for the sharded cluster.

For more information on disabling the balancer, seeDisable the Balancer.

Upgrade the config servers.

  • Upgrade the secondarymembers of the replica set one at a time:

    • Shut down the secondary mongod instance.
    • Restart the member with the Enterprise mongod,specifying the same configuration options (e.g. samedata directory, configuration file, etc.).
    • Wait for the member to recover to SECONDARY state beforeupgrading the next secondary member. To check the member’s state,issue rs.status() in the mongo shell.Repeat for each remaining secondary member.

  • Step down the replica set primary.

Connect a mongo shell to the primary and users.stepDown() to step down the primary and force anelection of a new primary:

  1. rs.stepDown()

  • When rs.status() shows that the primary has steppeddown and another member is primary, upgrade the stepped-downprimary:

    • Shut down the stepped-down primary.
    • Restart with the Enterprise mongod,specifying the same configuration options (e.g. samedata directory, configuration file, etc.).

Upgrade the shards.

Upgrade the shards one at a time.

For each shard replica set:

  • Upgrade the secondarymembers of the replica set one at a time:

    • Shut down the secondary mongod instance.
    • Restart the member with the Enterprise mongod,specifying the same configuration options (e.g. samedata directory, configuration file, etc.).
    • Wait for the member to recover to SECONDARY state beforeupgrading the next secondary member. To check the member’s state,issue rs.status() in the mongo shell.Repeat for each remaining secondary member.

  • Step down the replica set primary.

Connect a mongo shell to the primary and users.stepDown() to step down the primary and force anelection of a new primary:

  1. rs.stepDown()

  • When rs.status() shows that the primary has steppeddown and another member is primary, upgrade the stepped-downprimary:

    • Shut down the stepped-down primary.
    • Restart with the Enterprise mongod,specifying the same configuration options (e.g. samedata directory, configuration file, etc.).

Upgrade the mongos instances.

For each mongos instance, shutdownmongos and restart with the Enterprise mongos,specifying the same configuration options.

Re-enable the balancer.

Using a mongo shell, connect to amongos in the cluster and runsh.startBalancer() to re-enable the balancer:

  1. sh.startBalancer()

Starting in MongoDB 4.2, sh.startBalancer() also enablesauto-splitting for the sharded cluster.

For more inforamtion on the balancer, seeEnable the Balancer.

Important

Before using any Enterprise features, ensure that all members havebeen upgraded to Enterprise edition.