#27345 Removed configurable fields and improved MongoDbStore TTL info / recommendations

Author: Joe Bennett

components/lock.rst

@@ -238,16 +238,12 @@ This store does not support blocking, and expects a TTL to avoid stalled locks::
 
 The ``MongoDbStore`` takes the following ``$options``:
 
-=============== =============== ===================================================================================
-Option          Default         Description
-=============== =============== ===================================================================================
-database                        The name of the database [Mandatory]
-collection      ``lock``        The name of the collection
-resource_field  ``_id``         The field name for storing the lock id **MUST be uniquely indexed if you chage it**
-token_field     ``token``       The field name for storing the lock token
-acquired_field  ``acquired_at`` The field name for storing the acquisition timestamp
-expiry_field    ``expires_at``  The field name for storing the expiry-timestamp
-=============== =============== ===================================================================================
+=========== ========= ====================================
+Option      Default   Description
+=========== ========= ====================================
+database              The name of the database [Mandatory]
+collection  ``lock``  The name of the collection
+=========== ========= ====================================
 
 .. _lock-store-redis:
 
@@ -468,21 +464,25 @@ method uses the Memcached's ``flush()`` method which purges and removes everythi
 MongoDbStore
 ~~~~~~~~~~~~
 
-The MongoDbStore relies on a unique index on the ``<resource_field>``. By default
-this is ``_id`` which already has a unique index being the collection identifier.
-It is strongly recommended to leave this as is. If you do need to change the
-``<resource_field>`` you **MUST** ensure you place a unique index on your filed.
+An indexed field's value in MongoDB can be a maximum of 1024 bytes in length
+inclusive of structural overhead.
 
-It's possible to automatically expire the locks in the database as described below:
+For more details see: https://docs.mongodb.com/manual/reference/limits/#Index-Key-Limit
 
-A TTL index can be used on MongoDB 2.2+ to cleanup expired locks
-automatically. Such an index can for example look like this:
+A TTL index MUST BE used on MongoDB 2.2+ to automatically clean up expired locks.
+Please be aware any clock drift between the application and mongo servers could
+cause locks to be released prematurely. To account for any drift;
+expireAfterSeconds can be set to a value higher than 0. The logical expiry of
+locks is handled by the application so setting a higher ``expireAfterSeconds``
+has no effect other than keeping stale data for longer.
+
+Such an index can for example look like this:
 
 .. code-block:: javascript
 
-    db.<lock-collection>.ensureIndex(
-        { "<expiry-field>": 1 },
-        { "expireAfterSeconds": 0 }
+    db.lock.ensureIndex(
+        { "expires_at": 1 },
+        { "expireAfterSeconds": 60 }
     )
 
 For more details see: http://docs.mongodb.org/manual/tutorial/expire-data/