Added support for scrollable cursors in thin mode.

Author: anthony-tuininga

doc/src/api_manual/async_cursor.rst

@@ -326,6 +326,25 @@ AsyncCursor Methods
         :meth:`AsyncCursor.callfunc()`, the first parameter in the list refers
         to the return value of the PL/SQL function.
 
+.. method:: AsyncCursor.scroll(value=0, mode="relative")
+
+    Scrolls the cursor in the result set to a new position according to the
+    mode.
+
+    If mode is *relative* (the default value), the value is taken as an offset
+    to the current position in the result set. If set to *absolute*, value
+    states an absolute target position. If set to *first*, the cursor is
+    positioned at the first row and if set to *last*, the cursor is set to the
+    last row in the result set.
+
+    An error is raised if the mode is *relative* or *absolute* and the scroll
+    operation would position the cursor outside of the result set.
+
+    .. note::
+
+        This method is an extension to the DB API definition but it is
+        mentioned in PEP 249 as an optional extension.
+
 .. method:: AsyncCursor.setoutputsize(size, [column])
 
     This method does nothing and is retained solely for compatibility with the

doc/src/release_notes.rst

@@ -17,6 +17,7 @@ oracledb 3.1.0 (TBD)
 Thin Mode Changes
 +++++++++++++++++
 
+#)  Added support for :ref:`scrollable cursors <scrollablecursors>`.
 #)  Improved support for :ref:`Oracle Advanced Queuing <aqusermanual>`:
 
     - Added support for JSON payloads

doc/src/user_guide/appendix_a.rst

@@ -260,7 +260,7 @@ see :ref:`driverdiff` and :ref:`compatibility`.
       - Yes
       - Yes
     * - Scrollable cursors (see :ref:`scrollablecursors`)
-      - No
+      - Yes
       - Yes
       - Yes
     * - Oracle Database startup and shutdown (see :ref:`startup`)

doc/src/user_guide/sql_execution.rst

@@ -625,11 +625,6 @@ rows, and to move to a particular row in a query result set. The result set is
 cached on the database server until the cursor is closed. In contrast, regular
 cursors are restricted to moving forward.
 
-.. note::
-
-  Scrollable cursors are only supported in the python-oracledb Thick mode. See
-  :ref:`enablingthick`.
-
 A scrollable cursor is created by setting the parameter ``scrollable=True``
 when creating the cursor. The method :meth:`Cursor.scroll()` is used to move to
 different locations in the result set.
@@ -656,6 +651,10 @@ Examples are:
     cursor.scroll(-4)
     print("SKIP BACK 4 ROWS:", cursor.fetchone())
 
+See `samples/scrollable_cursors.py <https://github.com/oracle/python-oracledb/
+blob/main/samples/scrollable_cursors.py>`__ for a runnable example.
+
+
 .. _fetchobjects:
 
 Fetching Oracle Database Objects and Collections

samples/scrollable_cursors.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2016, 2023, Oracle and/or its affiliates.
+# Copyright (c) 2016, 2025, Oracle and/or its affiliates.
 #
 # Portions Copyright 2007-2015, Anthony Tuininga. All rights reserved.
 #
@@ -38,8 +38,9 @@
 import oracledb
 import sample_env
 
-# this script is currently only supported in python-oracledb thick mode
-oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
+# determine whether to use python-oracledb thin mode or thick mode
+if not sample_env.get_is_thin():
+    oracledb.init_oracle_client(lib_dir=sample_env.get_oracle_client())
 
 connection = oracledb.connect(
     user=sample_env.get_main_user(),

src/oracledb/cursor.py

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------------
-# Copyright (c) 2021, 2024, Oracle and/or its affiliates.
+# Copyright (c) 2021, 2025, Oracle and/or its affiliates.
 #
 # This software is dual-licensed to you under the Universal Permissive License
 # (UPL) 1.0 as shown at https://oss.oracle.com/licenses/upl and Apache License
@@ -846,17 +846,17 @@ def scroll(self, value: int = 0, mode: str = "relative") -> None:
         Scroll the cursor in the result set to a new position according to the
         mode.
 
-        If mode is “relative” (the default value), the value is taken as an
-        offset to the current position in the result set. If set to “absolute”,
-        value states an absolute target position. If set to “first”, the cursor
-        is positioned at the first row and if set to “last”, the cursor is set
+        If mode is "relative" (the default value), the value is taken as an
+        offset to the current position in the result set. If set to "absolute",
+        value states an absolute target position. If set to "first", the cursor
+        is positioned at the first row and if set to "last", the cursor is set
         to the last row in the result set.
 
-        An error is raised if the mode is “relative” or “absolute” and the
+        An error is raised if the mode is "relative" or "absolute" and the
         scroll operation would position the cursor outside of the result set.
         """
         self._verify_open()
-        self._impl.scroll(self.connection, value, mode)
+        self._impl.scroll(self, value, mode)
 
 
 class AsyncCursor(BaseCursor):
@@ -1081,3 +1081,20 @@ async def parse(self, statement: str) -> None:
         self._verify_open()
         self._prepare(statement)
         await self._impl.parse(self)
+
+    async def scroll(self, value: int = 0, mode: str = "relative") -> None:
+        """
+        Scroll the cursor in the result set to a new position according to the
+        mode.
+
+        If mode is "relative" (the default value), the value is taken as an
+        offset to the current position in the result set. If set to "absolute",
+        value states an absolute target position. If set to "first", the cursor
+        is positioned at the first row and if set to "last", the cursor is set
+        to the last row in the result set.
+
+        An error is raised if the mode is "relative" or "absolute" and the
+        scroll operation would position the cursor outside of the result set.
+        """
+        self._verify_open()
+        await self._impl.scroll(self, value, mode)

src/oracledb/errors.py

@@ -282,6 +282,7 @@ def _raise_not_supported(feature: str) -> None:
 ERR_ARROW_C_API_ERROR = 2060
 ERR_PARAMS_HOOK_HANDLER_FAILED = 2061
 ERR_PAYLOAD_CANNOT_BE_ENQUEUED = 2062
+ERR_SCROLL_OUT_OF_RESULT_SET = 2063
 
 # error numbers that result in NotSupportedError
 ERR_TIME_NOT_SUPPORTED = 3000
@@ -428,6 +429,7 @@ def _raise_not_supported(feature: str) -> None:
 ERR_DPI_ERROR_XREF = {
     1010: ERR_NOT_CONNECTED,
     1024: (ERR_INVALID_COLL_INDEX_GET, r"at index (?P<index>\d+) does"),
+    1027: ERR_SCROLL_OUT_OF_RESULT_SET,
     1043: ERR_INVALID_NUMBER,
     1044: ERR_ORACLE_NUMBER_NO_REPR,
     1063: ERR_EXECUTE_MODE_ONLY_FOR_DML,
@@ -772,6 +774,9 @@ def _raise_not_supported(feature: str) -> None:
     ERR_PYTHON_VALUE_NOT_SUPPORTED: (
         'Python value of type "{type_name}" is not supported'
     ),
+    ERR_SCROLL_OUT_OF_RESULT_SET: (
+        "scroll operation would go out of the result set"
+    ),
     ERR_SELF_BIND_NOT_SUPPORTED: "binding to self is not supported",
     ERR_CONNECTION_CLOSED: "the database or network closed the connection",
     ERR_SERVER_VERSION_NOT_SUPPORTED: (

src/oracledb/impl/base/cursor.pyx

@@ -664,7 +664,7 @@ cdef class BaseCursorImpl:
         """
         self._prepare(statement, tag, cache_statement)
 
-    def scroll(self, conn, value, mode):
+    def scroll(self, cursor, value, mode):
         """
         Scrolls a scrollable cursor.
         """

src/oracledb/impl/thick/cursor.pyx

@@ -510,7 +510,7 @@ cdef class ThickCursorImpl(BaseCursorImpl):
         if num_query_cols > 0:
             self._perform_define(cursor, num_query_cols)
 
-    def scroll(self, object conn, int32_t offset, object mode):
+    def scroll(self, object cursor, int32_t offset, object mode):
         cdef:
             uint32_t temp_buffer_row_index = 0, num_rows_in_buffer = 0
             bint more_rows_to_fetch = False

src/oracledb/impl/thin/constants.pxi

@@ -239,6 +239,17 @@ cdef enum:
 cdef enum:
     TNS_EXEC_FLAGS_DML_ROWCOUNTS = 0x4000
     TNS_EXEC_FLAGS_IMPLICIT_RESULTSET = 0x8000
+    TNS_EXEC_FLAGS_SCROLLABLE = 0x02
+
+# fetch orientations
+cdef enum:
+    TNS_FETCH_ORIENTATION_ABSOLUTE = 0x20
+    TNS_FETCH_ORIENTATION_CURRENT = 0x01
+    TNS_FETCH_ORIENTATION_FIRST = 0x04
+    TNS_FETCH_ORIENTATION_LAST = 0x08
+    TNS_FETCH_ORIENTATION_NEXT = 0x02
+    TNS_FETCH_ORIENTATION_PRIOR = 0x10
+    TNS_FETCH_ORIENTATION_RELATIVE = 0x40
 
 # server side piggyback op codes
 cdef enum:

src/oracledb/impl/thin/cursor.pyx

@@ -37,6 +37,8 @@ cdef class BaseThinCursorImpl(BaseCursorImpl):
         list _batcherrors
         list _dmlrowcounts
         list _implicit_resultsets
+        uint64_t _buffer_min_row
+        uint64_t _buffer_max_row
         uint32_t _num_columns
         uint32_t _last_row_index
         Rowid _lastrowid
@@ -61,6 +63,64 @@ cdef class BaseThinCursorImpl(BaseCursorImpl):
         message.cursor_impl = self
         return message
 
+    cdef ExecuteMessage _create_execute_message(self, object cursor):
+        """
+        Creates and returns the message used to execute a statement once.
+        """
+        cdef ExecuteMessage message
+        message = self._create_message(ExecuteMessage, cursor)
+        message.num_execs = 1
+        if self.scrollable:
+            message.fetch_orientation = TNS_FETCH_ORIENTATION_CURRENT
+            message.fetch_pos = 1
+        return message
+
+    cdef ExecuteMessage _create_scroll_message(self, object cursor,
+                                               object mode, int32_t offset):
+        """
+        Creates a message object that is used to send a scroll request to the
+        database and receive back its response.
+        """
+        cdef:
+            ExecuteMessage message
+            uint32_t orientation
+            uint64_t desired_row
+
+        # check mode and calculate desired row
+        if mode == "relative":
+            if <int64_t> (self.rowcount + offset) < 1:
+                errors._raise_err(errors.ERR_SCROLL_OUT_OF_RESULT_SET)
+            orientation = TNS_FETCH_ORIENTATION_RELATIVE
+            desired_row = self.rowcount + offset
+        elif mode == "absolute":
+            orientation = TNS_FETCH_ORIENTATION_ABSOLUTE
+            desired_row = <uint64_t> offset
+        elif mode == "first":
+            orientation = TNS_FETCH_ORIENTATION_FIRST
+            desired_row = 1
+        elif mode == "last":
+            orientation = TNS_FETCH_ORIENTATION_LAST
+        else:
+            errors._raise_err(errors.ERR_WRONG_SCROLL_MODE)
+
+        # determine if the server needs to be contacted at all
+        # for "last", the server is always contacted
+        if orientation != TNS_FETCH_ORIENTATION_LAST \
+                and desired_row >= self._buffer_min_row \
+                and desired_row < self._buffer_max_row:
+            self._buffer_index = \
+                    <uint32_t> (desired_row - self._buffer_min_row)
+            self._buffer_rowcount = self._buffer_max_row - desired_row
+            self.rowcount = desired_row - 1
+            return None
+
+        # build message
+        message = self._create_message(ExecuteMessage, cursor)
+        message.scroll_operation = self._more_rows_to_fetch
+        message.fetch_orientation = orientation
+        message.fetch_pos = <uint32_t> desired_row
+        return message
+
     cdef BaseVarImpl _create_var_impl(self, object conn):
         cdef ThinVarImpl var_impl
         var_impl = ThinVarImpl.__new__(ThinVarImpl)
@@ -125,6 +185,28 @@ cdef class BaseThinCursorImpl(BaseCursorImpl):
                 errors._raise_err(errors.ERR_MISSING_BIND_VALUE,
                                   name=bind_info._bind_name)
 
+    cdef int _post_process_scroll(self, ExecuteMessage message) except -1:
+        """
+        Called after a scroll operation has completed successfully. The row
+        count and buffer row counts and indices are updated as required.
+        """
+        if self._buffer_rowcount == 0:
+            if message.fetch_orientation not in (
+                TNS_FETCH_ORIENTATION_FIRST,
+                TNS_FETCH_ORIENTATION_LAST
+            ):
+                errors._raise_err(errors.ERR_SCROLL_OUT_OF_RESULT_SET)
+            self.rowcount = 0
+            self._more_rows_to_fetch = False
+            self._buffer_index = 0
+            self._buffer_min_row = 0
+            self._buffer_max_row = 0
+        else:
+            self.rowcount = message.error_info.rowcount - self._buffer_rowcount
+            self._buffer_min_row = self.rowcount + 1
+            self._buffer_max_row = self._buffer_min_row + self._buffer_rowcount
+            self._buffer_index = 0
+
     cdef int _set_fetch_array_size(self, uint32_t value):
         """
         Internal method for setting the fetch array size. This also ensures
@@ -182,15 +264,16 @@ cdef class ThinCursorImpl(BaseThinCursorImpl):
         else:
             message = self._create_message(FetchMessage, cursor)
         protocol._process_single_message(message)
+        self._buffer_min_row = self.rowcount + 1
+        self._buffer_max_row = self._buffer_min_row + self._buffer_rowcount
 
     def execute(self, cursor):
         cdef:
             Protocol protocol = <Protocol> self._conn_impl._protocol
             object conn = cursor.connection
             MessageWithData message
         self._preprocess_execute(conn)
-        message = self._create_message(ExecuteMessage, cursor)
-        message.num_execs = 1
+        message = self._create_execute_message(cursor)
         protocol._process_single_message(message)
         self.warning = message.warning
         if self._statement._is_query:
@@ -242,6 +325,15 @@ cdef class ThinCursorImpl(BaseThinCursorImpl):
         message.parse_only = True
         protocol._process_single_message(message)
 
+    def scroll(self, object cursor, int32_t offset, object mode):
+        cdef:
+            Protocol protocol = <Protocol> self._conn_impl._protocol
+            ExecuteMessage message
+        message = self._create_scroll_message(cursor, mode, offset)
+        if message is not None:
+            protocol._process_single_message(message)
+            self._post_process_scroll(message)
+
 
 cdef class AsyncThinCursorImpl(BaseThinCursorImpl):
 
@@ -268,6 +360,7 @@ cdef class AsyncThinCursorImpl(BaseThinCursorImpl):
         else:
             message = self._create_message(FetchMessage, cursor)
         await self._conn_impl._protocol._process_single_message(message)
+        self._buffer_min_row = self.rowcount + 1
 
     async def _preprocess_execute_async(self, object conn):
         """
@@ -293,8 +386,7 @@ cdef class AsyncThinCursorImpl(BaseThinCursorImpl):
             MessageWithData message
         protocol = <BaseAsyncProtocol> self._conn_impl._protocol
         await self._preprocess_execute_async(conn)
-        message = self._create_message(ExecuteMessage, cursor)
-        message.num_execs = 1
+        message = self._create_execute_message(cursor)
         await protocol._process_single_message(message)
         self.warning = message.warning
         if self._statement._is_query:
@@ -378,3 +470,13 @@ cdef class AsyncThinCursorImpl(BaseThinCursorImpl):
         message = self._create_message(ExecuteMessage, cursor)
         message.parse_only = True
         await protocol._process_single_message(message)
+
+    async def scroll(self, object cursor, int32_t offset, object mode):
+        cdef:
+            BaseAsyncProtocol protocol
+            MessageWithData message
+        protocol = <BaseAsyncProtocol> self._conn_impl._protocol
+        message = self._create_scroll_message(cursor, mode, offset)
+        if message is not None:
+            await protocol._process_single_message(message)
+            self._post_process_scroll(message)