Add documentation and test updates

Author: sharadraju

doc/src/api_manual/connection.rst

@@ -1159,9 +1159,9 @@ Connection Methods
             - ``dbType``: one of the :ref:`Oracle Database Type Constant <oracledbconstantsdbtype>` values.
             - ``dbTypeClass``: The class associated with the database type. This is only set if the database type is an object type.
             - ``dbTypeName``: The name of the database type, such as “NUMBER” or “VARCHAR2”. For object types, this will be the object name.
-            - ``domainName``: The name of the `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a SQL domain, this property value is `undefined`. SQL domains are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
+            - ``domainName``: The name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this property value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
 
-            - ``domainSchema``: The schema name of the `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a SQL domain, this property value is `undefined`. SQL domains are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
+            - ``domainSchema``: The schema name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched column. If the column does not have a data use case domain, this property value is `undefined`. `Data use case domains <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-4743FDE1-7C6E-471B-BC9D-442383CCA2F9>`__ are supported from Oracle Database 23ai onwards. If node-oracledb Thick mode is used, Oracle Client 23ai is also required.
 
             - ``fetchType``: One of the :ref:`Node-oracledb Type Constant <oracledbconstantsnodbtype>` values.
             - ``isJson``: Indicates if the column is known to contain JSON data. This will be ``true`` for JSON columns (from Oracle Database 21c) and for LOB and VARCHAR2 columns where "IS JSON" constraint is enabled (from Oracle Database 19c). This property will be ``false`` for all the other columns. It will also be ``false`` for any column when Oracle Client 18c or earlier is used in Thick mode or the Oracle Database version is earlier than 19c.

doc/src/api_manual/oracledb.rst

@@ -1132,8 +1132,8 @@ Each of the configuration properties is described below.
       "VARCHAR2".
     - ``dbTypeClass``: The class associated with the database type. This is
       only set if ``dbType`` is ``oracledb.DB_TYPE_OBJECT``.
-    - ``domainName``: The name of the `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__.
-    - ``domainSchema``: The schema name of the `SQL domain <https://docs.oracle.com/en/database/oracle/oracle-database/23/sqlrf/create-domain.html#GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__.
+    - ``domainName``: The name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__.
+    - ``domainSchema``: The schema name of the `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__.
     - ``isJson``: Indicates if the column is known to contain JSON data.
     - ``name``: The name of the column.
     - ``nullable``: Indicates whether ``NULL`` values are permitted for this
@@ -1450,8 +1450,8 @@ Each of the configuration properties is described below.
     connection has been released back to the pool. The pending connection
     request will consume one worker thread.
 
-    See :ref:`Connecting to Sharded Databases <sharding>` for more
-    information.
+    See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`
+    for more information.
 
     .. note::
 
@@ -3173,7 +3173,7 @@ Oracledb Methods
           - Thick
           - .. _getconnectiondbattrsshardingkey:
 
-            Allows a connection to be established directly to a database shard. See :ref:`Connecting to Sharded Databases <sharding>`.
+            Allows a connection to be established directly to a database shard. See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`.
 
             Array values may be of String type (mapping to VARCHAR2 sharding keys), Number (NUMBER), Date (DATE), or Buffer (RAW). Multiple types may be used in the array. Sharding keys TIMESTAMP type are not supported.
 
@@ -3189,7 +3189,7 @@ Oracledb Methods
           - Thick
           - .. _getconnectiondbattrssupershardingkey:
 
-            Allows a connection to be established directly to a database shard. See :ref:`Connecting to Sharded Databases <sharding>`.
+            Allows a connection to be established directly to a database shard. See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`.
 
             Array values may be of String type (mapping to VARCHAR2 sharding keys), Number (NUMBER), Date (DATE), or Buffer (RAW). Multiple types may be used in the array. Sharding keys TIMESTAMP type are not supported.
 

doc/src/api_manual/pool.rst

@@ -447,7 +447,7 @@ Pool Methods
           - Description
         * - ``poolAttrs``
           - Object
-          - This parameter can contain a ``tag`` property when :ref:`connection tagging <connpooltagging>` is in use. It can also contain :ref:`shardingKey <getconnectiondbattrsshardingkey>` and :ref:`superShardingKey <getconnectiondbattrssupershardingkey>` properties, when using :ref:`database sharding <sharding>`.
+          - This parameter can contain a ``tag`` property when :ref:`connection tagging <connpooltagging>` is in use. It can also contain :ref:`shardingKey <getconnectiondbattrsshardingkey>` and :ref:`superShardingKey <getconnectiondbattrssupershardingkey>` properties, when using :ref:`Oracle Globally Distributed Database <sharding>`.
 
             When getting connections from heterogeneous pools, this parameter can contain ``user`` (or ``username``) and ``password`` properties for true heterogeneous pool usage, or it can contain a ``user`` property when a pool proxy user is desired.
 

doc/src/user_guide/appendix_a.rst

@@ -80,7 +80,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
     * - Real Application Clusters (RAC) (see :ref:`connectionrac`)
       - Yes
       - Yes
-    * - Oracle Sharded Databases (see :ref:`sharding`)
+    * - Oracle Globally Distributed Database - previously known as Oracle Sharded Databases (see :ref:`sharding`)
       - No
       - Yes - No TIMESTAMP support
     * - Connection Pool Connection Load Balancing (CLB)

doc/src/user_guide/connection_handling.rst

@@ -4725,22 +4725,29 @@ when configuration information from this configuration provider is required.
 
 .. _sharding:
 
-Connecting to Sharded Databases
-===============================
-
-`Oracle Sharding <https://www.oracle.com/database/technologies/high-
-availability/sharding.html>`__ can be used to horizontally partition data
-across independent databases. A database table can be split so each shard
+Connecting to Oracle Globally Distributed Database
+==================================================
+
+`Oracle Globally Distributed Database <https://www.oracle.com/database/
+distributed-database/>`__ is a feature of Oracle Database that lets you
+automatically distribute and replicate data across a pool of Oracle databases
+that share no hardware or software. It was previously known as Oracle
+Sharding. It allows a database table to be split so that each database
 contains a table with the same columns but a different subset of rows. These
-tables are known as sharded tables. Sharding is configured in Oracle Database,
-see the `Oracle Sharding <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
-id=SHARD>`__ manual. Sharding requires Oracle Database and client libraries 12.2,
-or later.
+tables are known as sharded tables. From the perspective of an application, a
+sharded table in Oracle Globally Distributed Database looks like a single
+table: the distribution of data across those shards is completely transparent
+to the application.
+
+Sharding is configured in Oracle Database, see the `Oracle Globally
+Distributed Database <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
+SHARD>`__ manual. It requires Oracle Database and Oracle Client libraries
+12.2, or later.
 
 .. note::
 
-    In this release, sharding is only supported in the node-oracledb Thick
-    mode. See :ref:`enablingthick`.
+    In this release, Oracle Globally Distributed Database is only supported in
+    the node-oracledb Thick mode. See :ref:`enablingthick`.
 
 When a connection is opened in node-oracledb using
 :meth:`oracledb.getConnection()`, the
@@ -4768,11 +4775,11 @@ to VARCHAR2 sharding keys), Number (NUMBER), Date (DATE), or Buffer (RAW).
 Multiple types may be used in each array. Sharding keys of TIMESTAMP type
 are not supported by node-oracledb.
 
-Examples to Connect to a Shard Based on the Sharding Key Type
--------------------------------------------------------------
+Examples to Connect to a Globally Distributed Database Based on the Sharding Key Type
+-------------------------------------------------------------------------------------
 
-The examples listed in this section show how to establish connections to a
-database shard based on the sharding key type.
+The examples listed in this section show how to establish connections to an
+Oracle Globally Distributed Database based on the sharding key type.
 
 **VARCHAR2**
 

doc/src/user_guide/globalization.rst

@@ -53,6 +53,122 @@ Setting the Client Character Set
 
 In node-oracledb, the encoding used for all character data is AL32UTF8.
 
+.. _oratzfile:
+
+Time Zone Files
+===============
+
+This section is only applicable to node-oracledb Thick mode.
+
+Oracle Client libraries and Oracle Database use time zone files for date
+operations. The files are versioned, but do not always have to be the same
+version on the database and client. The name of the Oracle time zone file to
+use can be set in the ``ORA_TZFILE`` environment variable.
+
+Finding the Time Zone Files in Use
+----------------------------------
+
+You can find the time zone file used by the database itself by executing the
+following query:
+
+.. code-block:: sql
+
+    SQL> SELECT * FROM v$timezone_file;
+
+    FILENAME                VERSION     CON_ID
+    -------------------- ---------- ----------
+    timezlrg_43.dat              43          0
+
+The time zone files on the client side can be shown by running the utility
+``genezi -v``.  In Instant Client, this is in the Basic and Basic Light
+packages.  The output will be like::
+
+    $ genezi -v
+
+    . . .
+
+    TIMEZONE INFORMATION
+    --------------------
+    Operating in Instant Client mode.
+
+    Small timezone file = /opt/oracle/instantclient/oracore/zoneinfo/timezone_43.dat
+    Large timezone file = /opt/oracle/instantclient/oracore/zoneinfo/timezlrg_43.dat
+
+With Instant Client, the paths refer to a virtual file system in the Oracle
+libraries. These files are not present on the OS file system.
+
+The larger file ``timezlrg_<n>.dat`` contains all time zone information. This
+is the file used by default.  The smaller ``timezone_<n>.dat`` file contains
+only the most commonly used time zones. See `Time Zone Region Names <https://
+www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-21D14370-A707-4482-A3FE-
+9277263F292A>`__ for more information.
+
+The filenames shows the version of the time zone files, in this example it is
+version 43.
+
+The Oracle Database documentation contains more information about time zone
+files, see `Choosing a Time Zone File <https://www.oracle.com/pls/topic/
+lookup?ctx=dblatest&id=GUID-805AB986-DE12-4FEA-AF56-5AABCD2132DF>`__.
+
+Changing the Oracle Client Time Zone File
+-----------------------------------------
+
+You can get updated time zone files from a full Oracle Database installation,
+or by downloading a patch from `Oracle Support <https://support.oracle.com/>`_.
+For use with Instant Client, unzip the patch and copy the necessary files:
+installing the patch itself will not work.
+
+**Using a New Time Zone File in Instant Client**
+
+From Oracle Instant Client 12.2, you can use an external time zone file,
+allowing you to update time zone information without updating the complete
+Instant Client installation. Changing the file in earlier versions of Instant
+Client is not possible.
+
+To change the time zone file, do one of the following:
+
+- Create a subdirectory ``oracore/zoneinfo`` under the Instant Client
+  directory and move the file into it.  Then set ``ORA_TZFILE`` to the file
+  name, without any absolute or relative directory prefix prefix.  For
+  example, if Instant Client is in ``/opt/oracle/instantclient``::
+
+    mkdir -p /opt/oracle/instantclient/oracore/zoneinfo
+    cp timezone_43.dat /opt/oracle/instantclient/oracore/zoneinfo/
+    export ORA_TZFILE=timezone_43.dat
+
+- Alternatively, from Oracle Instant Client 19.18 onwards, you can place the
+  external time zone file in any directory and then set the ``ORA_TZFILE``
+  environment variable to the absolute path of the file. For example::
+
+    mkdir -p /opt/oracle/myconfig
+    cp timezone_43.dat /opt/oracle/myconfig/
+    export ORA_TZFILE=/opt/oracle/myconfig/timezone_43.dat
+
+After installing a new client time zone file, run ``genezi -v`` again to check
+if it is readable.
+
+**Using the Embedded Small Time Zone File in Instant Client**
+
+By default, Instant Client uses its larger embedded ``timezlrg_<n>.dat`` file.
+If you want to use the smaller embedded ``timezone_<n>.dat`` file, then set the
+``ORA_TZFILE`` environment variable to the name of the file without any
+absolute or relative directory prefix. For example::
+
+    export ORA_TZFILE=timezone_43.dat
+
+**Using a New Time Zone File in a Full Oracle Client**
+
+If node-oracledb Thick mode is using Oracle Client libraries from a full
+Oracle Client software installation (such as installed with Oracle's GUI
+installer), and you want to use a non-default time zone file, then set
+``ORA_TZFILE`` to the file name with an absolute path directory prefix. For
+example::
+
+    export ORA_TZFILE=/opt/oracle/myconfig/timezone_43.dat
+
+This also works if node-oracledb Thick mode is using libraries from an Oracle
+Database installation.
+
 Setting the Client Locale
 =========================
 

doc/src/user_guide/initialization.rst

@@ -492,46 +492,6 @@ explicitly specified or a default location will be used.  Do one of:
     installation, in ``$ORACLE_HOME/network/admin`` or
     ``$ORACLE_BASE_HOME/network/admin``.
 
-.. _oratzfile:
-
-Using the Optional Time Zone File
----------------------------------
-
-The name of the Oracle time zone file to use can be set in
-``ORA_TZFILE``.
-
-.. note::
-
-    The Oracle time zone file and ``ORA_TZFILE`` environment variable are only
-    used in the node-oracledb Thick mode.
-
-If node-oracledb is using Oracle Client libraries from an Oracle
-Database or full Oracle Client software installation, and you want to
-use a non-default time zone file, then set ``ORA_TZFILE`` to the file
-name with a directory prefix, for example:
-``export ORA_TZFILE=/opt/oracle/myconfig/timezone_31.dat``.
-
-Oracle Instant Client includes embedded small and big time zone ‘files’,
-for example ``timezone_32.dat`` and ``timezlrg_32.dat``. The versions
-can be shown by running the utility ``genezi -v`` located in the Instant
-Client directory. The small file contains only the most commonly used
-time zones. By default the larger ``timezlrg_n.dat`` file is used. If
-you want to use the smaller ``timezone_n.dat`` file, then set the
-``ORA_TZFILE`` environment variable to the name of the file without any
-directory prefix, for example ``export ORA_TZFILE=timezone_32.dat``.
-From Oracle Instant Client 12.2, you can also use an external time zone
-file. Create a subdirectory ``oracore/zoneinfo`` under the Instant Client
-directory, and move the file into it. Then set ``ORA_TZFILE`` to the file
-name, without any directory prefix. The ``genezi -v`` utility will show
-the time zone file in use. With Oracle Instant Client 19.18 (or later), you
-can alternatively place the external time zone file in any directory and then
-set the ``ORA_TZFILE`` environment variable to the absolute path of the file.
-
-The Oracle Database documentation contains more information about time
-zone files, see `Choosing a Time Zone
-File <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-805AB986-
-DE12-4FEA-AF56-5AABCD2132DF>`__.
-
 .. _environmentvariables:
 
 Oracle Environment Variables for node-oracledb Thick Mode

doc/src/user_guide/migrate.rst

@@ -155,12 +155,13 @@ Upgrading from node-oracledb 6.2 to 6.3
   ``annotations``, ``domainName``, and ``domainSchema`` identifies the
   `annotations <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
   GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object, the name of the
-  `SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
-  GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`_, and the schema name of the
-  `SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
-  GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched
-  column. Annotations and SQL domains are supported from Oracle Database 23ai
-  onwards. For node-oracledb Thick mode, Oracle Client 23ai is also required.
+  `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+  id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`_, and the schema name of the
+  `data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
+  id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched
+  column. Annotations and data use case domains are supported from Oracle
+  Database 23ai onwards. For node-oracledb Thick mode, Oracle Client 23ai is
+  also required.
 
 - In node-oracledb Thin mode, ``SYS.XMLTYPE`` data can now be
   :ref:`fetched as strings <xmltype>`.

test/binding.js

@@ -766,7 +766,7 @@ describe('4. binding.js', function() {
           await connection.execute(sql, {ROWID: 1});
         },
         //NJS-098: 1 positional bind values are required but 0 were provided
-        /ORA-01745:|NJS-098:/
+        /ORA-01745:/
       );
     });