You are viewing a plain text version of this content. The canonical link for it is here.
Posted to oak-commits@jackrabbit.apache.org by mr...@apache.org on 2018/05/23 14:40:59 UTC
svn commit: r1832107 - in
/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore:
document/mongo-document-store.md documentmk.md
Author: mreutegg
Date: Wed May 23 14:40:59 2018
New Revision: 1832107
URL: http://svn.apache.org/viewvc?rev=1832107&view=rev
Log:
OAK-301 - Document Oak
Move MongoDB specific documentation to mongo-document-store.md
Modified:
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md?rev=1832107&r1=1832106&r2=1832107&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/document/mongo-document-store.md Wed May 23 14:40:59 2018
@@ -44,7 +44,7 @@ instances and an arbiter) may lead to da
When using MongoDB 3.4 or newer, set the [maxStalenessSeconds](https://docs.mongodb.com/manual/core/read-preference/#maxstalenessseconds)
option in the MongoDB URI to `90`. This is an additional safeguard and will
-prevent reads from a secondary that are too far behind.
+prevent reads from a secondary that is too far behind.
Initializing a DocumentNodeStore on MongoDB with default values will also use
MongoDB to store blobs. While this is convenient for development and tests, the
@@ -74,6 +74,32 @@ a `MongoDocumentNodeStoreBuilder`.
Please note, even though the default is to store blobs in MongoDB, this is not
a recommended setup. See also [recommendations](#recommendations).
+## <a name="read-preference"></a> Read preference
+
+Without any read preference specified in the MongoDB URI, most read operations
+will be directed to the MongoDB primary to ensure consistent reads.
+Functionality like Revision Garbage Collection does not have such a strict
+requirement and will therefore scan (read) for garbage with a read preference
+of `secondaryPreferred`. This takes pressure off the primary.
+
+When the `MongoDocumentStore` is configured with an explicit read preference via
+the MongoDB URI, the read preference is considered a hit. The implementation
+may still read from the primary when it cannot guarantee a consistent read from
+a secondary. This may be the case when a secondary lags behind and a read
+happens for a document that was recently modified.
+
+A common use case is setting a read preference for a nearby secondary. This can
+be achieved with `readPreferenceTags` in the MongoDB URI.
+
+The below example will prefer a secondary with tag _dc:ny,rack:1_. If no such
+secondary is available, the read operation will target to a secondary with tag
+_dc:ny_ and if no such secondary is available either, any available secondary is
+chosen. As a final fallback the read will be served from the primary.
+
+ mongodb://example1.com,example2.com,example3.com/?readPreference=secondaryPreferred&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=
+
+Refer to [Read Preference Options][3] and [Write Concern Options][4] for more details.
+
## <a name="configuration"></a> Configuration
Independent of whether the DocumentNodeStore is initialized via the OSGi service
@@ -81,7 +107,7 @@ or the builder, the implementation will
appropriate default MongoDB client parameters. This includes the write concern,
which controls how many MongoDB replica-set members must acknowledge a write
operation. Without an explicit write concern specified in the MongoDB URI, the
-implementation will set write concern based on the MongoDB topology. If MongoDB
+implementation will set a write concern based on the MongoDB topology. If MongoDB
is setup as a replica-set, then Oak will use a `majority` write concern. When
running on a single standalone MongoDB instance, the write concern is set to
'acknowledged'.
@@ -94,3 +120,22 @@ concern is set to `local`.
Oak will log WARN messages if it deems the read and write concerns given via the
MongoDB URI insufficient.
+In addition to specifying the [read preference][1] and [write concern][2] in the
+MongoDB URI, those two parameters can also be set and changed at runtime by
+setting the property `readWriteMode` in the cluster node metadata. A cluster
+node will pick up the change within ten seconds (when it renews the lease of the
+cluster node id). This is a string property with the format
+`'readPreference=<preference>&w=<writeConcern>'` similar to the way it is used
+in MongoDB URI. Just that it does not include other option details.
+
+The following MongoDB shell command will set the read preference to `primary`
+and the write concern to `majority` for all cluster nodes:
+
+ > db.clusterNodes.update({},
+ {$set: {readWriteMode:'readPreference=primary&w=majority'}},
+ {multi: true})
+
+[1]: http://docs.mongodb.org/manual/core/read-preference/
+[2]: http://docs.mongodb.org/manual/core/write-concern/
+[3]: http://docs.mongodb.org/manual/reference/connection-string/#read-preference-options
+[4]: http://docs.mongodb.org/manual/reference/connection-string/#write-concern-options
Modified: jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md
URL: http://svn.apache.org/viewvc/jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md?rev=1832107&r1=1832106&r2=1832107&view=diff
==============================================================================
--- jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md (original)
+++ jackrabbit/oak/trunk/oak-doc/src/site/markdown/nodestore/documentmk.md Wed May 23 14:40:59 2018
@@ -545,41 +545,7 @@ and the uuid.
### <a name="rw-preference"></a> Specifying the Read Preference and Write Concern
-With `MongoDocumentStore` you can specify the the [read preference][1] and [write concern][2].
-This can be enabled in Oak via two modes.
-
-Note that `MongoDocumentStore` might still use a pre defined read preference like primary
-where ever required. So if for some code path like reading latest `_lastRev` of root node
-its required that read is performed from primary (for consistency) then code would explicitly
-use the readPreference primary for that operation. For all other operation Mongo Java Driver would
-use default settings where read preference is set to `Primary` and write concern is set to `Acknowledged`.
-Via using one of the two modes below a user can tune the default settings as per its need
-
-#### <a name="via-configuration"></a> Via Configuration
-
-In this mode the config is specified as part of the Mongo URI (See [configuration](../osgi_config.html#document-node-store)).
-So if a user wants that reads from secondaries should prefer secondary with tag _dc:ny,rack:1_
-otherwise they go to other secondary then he can specify that via following mongouri
-
- mongodb://example1.com,example2.com,example3.com/?readPreference=secondary&readPreferenceTags=dc:ny,rack:1&readPreferenceTags=dc:ny&readPreferenceTags=
-
-Refer to [Read Preference Options][3] and [Write Concern Options][4] for more details.
-
-#### <a name="changing-at-runtime"></a> Changing at Runtime
-
-The read preference and write concern of all cluster nodes can be changed at runtime
-without having to restart the instances, by setting the property `readWriteMode` of
-this collection. All cluster nodes will pick up the change within one minute
-(when they renew the lease of the cluster node id). This is a string property with the
-format `'readPreference=<preference>&w=<writeConcern>'` similar to the way it is used in mongouri.
-Just that it does not include other option details. The following shell command will
-set the read preference to `primary` and the write concern to `majority` for all
-cluster nodes:
-
- > db.clusterNodes.update({},
- {$set: {readWriteMode:'readPreference=primary&w=majority'}},
- {multi: true})
-
+See [configuration](document/mongo-document-store.html#configuration) of a `MongoDocumentStore`.
## <a name="cache"></a> Caching
@@ -777,10 +743,6 @@ mode, the RGC will not log every run but
summarizing the GC cycles for the past hour.
For more details, see also the [OSGi configuration][osgi-config] page.
-[1]: http://docs.mongodb.org/manual/core/read-preference/
-[2]: http://docs.mongodb.org/manual/core/write-concern/
-[3]: http://docs.mongodb.org/manual/reference/connection-string/#read-preference-options
-[4]: http://docs.mongodb.org/manual/reference/connection-string/#write-concern-options
[OAK-1156]: https://issues.apache.org/jira/browse/OAK-1156
[OAK-2646]: https://issues.apache.org/jira/browse/OAK-2646
[OAK-2546]: https://issues.apache.org/jira/browse/OAK-2546