/ /

mongosh Methods

Databases

Docs Home

Database Manual

Reference

mongosh Methods

Databases

db.shutdownServer() (mongosh method)

This version of the documentation is archived and no longer supported. To upgrade your 6.0 deployment, see the MongoDB 7.0 upgrade procedures.

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
force	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. You can pause and resume in-progress index builds using `force`. See `db.shutdownServer()` on Replica Set Members for more information.
timeoutSecs	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: Attempts to step down to a secondary. If the step down fails and a: `shutdown` or `db.shutdownServer()` command was run, `mongod` only continues the shut down steps if the force field is true, or a `SIGTERM` signal was sent to `mongod`, `mongod` always continues the shut down steps. Enters the quiesce period. Ends any remaining database operations. 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: timeoutSecs field if a `shutdown` or `db.shutdownServer()` command was run, or `shutdownTimeoutMillisForSignaledShutdown` server parameter if a `SIGTERM` signal was sent to `mongod`, or `mongosShutdownTimeoutMillisForSignaledShutdown` server parameter if a `SIGTERM` signal was sent to `mongos`. 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. In MongoDB 4.4 and earlier, for a `mongod` primary, timeoutSecs is the number of seconds the primary should wait for a secondary to catch up. If no secondaries catch up within the specified time, the command fails. Defaults to `10` seconds.

Field

Description

force

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.

You can pause and resume in-progress index builds using force. See db.shutdownServer() on Replica Set Members for more information.

timeoutSecs

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:

Attempts to step down to a secondary.
If the step down fails and a:
- shutdown or db.shutdownServer() command was run, mongod only continues the shut down steps if the force field is true, or a
- SIGTERM signal was sent to mongod, mongod always continues the shut down steps.
Enters the quiesce period.
Ends any remaining database operations.
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:

timeoutSecs field if a shutdown or db.shutdownServer() command was run, or
shutdownTimeoutMillisForSignaledShutdown server parameter if a SIGTERM signal was sent to mongod, or
mongosShutdownTimeoutMillisForSignaledShutdown server parameter if a SIGTERM signal was sent to mongos.

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.

In MongoDB 4.4 and earlier, for a mongod primary, timeoutSecs is the number of seconds the primary should wait for a secondary to catch up. If no secondaries catch up within the specified time, the command fails. Defaults to 10 seconds.

This operation provides a wrapper around the shutdown command.

Compatibility

This method is available in deployments hosted in the following environments:

Important

This command is not supported in MongoDB Atlas clusters. For information on Atlas support for all commands, see Unsupported Commands.

MongoDB Enterprise: The subscription-based, self-managed version of MongoDB
MongoDB Community: The source-available, free-to-use, and self-managed version of MongoDB

Behavior

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

For a mongod started without Authentication on Self-Managed Deployments, 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()` on Replica Set Members

db.shutdownServer() fails if the mongod replica set member is running certain operations such as index builds. You can specify force: true to save index build progress to disk. The mongod recovers the index build when it restarts and continues from the saved checkpoint.

Shutting Down the Replica Set Primary, Secondary, or `mongos`

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:

Attempts to step down to a secondary.
If the step down fails and a:
- shutdown or db.shutdownServer() command was run, mongod only continues the shut down steps if the force field is true, or a
- SIGTERM signal was sent to mongod, mongod always continues the shut down steps.
Enters the quiesce period.
Ends any remaining database operations.
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:

timeoutSecs field if a shutdown or db.shutdownServer() command was run, or
shutdownTimeoutMillisForSignaledShutdown server parameter if a SIGTERM signal was sent to mongod, or
mongosShutdownTimeoutMillisForSignaledShutdown server parameter if a SIGTERM signal was sent to mongos.

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.

Warning

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

Access Control

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

Examples

Shut down a `mongod`

db.getSiblingDB("admin").shutdownServer()

Force Shut Down a `mongod`

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

Shut Down a Primary `mongod` With Longer Timeout

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

Back

db.setProfilingLevel

db.stats

Compatibility

Important

Behavior

db.shutdownServer() on Replica Set Members

Shutting Down the Replica Set Primary, Secondary, or mongos