Skip to content

DOCS-3890: Improve movePrimary documentation #1982

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 3 additions & 7 deletions source/core/sharded-cluster-shards.txt
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,9 @@ holds all the un-sharded collections in that database.
.. include:: /images/sharded-cluster-primary-shard.rst

To change the primary shard for a database, use the
:dbcommand:`movePrimary` command.

.. warning::

The :dbcommand:`movePrimary` command can be expensive because it
copies all non-sharded data to the new shard. During this time,
this data will be unavailable for other operations.
:dbcommand:`movePrimary` command. The process of migrating the primary shard
may take significant time to complete, and you should not access the
collections until it completes.

When you deploy a new :term:`sharded cluster` with shards that were
previously used as replica sets, all existing databases
Expand Down
40 changes: 21 additions & 19 deletions source/reference/command/movePrimary.txt
Original file line number Diff line number Diff line change
Expand Up @@ -6,38 +6,40 @@ movePrimary

.. dbcommand:: movePrimary

In a :term:`sharded cluster`, this command reassigns the database's
:term:`primary shard`, which holds all un-sharded collections in
the database. :dbcommand:`movePrimary` is an administrative command
that is only available for :program:`mongos` instances. Only use
:dbcommand:`movePrimary` when removing a shard from a sharded
cluster.

:dbcommand:`movePrimary` changes the primary shard for a
database in the cluster metadata, and migrates all un-sharded
collections to the specified shard. Use the command with the
following form:
In a :term:`sharded cluster`, :dbcommand:`movePrimary` reassigns the
:term:`primary shard` which holds all un-sharded collections in
the database. :dbcommand:`movePrimary` first changes the primary shard in
the cluster metadata, and then migrates all un-sharded collections to the
specified :term:`shard`. Use the command with the following form:

.. code-block:: javascript

{ movePrimary : "test", to : "shard0001" }

When the command returns, the database's primary location will
shift to the designated :term:`shard`. To fully decommission a
shift to the designated shard. To fully decommission a
shard, use the :dbcommand:`removeShard` command.

:dbcommand:`movePrimary` is an administrative command that is only available
for :program:`mongos` instances.

Considerations
--------------

Limitations
~~~~~~~~~~~
Behavior
~~~~~~~~

Only use :dbcommand:`movePrimary` when:
Avoid accessing an un-sharded collection during migration.
:dbcommand:`movePrimary` does not prevent reading and writing during its
operation, and such actions yield undefined behavior.

- the database does not contain any collections, *or*
:dbcommand:`movePrimary` may take significant time to complete, and
you should plan for this unavailability.

- you have drained all sharded collections using the
:dbcommand:`removeShard` command.
:dbcommand:`movePrimary` will fail if the destination shard contains a
conflicting collection name. This may occur if documents are written to an
un-sharded collection while the collection is moved away, and later the original
primary shard is restored.

Use
~~~
Expand All @@ -51,7 +53,7 @@ for the database.

If you do not update the :program:`mongos` instances' metadata cache
after using :dbcommand:`movePrimary`, the :program:`mongos` may not
write data to the correct shard, to recover you must manually
write data to the correct shard. To recover, you must manually
intervene.

Additional Information
Expand Down