Create docs chapter for sharding

doctrine · May 20, 2016 · 7887ac7 · 7887ac7
1 parent 67caa7b
commit 7887ac7
Show file tree

Hide file tree

Showing 3 changed files with 72 additions and 53 deletions.
diff --git a/docs/en/index.rst b/docs/en/index.rst
@@ -69,8 +69,9 @@ Advanced Topics
 
 * **Collections**:
   :doc:`Capped Collections <reference/capped-collections>` |
-  :doc:`Storage Strategies <reference/storage-strategies>`
-  :doc:`Custom Collections <reference/custom-collections>`
+  :doc:`Storage Strategies <reference/storage-strategies>` |
+  :doc:`Custom Collections <reference/custom-collections>` |
+  :doc:`Sharded setups <reference/sharding>`
 
 * **Best Practices**:
   :doc:`Best Practices <reference/best-practices>`

diff --git a/docs/en/reference/indexes.rst b/docs/en/reference/indexes.rst
@@ -489,54 +489,3 @@ it on a per query basis:
     $qb->requireIndexes(true);
     $query = $qb->getQuery();
     $results = $query->execute();
-
-Shard keys
-----------
-
-When using a sharded setup you need to define a shard key for all collections that need to be sharded.
-You can define this index on the document level:
-
-.. configuration-block::
-
-    .. code-block:: php
-
-        <?php
-
-        /**
-         * @Document
-         * @ShardKey(keys={"username"="asc"})
-         */
-        class User
-        {
-            /** @Id */
-            public $id;
-
-            /** @Field(type="int") */
-            public $accountId;
-
-            /** @Field(type="string") */
-            public $username;
-        }
-
-    .. code-block:: xml
-
-        <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping"
-              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
-              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping
-                            http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd">
-
-            <document name="Documents\User">
-                <shard-key>
-                    <key name="username" order="asc"/>
-                </shard-key>
-            </document>
-        </doctrine-mongo-mapping>
-
-    .. code-block:: yaml
-
-        Documents\User:
-          shardKey:
-            keys:
-              username: asc
-
-You can create these indexes in the database using the `odm:schema:create` command.
diff --git a/docs/en/reference/sharding.rst b/docs/en/reference/sharding.rst
@@ -0,0 +1,69 @@
+.. _sharding:
+
+Sharding
+========
+
+MongoDB allows you to horizontally scale your database. In order to enable this,
+Doctrine MongoDB ODM needs to know about your sharding setup. For basic information
+about sharding, please refer to the `MongoDB docs <https://docs.mongodb.com/manual/sharding/>`_.
+
+Once you have a `sharded cluster <https://docs.mongodb.com/manual/core/sharded-cluster-architectures-production/>`_,
+you can enable sharding for a document. You can do this by defining a shard key in
+the document:
+
+.. configuration-block::
+
+    .. code-block:: php
+
+        <?php
+
+        /**
+         * @Document
+         * @ShardKey(keys={"username"="asc"})
+         */
+        class User
+        {
+            /** @Id */
+            public $id;
+
+            /** @Field(type="int") */
+            public $accountId;
+
+            /** @Field(type="string") */
+            public $username;
+        }
+
+    .. code-block:: xml
+
+        <doctrine-mongo-mapping xmlns="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping"
+              xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+              xsi:schemaLocation="http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping
+                            http://doctrine-project.org/schemas/orm/doctrine-mongo-mapping.xsd">
+
+            <document name="Documents\User">
+                <shard-key>
+                    <key name="username" order="asc"/>
+                </shard-key>
+            </document>
+        </doctrine-mongo-mapping>
+
+    .. code-block:: yaml
+
+        Documents\User:
+          shardKey:
+            keys:
+              username: asc
+
+.. note::
+    When a shard key is defined for a document, Doctrine MongoDB ODM will no
+    longer persist changes to the shard key as these fields become immutable in
+    a sharded setup.
+
+Once you've defined a shard key you need to enable sharding for the collection
+where the document will be stored. To do this, use the ``odm:schema:shard``
+command.
+
+.. note::
+
+    For performance reasons, sharding is not enabled during the
+    ``odm:schema:create`` and ``odm:schema:update`` commmands.