From 0859a69b8361b4b8ea3d622f67310b59f55fe1f1 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 28 Aug 2012 18:12:27 -0400 Subject: [PATCH 1/2] added in _secondaryThrottle parameter description --- source/administration/sharding.txt | 7 ++++ source/core/sharding-internals.txt | 49 +++++++++++++++++++++++++- source/reference/command/moveChunk.txt | 14 +++++++- 3 files changed, 68 insertions(+), 2 deletions(-) diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index 92a7bbc2d30..cb723d7c9e0 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -566,6 +566,13 @@ This command moves the chunk that includes the shard key value "smith" to the :term:`shard` named ``mongodb-shard3.example.net``. The command will block until the migration is complete. +.. versionadded:: 2.2 + + :dbcommand:`moveChunk` command accepts parameter: + ``_secondaryThrottle``, when set to ``true``, MongoDB will ensure + secondary members have replicated changes before allowing new chunk + migrations to occur. + .. note:: To return a list of shards, use the :dbcommand:`listshards` diff --git a/source/core/sharding-internals.txt b/source/core/sharding-internals.txt index 59417374ac5..18960183ea6 100644 --- a/source/core/sharding-internals.txt +++ b/source/core/sharding-internals.txt @@ -374,7 +374,7 @@ chunks. The balancer has the following thresholds: Number of Chunks Migration Threshold ---------------- ------------------- Greater than 80 8 -80-21 4 +21-80 4 Less than 20 2 ================ =================== @@ -449,3 +449,50 @@ to the shard when the value of :status:`mem.mapped` exceeds the ``maxSize`` setting. .. seealso:: ":doc:`/administration/monitoring`." + +.. _sharding-chunk-migration: + +Chunk Migration +~~~~~~~~~~~~~~~ + +MongoDB migrates chunks in a :term:`shard cluster` to distribute data +evenly among shards. Migrations may be either: + +- Manual. In these migrations you must specify the chunk that you want + to migrate and the destination shard. Only migrate chunks manually + after initiating sharding, to distribute data during bulk inserts, + or if the cluster becomes uneven. See :doc:`Migrating Chunks + ` for more details. + +- Automatic. The balancer process handles most migrations when + distribution of chunks between shards becomes uneven. See + :doc:`Migration Thresholds ` for more + details. + +All chunk migrations use the following procedure: + +#. The balancer process sends the :dbCommand:`moveChunk` command to + the source shard for the chunk. In this operation the balancer + passes the name of the destination shard to the source shard. + +#. The source initaties the move with an internal + :dbcommand:`moveChunk` command with the destination shard. + +#. The destination shard begins requesting documents in the chunk, and + begins receiving these chunks. + +#. After receving the final document in the chunk, the destination + shard initiates a synchronization process to ensure that all + changes to the documents in the chunk on the source shard during + the migration process exist on the destination shard. + + When fully synchronized, the destination shard connects to the + :term:`config database` and updates the chunk location in the + cluster metadata. After completing this operation, once there are + no open cursors on the chunk, the source shard starts deleting + its copy of documents from the migrated chunk. + +When the ``_secondaryThrottle`` option is set ``true`` for +:dbcommand:`moveChunk` or the :term:`balancer`, MongoDB will ensure +secondary members have replicated changes before allowing new chunk +migrations to occur. diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 23195c2daec..8fbe325c988 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -7,8 +7,20 @@ moveChunk .. dbcommand:: moveChunk :dbcommand:`moveChunk` is an internal command that supports the - sharding functionality. Do not call directly. Use the + sharding functionality. Use the :method:`sh.moveChunk()` function in the :program:`mongo` shell if you must move a chunk manually. + :option _secondaryThrottle: Optional. The default setting is + ``false``. If ``true`` this will + specify that primary shard members + should wait for its secondary shard + members to replicate chunk data updates + before allowing new chunk migrations to + occur. + + For details on chunk migrations, please + see: :ref:`Sharding Internals - Chunk + Migration ` + .. admin-only From 88b86beafc21c35ef0f6b26a28da39abed166f00 Mon Sep 17 00:00:00 2001 From: Andrew Leung Date: Tue, 28 Aug 2012 18:36:32 -0400 Subject: [PATCH 2/2] Added in remove balance window (DOCS-453) and fixing rendering changes --- source/administration/sharding.txt | 9 ++++++++- source/core/sharding-internals.txt | 6 +++--- source/reference/command/moveChunk.txt | 14 +++++++------- 3 files changed, 18 insertions(+), 11 deletions(-) diff --git a/source/administration/sharding.txt b/source/administration/sharding.txt index cb723d7c9e0..31850cbd2ca 100644 --- a/source/administration/sharding.txt +++ b/source/administration/sharding.txt @@ -570,7 +570,7 @@ block until the migration is complete. :dbcommand:`moveChunk` command accepts parameter: ``_secondaryThrottle``, when set to ``true``, MongoDB will ensure - secondary members have replicated changes before allowing new chunk + :term:`secondary` members have replicated changes before allowing new chunk migrations to occur. .. note:: @@ -698,6 +698,13 @@ be able to migrate chunks: db.settings.update({ _id : "balancer" }, { $set : { activeWindow : { start : "23:00", stop : "6:00" } } }, true ) +To turn off the balancing window: + + .. code-block:: javascript + + use config + db.settings.update({ _id : "balancer" }, { $unset : { activeWindow : true }) + .. note:: The balancer window must be sufficient to *complete* the migration diff --git a/source/core/sharding-internals.txt b/source/core/sharding-internals.txt index 18960183ea6..632ee938282 100644 --- a/source/core/sharding-internals.txt +++ b/source/core/sharding-internals.txt @@ -461,12 +461,12 @@ evenly among shards. Migrations may be either: - Manual. In these migrations you must specify the chunk that you want to migrate and the destination shard. Only migrate chunks manually after initiating sharding, to distribute data during bulk inserts, - or if the cluster becomes uneven. See :doc:`Migrating Chunks + or if the cluster becomes uneven. See :ref:`Migrating Chunks ` for more details. - Automatic. The balancer process handles most migrations when distribution of chunks between shards becomes uneven. See - :doc:`Migration Thresholds ` for more + :ref:`Migration Thresholds ` for more details. All chunk migrations use the following procedure: @@ -494,5 +494,5 @@ All chunk migrations use the following procedure: When the ``_secondaryThrottle`` option is set ``true`` for :dbcommand:`moveChunk` or the :term:`balancer`, MongoDB will ensure -secondary members have replicated changes before allowing new chunk +:term:`secondary` members have replicated changes before allowing new chunk migrations to occur. diff --git a/source/reference/command/moveChunk.txt b/source/reference/command/moveChunk.txt index 8fbe325c988..2b5c4d0c619 100644 --- a/source/reference/command/moveChunk.txt +++ b/source/reference/command/moveChunk.txt @@ -11,13 +11,13 @@ moveChunk :method:`sh.moveChunk()` function in the :program:`mongo` shell if you must move a chunk manually. - :option _secondaryThrottle: Optional. The default setting is - ``false``. If ``true`` this will - specify that primary shard members - should wait for its secondary shard - members to replicate chunk data updates - before allowing new chunk migrations to - occur. + :option _secondaryThrottle: The default setting is ``false``. If + ``true`` this will specify that + :term:`primary` :term:`shard` members + should wait for its :term:`secondary` + shard members to replicate :term:`chunk` data + updates before allowing new chunk + migrations to occur. For details on chunk migrations, please see: :ref:`Sharding Internals - Chunk