Add samples and improve documentation.

oracle · Jul 19, 2024 · 7d364ea · 7d364ea
1 parent 10e19b8
commit 7d364ea
Show file tree

Hide file tree

Showing 12 changed files with 570 additions and 172 deletions.
diff --git a/doc/src/api_manual/module.rst b/doc/src/api_manual/module.rst
@@ -332,13 +332,14 @@ Oracledb Methods
     Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the
-    database after a connection has been established.  This feature is only
-    available with certain versions of ADB-S.  This value is used in both
-    python-oracledb Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -347,7 +348,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
@@ -605,13 +606,14 @@ Oracledb Methods
     the python-oracledb Thin and Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the
-    database after a connection has been established.  This feature is only
-    available with certain versions of ADB-S.  This value is used in both
-    python-oracledb Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -620,7 +622,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     The ``handle`` parameter is ignored in the python-oracledb Thin mode.
 
@@ -903,13 +905,14 @@ Oracledb Methods
     Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the
-    database after a connection has been established.  This feature is only
-    available with certain versions of ADB-S.  This value is used in both
-    python-oracledb Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -918,7 +921,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the
@@ -1303,13 +1306,14 @@ Oracledb Methods
     Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the database
-    after a connection has been established.  This feature is only available
-    with certain versions of ADB-S.  This value is used in both python-oracledb
-    Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -1318,7 +1322,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     If the ``handle`` parameter is specified, it must be of type OCISvcCtx\*
     and is only of use when embedding Python in an application (like
@@ -1643,13 +1647,14 @@ Oracledb Methods
     the python-oracledb Thin and Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the database
-    after a connection has been established.  This feature is only available
-    with certain versions of ADB-S.  This value is used in both python-oracledb
-    Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -1658,7 +1663,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     The ``handle`` parameter is ignored in the python-oracledb Thin mode.
 
@@ -2110,13 +2115,14 @@ Oracledb Methods
     Thick modes.
 
     The ``use_tcp_fast_open`` parameter is expected to be a boolean which
-    indicates whether to use an `Oracle Autonomous Database Serverless (ADB-S)
-    <https://docs.oracle.com/en/cloud/paas/autonomous-database/serverless/
-    adbsb/adbsb-overview.html#GUID-A7435462-9D74-44B4-8240-4A6F06E92348>`__
-    specific feature that can reduce the latency in round-trips to the database
-    after a connection has been established.  This feature is only available
-    with certain versions of ADB-S.  This value is used in both python-oracledb
-    Thin and Thick modes.  The default value is False.
+    indicates whether to use TCP Fast Open which is an `Oracle Autonomous
+    Database Serverless (ADB-S) <https://docs.oracle.com/en/cloud/paas/
+    autonomous-database/serverless/adbsb/connection-tcp-fast-open.html#
+    GUID-34654005-DBBA-4C49-BC6D-717F9C16A17C>`__ specific feature that can
+    reduce the latency in round-trips to the database after a connection has
+    been established.  This feature is only available with certain versions of
+    ADB-S.  This value is used in both python-oracledb Thin and Thick modes.
+    The default value is False.
 
     The ``ssl_version`` parameter is expected to be one of the constants
     "ssl.TLSVersion.TLSv1_2" or "ssl.TLSVersion.TLSv1_3" and specifies the TLS
@@ -2125,7 +2131,7 @@ Oracledb Methods
     parameter can be specified when establishing connections with the protocol
     "tcps".  This parameter is used in both python-oracledb Thin and Thick
     modes.  The value "ssl.TLSVersion.TLSv1_3" requires Oracle Database 23ai
-    and for Thick mode, Oracle Client 19c (or later) is additionally required.
+    and for Thick mode, Oracle Client 23ai is additionally required.
 
     The ``handle`` parameter is expected to be an integer which represents a
     pointer to a valid service context handle. This value is only used in the

diff --git a/doc/src/api_manual/soda.rst b/doc/src/api_manual/soda.rst
@@ -10,6 +10,11 @@ allows documents to be inserted, queried, and retrieved from Oracle Database
 using a set of NoSQL-style python-oracledb methods. By default, documents are JSON
 strings. See the :ref:`user manual <sodausermanual>` for examples.
 
+.. note::
+
+    SODA is only supported in the python-oracledb Thick mode.  See
+    :ref:`enablingthick`.
+
 .. _sodarequirements:
 
 SODA Requirements
@@ -30,51 +35,53 @@ SODA requires Oracle Client 18.3 or higher and Oracle Database 18.1 and higher.
 
 .. note::
 
-    If you are using Oracle Database 21c (or later) and create new collections
-    you need to do one of the following:
-
-    - Use Oracle Client libraries 21c (or later)
-
-    - Or explicitly use collection metadata when creating collections and set
-      the data storage type to BLOB, for example::
-
-        {
-            "keyColumn": {
-                "name":"ID"
-            },
-            "contentColumn": {
-                "name": "JSON_DOCUMENT",
-                "sqlType": "BLOB"
-            },
-            "versionColumn": {
-                "name": "VERSION",
-                "method": "UUID"
-            },
-            "lastModifiedColumn": {
-                "name": "LAST_MODIFIED"
-            },
-            "creationTimeColumn": {
-                "name": "CREATED_ON"
-            }
+    SODA APIs are only supported in the python-oracledb Thick mode. See
+    :ref:`enablingthick`.
+
+
+If you are using Oracle Database 21c (or later) and create new collections
+you need to do one of the following:
+
+- Use Oracle Client libraries 21c (or later)
+
+- Or explicitly use collection metadata when creating collections and set
+  the data storage type to BLOB, for example::
+
+    {
+        "keyColumn": {
+            "name":"ID"
+        },
+        "contentColumn": {
+            "name": "JSON_DOCUMENT",
+            "sqlType": "BLOB"
+        },
+        "versionColumn": {
+            "name": "VERSION",
+            "method": "UUID"
+        },
+        "lastModifiedColumn": {
+            "name": "LAST_MODIFIED"
+        },
+        "creationTimeColumn": {
+            "name": "CREATED_ON"
         }
+    }
 
-    - Or, set the database initialization parameter `compatible
-      <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
-      id=GUID-A2E90F08-BC9F-4688-A9D0-4A948DD3F7A9>`__ to 19 or lower.
+- Or set the database initialization parameter `compatible
+  <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+  id=GUID-A2E90F08-BC9F-4688-A9D0-4A948DD3F7A9>`__ to 19.0.0 or lower
 
-    Otherwise, you may get errors such as ``ORA-40842: unsupported value JSON in
-    the metadata for the field sqlType`` or ``ORA-40659: Data type does not match
-    the specification in the collection metadata``.
+Otherwise, you may get errors such as ``ORA-40842: unsupported value JSON in
+the metadata for the field sqlType`` or ``ORA-40659: Data type does not match
+the specification in the collection metadata``.
 
 .. _sodadb:
 
 SodaDatabase Objects
 ====================
 
-.. note::
-
-    The SODA Database object is an extension the DB API. It is returned by the
-    method :meth:`Connection.getSodaDatabase()`.
+The SODA Database object is an extension to the DB API. It is returned by the
+method :meth:`Connection.getSodaDatabase()`.
 
 
 SodaDatabase Methods
@@ -152,12 +159,10 @@ SodaDatabase Methods
 SodaCollection Objects
 ======================
 
-.. note::
-
-    The SODA Collection object is an extension the DB API. It is used to
-    represent SODA collections and is created by methods
-    :meth:`SodaDatabase.createCollection()` and
-    :meth:`SodaDatabase.openCollection()`.
+The SODA Collection object is an extension to the DB API. It is used to
+represent SODA collections and is created by methods
+:meth:`SodaDatabase.createCollection()` and
+:meth:`SodaDatabase.openCollection()`.
 
 SodaCollection Methods
 ----------------------
@@ -361,12 +366,10 @@ SodaCollection Attributes
 SodaDoc Objects
 ===============
 
-.. note::
-
-    The SODA Document object is an extension the DB API. It is returned by the
-    methods :meth:`SodaDatabase.createDocument()`,
-    :meth:`SodaOperation.getDocuments()` and :meth:`SodaOperation.getOne()` as
-    well as by iterating over :ref:`SODA document cursors <sodadoccur>`.
+The SODA Document object is an extension to the DB API. It is returned by the
+methods :meth:`SodaDatabase.createDocument()`,
+:meth:`SodaOperation.getDocuments()` and :meth:`SodaOperation.getOne()` as
+well as by iterating over :ref:`SODA document cursors <sodadoccur>`.
 
 SodaDoc Methods
 ---------------
@@ -440,12 +443,10 @@ SodaDoc Attributes
 SodaDocCursor Objects
 =====================
 
-.. note::
-
-    The SODA Document Cursor object is an extension the DB API. It is returned
-    by the method :meth:`SodaOperation.getCursor()` and implements the iterator
-    protocol.  Each iteration will return a :ref:`SODA document object
-    <sodadoc>`.
+The SODA Document Cursor object is an extension to the DB API. It is returned
+by the method :meth:`SodaOperation.getCursor()` and implements the iterator
+protocol.  Each iteration will return a :ref:`SODA document object
+<sodadoc>`.
 
 SodaDocCursor Methods
 ---------------------
@@ -462,11 +463,9 @@ SodaDocCursor Methods
 SodaOperation Objects
 =====================
 
-.. note::
-
-    The SODA Operation Object is an extension to the DB API. It represents an
-    operation that will be performed on all or some of the documents in a SODA
-    collection. It is created by the method :meth:`SodaCollection.find()`.
+The SODA Operation Object is an extension to the DB API. It represents an
+operation that will be performed on all or some of the documents in a SODA
+collection. It is created by the method :meth:`SodaCollection.find()`.
 
 SodaOperation Methods
 ---------------------