Skip to content

clarify removeShard behaviour when shard is db's primary shard #2958

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.

Sign up for GitHub

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

clarify removeShard behaviour when shard is db's primary shard #2958

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
69 changes: 46 additions & 23 deletions source/reference/command/removeShard.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,43 +66,66 @@ operation resembles the following:

Replace ``bristol01`` with the name of the shard to remove. When you
run :dbcommand:`removeShard`, the command returns immediately,
with the following message:
with a message that resembles the following:

.. code-block:: javascript

{
"msg" : "draining started successfully",
"state" : "started",
"shard" : "bristol01",
"ok" : 1
"msg" : "draining started successfully",
"state" : "started",
"shard" : "bristol01",
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fizz",
"buzz"
],
"ok" : 1
}

The balancer begins migrating chunks from the shard named
``bristol01`` to other shards in the cluster. These migrations happens
slowly to avoid placing undue load on the overall cluster.
The balancer begins migrating chunks from the shard named ``bristol01``
to other shards in the cluster. These migrations happen slowly in order to
avoid placing undue load on the cluster. Since ``bristol01`` is
the primary shard for the ``fizz`` and ``buzz`` databases,
:dbcommand:`removeShard` notes that you must use the
:dbcommand:`movePrimary` command to move those
databases to another shard. Alternatively, you can use :dbcommand:`dropDatabase`
to drop the database and delete its associated data files.

.. note::
If the shard you are removing is not the primary shard for any
databases, the ``dbsToMove`` array will be empty and
:dbcommand:`removeShard` can complete the migration without
intervention.

If you run the command again, :dbcommand:`removeShard` returns the
following progress output:
If you run the command again, :dbcommand:`removeShard` returns output
that resembles the following:

.. code-block:: javascript

{
"msg" : "draining ongoing",
"state" : "ongoing",
"remaining" : {
"chunks" : 23,
"dbs" : 1
},
"ok" : 1
"msg" : "draining ongoing",
"state" : "ongoing",
"remaining" : {
"chunks" : NumberLong(2),
"dbs" : NumberLong(2)
},
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fizz",
"buzz"
],
"ok" : 1
}

The ``remaining`` :term:`document` specifies how many chunks and databases
remain on the shard. Use :method:`db.printShardingStatus()` to list the
databases that you must move from the shard. Use the
:dbcommand:`movePrimary` to move databases.

After removing all chunks and databases from the shard, you can issue
:dbcommand:`removeShard` again see the following:
remain on the shard. Use the :dbcommand:`movePrimary` command to move
each database listed in ``dbsToMove`` to another shard.
Alternatively, use :dbcommand:`dropDatabase` to drop the database.

When the balancer completes moving all chunks off of the shard and
you have either moved or dropped any database listed in ``dbsToMove``,
running :dbcommand:`removeShard` again returns output that
resembles the following:

.. code-block:: javascript

Expand Down
102 changes: 54 additions & 48 deletions source/tutorial/remove-shards-from-cluster.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -79,15 +79,32 @@ This operation returns immediately, with the following response:
.. code-block:: javascript

{
"msg" : "draining started successfully",
"state" : "started",
"shard" : "mongodb0",
"ok" : 1
"msg" : "draining started successfully",
"state" : "started",
"shard" : "mongodb0",
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fiz",
"buzz"
],
"ok" : 1
}

The balancer begins migrating chunks from the shard named ``bristol01``
to other shards in the cluster. These migrations happens slowly to
avoid placing undue load on the overall cluster.
Depending on your network capacity and the amount of data, this
operation can take from a few minutes to several days to complete.

.. note::

Each database in a sharded cluster has a primary shard. If the shard you
want to remove is also the primary of one of the cluster's databases,
:dbcommand:`removeShard` lists the database in the ``dbsToMove`` field.
To finish removing the shard, you must either move the database
to a new shard after migrating all data from the shard or drop the
database, deleting the associated data files.

.. _remove-shard-check-migration-status:

Check the Status of the Migration
Expand All @@ -107,13 +124,18 @@ The command returns output similar to the following:
.. code-block:: javascript

{
"msg" : "draining ongoing",
"state" : "ongoing",
"remaining" : {
"chunks" : 42,
"dbs" : 1
},
"ok" : 1
"msg" : "draining ongoing",
"state" : "ongoing",
"remaining" : {
"chunks" : NumberLong(2),
"dbs" : NumberLong(2)
},
"note" : "you need to drop or movePrimary these databases",
"dbsToMove" : [
"fizz",
"buzz"
],
"ok" : 1
}

In the output, the ``remaining`` document displays the remaining number
Expand All @@ -127,62 +149,46 @@ use :method:`sh._adminCommand` to run the command on ``admin``.

.. _remove-shard-move-unsharded-databases:

Move Unsharded Data
-------------------
Move Databases to Another Primary Shard
---------------------------------------

If the shard is the :term:`primary shard` for one or more databases in
the cluster, then the shard will have unsharded data. If the shard is
the cluster, then you must make that database use a different shard
as its primary shard. :dbcommand:`removeShard` lists any databases
that you need to move in the ``dbsToMove`` field in the command output.
If the shard is
not the primary shard for any databases, skip to the next task,
:ref:`remove-shard-finalize-migration`.

In a cluster, a database with unsharded collections stores those
collections only on a single shard. That shard becomes the primary shard
for that database. (Different databases in a cluster can have different
primary shards.)

.. warning::

Do not perform this procedure until you have finished draining the
shard.

1. To determine if the shard you are removing is the primary shard for
any of the cluster's databases, issue one of the following methods:

- :method:`sh.status()`
To move a database to another shard, use the :dbcommand:`movePrimary`
command.

- :method:`db.printShardingStatus()`
.. important::

In the resulting document, the ``databases`` field lists each
database and its primary shard. For example, the following
``database`` field shows that the ``products`` database uses
``mongodb0`` as the primary shard:
To ensure a smooth migration, refer to the considerations in the
:dbcommand:`movePrimary` command documentation before running
:dbcommand:`movePrimary`.

.. code-block:: javascript
To migrate the ``fizz`` database from
``mongodb0`` to ``mongodb1``, issue the following command:

{ "_id" : "products", "partitioned" : true, "primary" : "mongodb0" }

#. To move a database to another shard, use the :dbcommand:`movePrimary`
command. For example, to migrate all remaining unsharded data from
``mongodb0`` to ``mongodb1``, issue the following command:

.. code-block:: javascript
.. code-block:: javascript

db.runCommand( { movePrimary: "products", to: "mongodb1" })
db.runCommand( { movePrimary: "fizz", to: "mongodb1" })

This command does not return until MongoDB completes moving all data,
which may take a long time. The response from this command will
resemble the following:
This command does not return until MongoDB completes moving all data.
The response from this command will
resemble the following:

.. code-block:: javascript
.. code-block:: javascript

{ "primary" : "mongodb1", "ok" : 1 }

.. warning::

The :dbcommand:`movePrimary` command has many considerations, please
carefully review the documentation to ensure that these are correctly
handled.

.. _remove-shard-finalize-migration:

Finalize the Migration
Expand All @@ -209,4 +215,4 @@ A success message appears at completion:
}

Once the value of the ``state`` field is "completed", you may safely
stop the processes comprising the ``mongodb0`` shard.
stop the instances comprising the ``mongodb0`` shard.