Added support for locking SODA documents while fetching them (equivalent

of SQL select for update).

Author: anthony-tuininga

doc/src/api_manual/soda.rst

@@ -545,6 +545,29 @@ SodaOperation Methods
     19 from 19.11).
 
 
+.. method:: SodaOperation.lock()
+
+    Specifies whether the documents fetched from the collection should be
+    locked (equivalent to SQL "select for update").
+
+    The next commit or rollback on the connection made after the operation is
+    performed will "unlock" the documents. Ensure that the connection is not in
+    autocommit mode or the documents will be unlocked immediately after the
+    operation is complete.
+
+    This method should only be used with read operations (other than
+    :func:`~SodaOperation.count()`) and should not be used in
+    conjunction with non-terminal methods :meth:`~SodaOperation.skip()` and
+    :meth:`~SodaOperation.limit()`.
+
+    If this method is specified in conjunction with a write operation this
+    method is ignored.
+
+    This method is only supported in Oracle Client 21.3 and higher (also
+    available in Oracle Client 19 from 19.11).
+
+    .. versionadded:: 1.4
+
 .. method:: SodaOperation.key(value)
 
     Specifies that the document with the specified key should be returned.

doc/src/release_notes.rst

@@ -60,6 +60,10 @@ Thick Mode Changes
 
 #)  Added function :meth:`SodaCollection.getIndexes()` for getting the indexes
     on a SODA collection.
+#)  Added support for specifying if documents should be locked when fetched
+    from SODA collections. A new non-terminal method
+    :meth:`~SodaOperation.lock()` was added which requires Oracle Client
+    21.3 or higher (or Oracle Client 19 from 19.11).
 #)  Relaxed restriction for end-to-end tracing string connection
     attributes. These values can now be set to the value ``None`` which will be
     treated the same as an empty string.

src/oracledb/impl/thick/odpi.pxd

@@ -445,6 +445,7 @@ cdef extern from "impl/thick/odpi/embed/dpi.c":
         uint32_t skip
         uint32_t limit
         uint32_t fetchArraySize
+        bint lock
 
     ctypedef struct dpiStmtInfo:
         bint isQuery

src/oracledb/impl/thick/soda.pyx

@@ -664,4 +664,6 @@ cdef class ThickSodaOpImpl:
             options.limit = op._limit
         if op._fetch_array_size is not None:
             options.fetchArraySize = op._fetch_array_size
+        if op._lock:
+            options.lock = True
         return impl

src/oracledb/soda.py

@@ -463,6 +463,7 @@ def __init__(self, collection: SodaCollection) -> None:
         self._skip = None
         self._limit = None
         self._fetch_array_size = None
+        self._lock = False
 
     def count(self) -> int:
         """
@@ -552,6 +553,18 @@ def hint(self, value: str) -> "SodaOperation":
         self._hint = value
         return self
 
+    def lock(self) -> "SodaOperation":
+        """
+        Specifies whether the documents fetched from the collection should be
+        locked (equivalent to SQL "select for update"). Use of this method
+        requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).
+
+        As a convenience, the SodaOperation object is returned so that further
+        criteria can be specified by chaining methods together.
+        """
+        self._lock = True
+        return self
+
     def key(self, value: str) -> "SodaOperation":
         """
         Specifies that the document with the specified key should be returned.

tests/test_3400_soda_collection.py

@@ -663,5 +663,18 @@ def test_3429_getting_indexes(self):
         self.assertEqual(indexes[0]["fields"][0]["path"], "address.city")
         self.assertEqual(indexes[1]["fields"][0]["path"], "address.postal_code")
 
+    def test_3430_lock_documents(self):
+        "3430 - test locking documents on fetch"
+        soda_db = self.get_soda_database(minclient=(19, 11))
+        coll = soda_db.createCollection("TestSodaLockDocs")
+        coll.find().remove()
+        values_to_insert = [
+            {"name": "Bob", "age": 46},
+            {"name": "Barb", "age": 45},
+            {"name": "Sandy", "age": 47}
+        ]
+        coll.insertMany(values_to_insert)
+        coll.find().lock().getDocuments()
+
 if __name__ == "__main__":
     test_env.run_test_cases()