db.shutdownServer()
On this page
Changed in version 5.0.
db.shutdownServer()
Shuts down the current
mongod
ormongos
process cleanly and safely. You must issue thedb.shutdownServer()
operation against the admin database.db.shutdownServer()
has this syntax:db.shutdownServer({ force: <boolean>, timeoutSecs: <int> }) The method takes these fields:
FieldDescriptionOptional. Specify
true
to force themongod
ormongos
to shut down. Force shutdown interrupts any ongoing operations on themongod
ormongos
and may result in unexpected behavior.You can pause and resume in-progress index builds using
force
. Seedb.shutdownServer()
on Replica Set Members for more information.Optional.
Starting in MongoDB 5.0,
mongod
andmongos
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:
Enters the quiesce period.
Ends any remaining database operations.
Shuts down.
For a
mongod
secondary ormongos
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
ordb.shutdownServer()
command was run, orshutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongod
, ormongosShutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongos
.
Clients cannot open new connections to a
mongod
ormongos
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 othermongos
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 to10
seconds.
This operation provides a wrapper around the shutdown
command.
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:
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
ordb.shutdownServer()
command was run, orshutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongod
, ormongosShutdownTimeoutMillisForSignaledShutdown
server parameter if aSIGTERM
signal was sent tomongos
.
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.
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 })