Skip to content
Permalink
Branch: master
Find file Copy path
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
293 lines (228 sloc) 7.72 KB
=============
rs.reconfig()
=============
.. default-domain:: mongodb
.. contents:: On this page
:local:
:backlinks: none
:depth: 1
:class: singlecol
Definition
----------
.. method:: rs.reconfig(configuration, force)
Reconfigures an existing replica set, overwriting the existing
replica set configuration. To run the method, you must connect to
the :term:`primary` of the replica set.
.. include:: /includes/apiargs/method-rs.reconfig-param.rst
To reconfigure an existing replica set, first retrieve the
current configuration with :method:`rs.conf()`, modify the
configuration document as needed, and then pass the modified
document to :method:`rs.reconfig()`.
:method:`rs.reconfig()` provides a wrapper around the
:dbcommand:`replSetReconfig` command.
The ``force`` parameter allows a reconfiguration command to be issued
to a non-primary node.
Consideration
-------------
Mixed Version Replica Set
~~~~~~~~~~~~~~~~~~~~~~~~~
.. warning::
.. include:: /includes/warning-mixed-version-rs-config.rst
Availability
~~~~~~~~~~~~
The :method:`rs.reconfig()` shell method can trigger the current primary
to step down in some situations. When the primary steps down, it
forcibly closes all client connections. Primary step-down triggers an
:ref:`election <replica-set-elections>` to select a new :term:`primary`.
.. include:: /includes/fact-election-latency.rst
During the election process, the cluster cannot
accept write operations until it elects the new primary.
.. include:: /includes/fact-retryable-writes-failover-election.rst
To further reduce potential impact to a production cluster,
reconfigure only during scheduled maintenance periods.
``{ force: true }``
~~~~~~~~~~~~~~~~~~~
.. warning::
Using :method:`rs.reconfig()` with ``{ force: true }`` can lead to
:term:`rollback` of majority-committed writes. Exercise caution when
using this option.
Member Priority and Votes
~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionchanged:: 3.2
- .. include:: /includes/fact-rs-nonzero-priority-vote-restriction.rst
- .. include:: /includes/fact-rs-non-voting-priority-restriction.rst
Drop Outgoing Connections After Removing a Member
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
..
This behavior will change once SERVER-36417 closes.
Using :method:`rs.reconfig()` to remove a replica set member does not
automatically drop open outgoing connections from other replica set
members to the removed member.
By default, replica set members wait for 5 minutes before dropping
connections to the removed member. In sharded replica sets, you can
modify this timeout using the
:parameter:`ShardingTaskExecutorPoolHostTimeoutMS` server parameter.
.. versionadded:: 4.2
To immediately drop all outgoing connections from the replica set to
the removed member, run the :dbcommand:`dropConnections`
administrative command on each remaining member on the replica set:
.. code-block:: javascript
db.adminCommand(
{
"dropConnections" : 1,
"hostAndPort" : [
"<hostname>:<port>"
]
}
)
Replace ``<hostname>`` and ``<port>`` with those of the removed
member.
.. _replica-set-reconfiguration-usage:
Examples
--------
A replica set named ``rs0`` has the following configuration:
.. code-block:: javascript
{
"_id" : "rs0",
"version" : 1,
"protocolVersion" : NumberLong(1),
"members" : [
{
"_id" : 0,
"host" : "mongodb0.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 1,
"host" : "mongodb1.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 2,
"host" : "mongodb2.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
}
],
"settings" : {
"chainingAllowed" : true,
"heartbeatIntervalMillis" : 2000,
"heartbeatTimeoutSecs" : 10,
"electionTimeoutMillis" : 10000,
"catchUpTimeoutMillis" : 2000,
"getLastErrorModes" : {
},
"getLastErrorDefaults" : {
"w" : 1,
"wtimeout" : 0
},
"replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
}
}
The following sequence of operations updates the
:rsconf:`members[n].priority` of the second member.
The operations are issued through a :binary:`~bin.mongo` shell connected to
the primary.
.. code-block:: javascript
cfg = rs.conf();
cfg.members[1].priority = 2;
rs.reconfig(cfg);
#. The first statement uses the :method:`rs.conf()` method to retrieve
a document containing the current :ref:`configuration
<replSetGetConfig-output>` for the replica set and sets the
document to the local variable ``cfg``.
#. The second statement sets a
:rsconf:`members[n].priority` value to the
second document in the :rsconf:`members` array.
For additional settings, see :ref:`replica set configuration settings
<replSetGetConfig-output>`.
To access the member configuration document in the array, the
statement uses the array index and **not** the replica set member's
:rsconf:`members[n]._id` field.
#. The last statement calls the :method:`rs.reconfig()` method with the
modified ``cfg`` to initialize this new configuration. Upon
successful reconfiguration, the replica set configuration will
resemble the following:
.. code-block:: javascript
{
"_id" : "rs0",
"version" : 2,
"protocolVersion" : NumberLong(1),
"members" : [
{
"_id" : 0,
"host" : "mongodb0.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 1,
"host" : "mongodb1.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 2,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
},
{
"_id" : 2,
"host" : "mongodb2.example.net:27017",
"arbiterOnly" : false,
"buildIndexes" : true,
"hidden" : false,
"priority" : 1,
"tags" : {
},
"slaveDelay" : NumberLong(0),
"votes" : 1
}
],
"settings" : {
"chainingAllowed" : true,
"heartbeatIntervalMillis" : 2000,
"heartbeatTimeoutSecs" : 10,
"electionTimeoutMillis" : 10000,
"catchUpTimeoutMillis" : 2000,
"getLastErrorModes" : {
},
"getLastErrorDefaults" : {
"w" : 1,
"wtimeout" : 0
},
"replicaSetId" : ObjectId("58858acc1f5609ed986b641b")
}
}
.. seealso::
- :method:`rs.conf()`
- :ref:`replSetGetConfig-output`
- :doc:`/administration/replica-set-member-configuration`
- :doc:`/administration/replica-set-maintenance`
You can’t perform that action at this time.