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()