Upgrade to MongoDB Enterprise (Sharded Cluster)
Important
MongoDB 8.0 Release Candidates
MongoDB 8.0 binaries are currently available only as release candidates. Release candidates can be used for early testing of new features, but are not suitable for production deployments.
This version of the manual is for an upcoming release and is currently a work in progress.
MongoDB Enterprise provides various features not available in the MongoDB Community edition, such as:
The following steps outline the procedure to upgrade a sharded cluster from the MongoDB Community Edition to the MongoDB Enterprise Edition. For example, the steps can be used to upgrade MongoDB 7.0 Community to MongoDB 7.0 Enterprise.
Consideration
Warning
Do not use these instructions to upgrade to another release version. To upgrade release versions, refer to the appropriate release upgrade instructions, such as Upgrade to MongoDB 8.0.
Download Enterprise Binaries
Depending on your operating system, you can install the MongoDB Enterprise binaries by using a package manager or by downloading the binaries manually.
If you have installed MongoDB Community using a package manager, follow the package manager instructions for your operating system:
During the installation, the package manager will remove the community packages; this will not affect the running deployment until you restart.
If you have not installed MongoDB using a package manager, you can manually download the MongoDB binaries from the MongoDB Download Center. Follow the manual instructions, including specific prerequisites for MongoDB Enterprise, for your operating system:
Important
Install to a location different from that of your current Community edition.
In the upgrade procedure, you will use the existing data directory and, if applicable, the existing configuration file.
Important
You cannot use the .msi to install the Enterprise
edition if you have the Community edition of the same
release series installed on the same machine. That is, if
you have version 4.4.0 Community edition installed, you
cannot use the .msi to install the 4.4.0 or 4.4.1
Enterprise edition.
Manually download the archive file from the MongoDB Download Center.
To install, extract/unzip the file to a location different from that of your current Community edition.
In the upgrade procedure, you will use the existing data directory and, if applicable, the existing configuration file.
Install the binaries:
Manually download the archive file from the MongoDB Download Center.
Extract the files to a location different from that of your current Community edition. For details on extracting the files, see macOS.
In the upgrade procedure, you will use the existing data directory and, if applicable, the existing configuration file.
Before You Begin
Starting in MongoDB 8.0, you can use the
directShardOperations role to perform maintenance operations
that require you to execute commands directly against a shard.
Warning
Running commands using the directShardOperations role can cause
your cluster to stop working correctly and may cause data corruption.
Only use the directShardOperations role for maintenance purposes
or under the guidance of MongoDB support. Once you are done
performing maintenance operations, stop using the
directShardOperations role.
Procedure
To minimize downtime, you can upgrade from MongoDB Community to Enterprise Edition using a "rolling" upgrade by upgrading the members individually while the other members are available.
Disable the Balancer.
Connect mongosh to a mongos instance in
the sharded cluster, and run sh.stopBalancer() to
disable the balancer:
sh.stopBalancer()
Note
If a migration is in progress, the system will complete the
in-progress migration before stopping the balancer. You can run
sh.isBalancerRunning() to check the balancer's current
state.
To verify that the balancer is disabled, run
sh.getBalancerState(), which returns false if the balancer
is disabled:
sh.getBalancerState()
Starting in MongoDB 6.0.3, automatic chunk splitting is not performed. This is because of balancing policy improvements. Auto-splitting commands still exist, but do not perform an operation.
In MongoDB versions earlier than 6.0.3, sh.stopBalancer()
also disables auto-splitting for the sharded cluster.
For more information on disabling the balancer, see Disable the Balancer.
Upgrade the config servers.
Upgrade the secondary members of the replica set one at a time:
Shut down the secondary
mongodinstance.Restart the member with the Enterprise
mongod, specifying the same configuration options (e.g. same data directory, configuration file, etc.).Wait for the member to recover to
SECONDARYstate before upgrading the next secondary member. To check the member's state, issuers.status()inmongosh.
Repeat for each remaining secondary member.
Step down the replica set primary.
Connect
mongoshto the primary and users.stepDown()to step down the primary and force an election of a new primary:rs.stepDown() When
rs.status()shows that the primary has stepped down and another member is primary, upgrade the stepped-down primary:Shut down the stepped-down primary.
Restart with the Enterprise
mongod, specifying the same configuration options (e.g. same data directory, configuration file, etc.).
Upgrade the shards.
Upgrade the shards one at a time.
For each shard replica set:
Upgrade the secondary members of the replica set one at a time:
Shut down the secondary
mongodinstance.Restart the member with the Enterprise
mongod, specifying the same configuration options (e.g. same data directory, configuration file, etc.).Wait for the member to recover to
SECONDARYstate before upgrading the next secondary member. To check the member's state, issuers.status()inmongosh.
Repeat for each remaining secondary member.
Step down the replica set primary.
Connect
mongoshto the primary and users.stepDown()to step down the primary and force an election of a new primary:rs.stepDown() When
rs.status()shows that the primary has stepped down and another member is primary, upgrade the stepped-down primary:Shut down the stepped-down primary.
Restart with the Enterprise
mongod, specifying the same configuration options (e.g. same data directory, configuration file, etc.).
Re-enable the balancer.
Using mongosh, connect to a
mongos in the cluster and run
sh.startBalancer() to re-enable the balancer:
sh.startBalancer()
Starting in MongoDB 6.0.3, automatic chunk splitting is not performed. This is because of balancing policy improvements. Auto-splitting commands still exist, but do not perform an operation.
In MongoDB versions earlier than 6.0.3, sh.startBalancer()
also enables auto-splitting for the sharded cluster.
For more inforamtion on the balancer, see Enable the Balancer.
Important
Before using any Enterprise features, ensure that all members have been upgraded to Enterprise edition.