Fixed bug that prevented binding data of types DB_TYPE_ROWID and

DB_TYPE_UROWID.

Author: anthony-tuininga

doc/src/api_manual/module.rst

@@ -2066,9 +2066,9 @@ DB API Types
 .. data:: ROWID
 
     This type object is used to describe the pseudo column "rowid". The
-    database type :data:`DB_TYPE_ROWID` will compare equal to this value. If a
-    variable is created with this type, the database type
-    :data:`DB_TYPE_VARCHAR` will be used.
+    database types :data:`DB_TYPE_ROWID` and :data:`DB_TYPE_UROWID` will
+    compare equal to this value. If a variable is created with this type, the
+    database type :data:`DB_TYPE_VARCHAR` will be used.
 
 
 .. data:: STRING
@@ -2281,6 +2281,17 @@ when binding data.
     :data:`DATETIME`.
 
 
+.. data:: DB_TYPE_UROWID
+
+    Describes columns, attributes or array elements in a database that are of
+    type UROWID. It will compare equal to the DB API type :data:`ROWID`.
+
+    .. note::
+
+        This type is not supported in python-oracledb Thick mode.
+        See :ref:`querymetadatadiff`.
+
+
 .. data:: DB_TYPE_VARCHAR
 
     Describes columns, attributes or array elements in a database that are of

doc/src/release_notes.rst

@@ -13,6 +13,9 @@ oracledb 1.1.1 (TBD)
 Thin Mode Changes
 +++++++++++++++++
 
+#)  Fixed bug that prevented binding data of types
+    :data:`~oracledb.DB_TYPE_ROWID` and :data:`~oracledb.DB_TYPE_UROWID`.
+
 Thick Mode Changes
 ++++++++++++++++++
 

doc/src/user_guide/appendix_a.rst

@@ -463,11 +463,11 @@ values.
     * - ROWID
       - DB_TYPE_ROWID
       - Yes
-      - cannot be set
+      - bytes, str
     * - UROWID
-      - DB_TYPE_ROWID
+      - DB_TYPE_ROWID, DB_TYPE_UROWID (only supported in python-oracledb Thin mode)
       - Yes.  May show DB_TYPE_UROWID in metadata. See :ref:`Query Metadata Differences <querymetadatadiff>`.
-      - cannot be set
+      - bytes, str
     * - CHAR
       - DB_TYPE_CHAR
       - Yes
@@ -578,14 +578,14 @@ these arrays.
     * - DB_TYPE_RAW
       - bytes, str
     * - DB_TYPE_ROWID
-      - cannot be set
+      - bytes, str
     * - DB_TYPE_TIMESTAMP
       - datetime.date, datetime.datetime
     * - DB_TYPE_TIMESTAMP_LTZ
       - datetime.date, datetime.datetime
     * - DB_TYPE_TIMESTAMP_TZ
       - datetime.date, datetime.datetime
     * - DB_TYPE_UROWID
-      - cannot be set
+      - bytes, str
     * - DB_TYPE_VARCHAR
       - bytes, str

doc/src/user_guide/bind.rst

@@ -183,6 +183,48 @@ fetching a row and then updating that row by binding its rowid:
             where rowid = :rid""", manager_id=205, rid=rowid)
 
 
+Binding UROWID Values
+=====================
+
+Universal rowids (UROWID) are used to uniquely identify rows in index
+organized tables. In python-oracledb, UROWID values are represented as strings.
+The example below shows fetching a row from index organized table
+``universal_rowids`` and then updating that row by binding its urowid:
+
+.. code-block:: sql
+
+    CREATE TABLE universal_rowids (
+        int_col number(9) not null,
+        str_col varchar2(250) not null,
+        date_col date not null,
+        CONSTRAINT universal_rowids_pk PRIMARY KEY(int_col, str_col, date_col)
+    ) ORGANIZATION INDEX
+
+
+.. code-block:: python
+
+    ridvar = cursor.var(oracledb.DB_TYPE_UROWID)
+
+    # fetch the row
+    cursor.execute("""
+            begin
+                select rowid into :rid from universal_rowids
+                where int_col = 3;
+            end;""", rid=ridvar)
+
+    # update the row by binding UROWID
+    cursor.execute("""
+            update universal_rowids set
+                str_col = :str_val
+            where rowid = :rowid_val""",
+            str_val="String #33", rowid_val=ridvar)
+
+Note that the type :attr:`oracledb.DB_TYPE_UROWID` is only supported in
+python-oracledb Thin mode. For python-oracledb Thick mode, the database type
+UROWID can be bound with type :attr:`oracledb.DB_TYPE_ROWID`.
+See :ref:`querymetadatadiff`.
+
+
 DML RETURNING Bind Variables
 ============================
 

doc/src/user_guide/sql_execution.rst

@@ -239,7 +239,7 @@ Python object that is returned by default. Python types can be changed with
       - :attr:`oracledb.DB_TYPE_TIMESTAMP_TZ`
       - datetime.datetime [2]_
     * - UROWID
-      - :attr:`oracledb.DB_TYPE_ROWID`
+      - :attr:`oracledb.DB_TYPE_ROWID`, :attr:`oracledb.DB_TYPE_UROWID`
       - str
     * - VARCHAR2
       - :attr:`oracledb.DB_TYPE_VARCHAR`

src/oracledb/impl/thin/buffer.pyx

@@ -1016,15 +1016,22 @@ cdef class ReadBuffer:
             const char_type *input_ptr
             bytearray output_value
             uint32_t num_bytes
+            uint8_t length
             Rowid rowid
 
         # check for null
-        self.read_ub4(&num_bytes)
-        if num_bytes == 0:
+        self.read_ub1(&length)
+        if _is_null_length(length):
             return None
 
-        # handle physical rowid
+        if length == 1:
+            self.skip_ub1()
+        else:
+            self.read_ub4(&num_bytes)
+
         self.read_raw_bytes_chunked(&input_ptr, &input_len)
+
+        # handle physical rowid
         if input_ptr[0] == 1:
             rowid.rba = unpack_uint32(&input_ptr[1], BYTE_ORDER_MSB)
             rowid.partition_id = unpack_uint16(&input_ptr[5], BYTE_ORDER_MSB)

src/oracledb/impl/thin/constants.pxi

@@ -621,6 +621,7 @@ DEF TNS_MAX_CURSORS_TO_CLOSE = 500
 DEF TNS_TXN_IN_PROGRESS = 0x00000002
 DEF TNS_MAX_CONNECT_DATA = 230
 DEF TNS_CHUNK_SIZE = 32767
+DEF TNS_MAX_UROWID_LENGTH = 3950
 
 # base 64 encoding alphabet
 DEF TNS_BASE64_ALPHABET = \

src/oracledb/impl/thin/messages.pyx

@@ -537,7 +537,8 @@ cdef class MessageWithData(Message):
         if var_impl.bypass_decode:
             ora_type_num = TNS_DATA_TYPE_RAW
         if buffer_size == 0 and ora_type_num != TNS_DATA_TYPE_LONG \
-                and ora_type_num != TNS_DATA_TYPE_LONG_RAW:
+                and ora_type_num != TNS_DATA_TYPE_LONG_RAW \
+                and ora_type_num != TNS_DATA_TYPE_UROWID:
             column_value = None             # column is null by describe
         elif ora_type_num == TNS_DATA_TYPE_VARCHAR \
                 or ora_type_num == TNS_DATA_TYPE_CHAR \
@@ -557,7 +558,7 @@ cdef class MessageWithData(Message):
             column_value = buf.read_date()
         elif ora_type_num == TNS_DATA_TYPE_ROWID:
             if not self.in_fetch:
-                column_value = buf.read_urowid()
+                column_value = buf.read_str(TNS_CS_IMPLICIT)
             else:
                 buf.read_ub1(&num_bytes)
                 if _is_null_length(num_bytes):
@@ -566,7 +567,10 @@ cdef class MessageWithData(Message):
                     buf.read_rowid(&rowid)
                     column_value = _encode_rowid(&rowid)
         elif ora_type_num == TNS_DATA_TYPE_UROWID:
-            column_value = buf.read_urowid()
+            if not self.in_fetch:
+                column_value = buf.read_str(TNS_CS_IMPLICIT)
+            else:
+                column_value = buf.read_urowid()
         elif ora_type_num == TNS_DATA_TYPE_BINARY_DOUBLE:
             column_value = buf.read_binary_double()
         elif ora_type_num == TNS_DATA_TYPE_BINARY_FLOAT:
@@ -895,11 +899,14 @@ cdef class MessageWithData(Message):
                                     list bind_var_impls) except -1:
         cdef:
             uint8_t ora_type_num, flag
+            uint32_t buffer_size
             ThinVarImpl var_impl
         for var_impl in bind_var_impls:
             ora_type_num = var_impl.dbtype._ora_type_num
-            if ora_type_num == TNS_DATA_TYPE_ROWID:
-                ora_type_num = TNS_DATA_TYPE_UROWID
+            buffer_size = var_impl.buffer_size
+            if ora_type_num in (TNS_DATA_TYPE_ROWID, TNS_DATA_TYPE_UROWID):
+                ora_type_num = TNS_DATA_TYPE_VARCHAR
+                buffer_size = TNS_MAX_UROWID_LENGTH
             flag = TNS_BIND_USE_INDICATORS
             if var_impl.is_array:
                 flag |= TNS_BIND_ARRAY
@@ -909,10 +916,10 @@ cdef class MessageWithData(Message):
             # expects that and complains if any other value is sent!
             buf.write_uint8(0)
             buf.write_uint8(0)
-            if var_impl.buffer_size >= TNS_MIN_LONG_LENGTH:
+            if buffer_size >= TNS_MIN_LONG_LENGTH:
                 buf.write_ub4(TNS_MAX_LONG_LENGTH)
             else:
-                buf.write_ub4(var_impl.buffer_size)
+                buf.write_ub4(buffer_size)
             if var_impl.is_array:
                 buf.write_ub4(var_impl.num_elements)
             else:
@@ -996,6 +1003,9 @@ cdef class MessageWithData(Message):
             num_bytes = <uint32_t> len(lob_impl._locator)
             buf.write_ub4(num_bytes)
             buf.write_bytes_chunked(lob_impl._locator)
+        elif ora_type_num in (TNS_DATA_TYPE_ROWID, TNS_DATA_TYPE_UROWID):
+            temp_bytes = (<str> value).encode()
+            buf.write_bytes_chunked(temp_bytes)
         else:
             errors._raise_err(errors.ERR_DB_TYPE_NOT_SUPPORTED,
                               name=var_impl.dbtype.name)

tests/test_1500_types.py

@@ -194,5 +194,10 @@ def test_1528_ROWID(self):
         "1528 - test oracledb.ROWID pickling"
         self.__test_pickle(oracledb.ROWID)
 
+    def test_1529_DB_TYPE_UROWID(self):
+        "1529 - test oracledb.DB_TYPE_UROWID comparisons and pickling"
+        self.__test_compare(oracledb.DB_TYPE_UROWID, oracledb.ROWID)
+        self.__test_pickle(oracledb.DB_TYPE_UROWID)
+
 if __name__ == "__main__":
     test_env.run_test_cases()

tests/test_2900_rowid.py

@@ -27,6 +27,7 @@
 """
 
 import datetime
+import unittest
 
 import oracledb
 import test_env
@@ -84,5 +85,90 @@ def test_2903_select_rowids_as_urowids(self):
                     val=rowid)
             self.assertEqual(self.cursor.fetchall(), [(int_val,)])
 
+    def test_2904_select_rowids_as_rowids(self):
+        "2904 - test selecting regular rowids stored in a rowid column"
+        self.cursor.execute("truncate table TestRowids")
+        self.cursor.execute("""
+                insert into TestRowids (IntCol, RowidCol)
+                select IntCol, rowid from TestNumbers""")
+        self.connection.commit()
+        self.cursor.execute("select IntCol, RowidCol from TestRowids")
+        for int_val, rowid in self.cursor.fetchall():
+            self.cursor.execute("""
+                    select IntCol
+                    from TestNumbers
+                    where rowid = :val""",
+                    val=rowid)
+            self.assertEqual(self.cursor.fetchall(), [(int_val,)])
+
+    def test_2905_test_bind_and_insert_rowid(self):
+        "2905 - binding and inserting a rowid"
+        self.cursor.execute("truncate table TestRowids")
+        insert_data = [
+            (1, "String #1"), (2, "String #2"),
+            (3, "String #3"),(4, "String #4")
+        ]
+        self.cursor.execute("truncate table TestTempTable")
+        sql = "insert into TestTempTable (IntCol, StringCol1) values (:1, :2)"
+        self.cursor.executemany(sql, insert_data)
+        self.connection.commit()
+        ridvar = self.cursor.var(oracledb.ROWID)
+        self.cursor.execute("""
+            begin
+                select rowid into :rid from TestTempTable
+                where IntCol = 3;
+            end;""",
+            rid=ridvar)
+        self.cursor.setinputsizes(r1=oracledb.ROWID)
+        self.cursor.execute("""
+            insert into TestRowids (IntCol, RowidCol)
+            values(1, :r1)""",
+            r1=ridvar)
+        self.connection.commit()
+        self.cursor.execute("select IntCol, RowidCol from TestRowids")
+        int_val, rowid = self.cursor.fetchone()
+        self.cursor.execute("""
+            select IntCol, StringCol1 from TestTempTable
+            where rowid = :val""",
+            val=rowid)
+        self.assertEqual(self.cursor.fetchone(), (3, "String #3"))
+
+    @unittest.skipIf(not test_env.get_is_thin(),
+                     "thick mode doesn't support DB_TYPE_UROWID")
+    def test_2906_test_bind_and_insert_rowid_as_urowid(self):
+        "2906 - binding and inserting a rowid as urowid"
+        self.cursor.execute("truncate table TestRowids")
+        insert_data = [
+            (1, "String #1", datetime.datetime(2017, 4, 4)),
+            (2, "String #2", datetime.datetime(2017, 4, 5)),
+            (3, "String #3", datetime.datetime(2017, 4, 6)),
+            (4, "A" * 250, datetime.datetime(2017, 4, 7))
+        ]
+        self.cursor.execute("truncate table TestUniversalRowids")
+        sql = "insert into TestUniversalRowids values (:1, :2, :3)"
+        self.cursor.executemany(sql, insert_data)
+        self.connection.commit()
+        ridvar = self.cursor.var(oracledb.DB_TYPE_UROWID)
+        self.cursor.execute("""
+            begin
+                select rowid into :rid from TestUniversalRowids
+                where IntCol = 3;
+            end;""",
+            rid=ridvar)
+        self.cursor.setinputsizes(r1=oracledb.DB_TYPE_UROWID)
+        self.cursor.execute("""
+            insert into TestRowids (IntCol, UrowidCol)
+            values(1, :r1)""",
+            r1=ridvar)
+        self.connection.commit()
+        self.cursor.execute("select IntCol, UrowidCol from TestRowids")
+        int_val, rowid = self.cursor.fetchone()
+        self.cursor.execute("""
+            select IntCol, StringCol, DateCol from TestUniversalRowids
+            where rowid = :val""",
+            val=rowid)
+        self.assertEqual(self.cursor.fetchone(),
+                         (3, "String #3", datetime.datetime(2017, 4, 6)))
+
 if __name__ == "__main__":
     test_env.run_test_cases()