Docs Menu
Docs Home
/
MongoDB Manual
/ / /

db.shutdownServer()

On this page

  • Behavior
  • Access Control
  • Examples

Changed in version 5.0.

db.shutdownServer()

Shuts down the current mongod or mongos process cleanly and safely. You must issue the db.shutdownServer() operation against the admin database.

db.shutdownServer() has this syntax:

db.shutdownServer({
force: <boolean>,
timeoutSecs: <int>
})

The method takes these fields:

Field
Description

Optional. Specify true to force the mongod or mongos to shut down. Force shutdown interrupts any ongoing operations on the mongod or mongos and may result in unexpected behavior.

Optional.

Starting in MongoDB 5.0, mongod and mongos enter a quiesce period to allow any ongoing database operations to complete before shutting down.

If a mongod primary receives a shut down request, the primary:

  1. Attempts to step down to a secondary.

    If the step down fails and a:

  2. Enters the quiesce period.

  3. Ends any remaining database operations.

  4. Shuts down.

For a mongod secondary or mongos shut down request, the quiesce period is entered after a shut down was requested.

The quiesce period is specified by the:

Clients cannot open new connections to a mongod or mongos that is shutting down.

timeoutSecs specifies a time period in seconds. The default is:

  • 15 seconds starting in MongoDB 5.0.

  • 10 seconds in MongoDB versions earlier than 5.0.

mongod uses timeoutSecs as follows:

  • If the current node is the primary node of a replica set, mongod waits for a period of up to the number of seconds specified by the timeoutSecs field for an electable node to catch up before stepping down the primary node. For details about the catch up time, see replication lag.

  • If the current node is in the SECONDARY state after stepping down from being the primary, any remaining time specified in timeoutSecs is used for a quiesce period, which allows existing operations to complete. New operations are sent to other replica set nodes.

Starting in MongoDB 5.0, mongos uses timeoutSecs as a quiesce period, which allows existing operations to complete. New operations are sent to other mongos nodes. In MongoDB versions earlier than 5.0, mongos shuts down immediately and does not use timeoutSecs.

For a mongod primary in MongoDB 4.4 and earlier, timeoutSecs specifies the time in seconds that the primary waits for a secondary to catch up for the shutdownServer command. If no secondaries catch up within timeoutSecs, the shutdownServer command fails.

This operation provides a wrapper around the shutdown command.

For a mongod started with Authentication, you must run db.shutdownServer() over an authenticated connection. See Access Control for more information.

For a mongod started without Authentication, you must run db.shutdownServer() from a client connected to the localhost interface. For example, run mongosh with the --host "127.0.0.1" option on the same host machine as the mongod.

db.shutdownServer() fails if the mongod replica set member is running certain operations such as index builds. You can specify force: true to force the member to interrupt those operations and shut down.

Starting in MongoDB 5.0, mongod and mongos enter a quiesce period to allow any ongoing database operations to complete before shutting down.

If a mongod primary receives a shut down request, the primary:

  1. Attempts to step down to a secondary.

    If the step down fails and a:

  2. Enters the quiesce period.

  3. Ends any remaining database operations.

  4. Shuts down.

For a mongod secondary or mongos shut down request, the quiesce period is entered after a shut down was requested.

The quiesce period is specified by the:

Clients cannot open new connections to a mongod or mongos that is shutting down.

timeoutSecs specifies a time period in seconds. The default is:

  • 15 seconds starting in MongoDB 5.0.

  • 10 seconds in MongoDB versions earlier than 5.0.

mongod uses timeoutSecs as follows:

  • If the current node is the primary node of a replica set, mongod waits for a period of up to the number of seconds specified by the timeoutSecs field for an electable node to catch up before stepping down the primary node. For details about the catch up time, see replication lag.

  • If the current node is in the SECONDARY state after stepping down from being the primary, any remaining time specified in timeoutSecs is used for a quiesce period, which allows existing operations to complete. New operations are sent to other replica set nodes.

Starting in MongoDB 5.0, mongos uses timeoutSecs as a quiesce period, which allows existing operations to complete. New operations are sent to other mongos nodes. In MongoDB versions earlier than 5.0, mongos shuts down immediately and does not use timeoutSecs.

For a mongod primary in MongoDB 4.4 and earlier, timeoutSecs specifies the time in seconds that the primary waits for a secondary to catch up for the shutdownServer command. If no secondaries catch up within timeoutSecs, the shutdownServer command fails.

In MongoDB 4.4 and earlier, if running db.shutdownServer() against the replica set primary, the operation implicitly uses replSetStepDown to step down the primary before shutting down the mongod. If no secondary in the replica set can catch up to the primary within 10 seconds, the shutdown operation fails. You can issue db.shutdownServer() with force: true to shut down the primary even if the step down fails.

Warning

Force shutdown of the primary can result in the rollback of any writes not yet replicated to a secondary.

To run db.shutdownServer() on a mongod enforcing Authentication, the authenticated user must have the db.shutdownServer() privilege. For example, a user with the built-in role hostManager has the appropriate permissions.

db.getSiblingDB("admin").shutdownServer()
db.getSiblingDB("admin").shutdownServer({ "force" : true })
db.getSiblingDB("admin").shutdownServer({ "timeoutSecs": 60 })

Back

db.setProfilingLevel()