Skip to content

Commit 7d65266

Browse files
sharadrajusharadraju
committed
Add documentation and test updates
1 parent 606bb9c commit 7d65266

File tree

12 files changed

+302
-174
lines changed

12 files changed

+302
-174
lines changed

‎doc/src/api_manual/connection.rst

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1159,9 +1159,9 @@ Connection Methods
11591159
- ``dbType``: one of the :ref:`Oracle Database Type Constant <oracledbconstantsdbtype>` values.
11601160
- ``dbTypeClass``: The class associated with the database type. This is only set if the database type is an object type.
11611161
- ``dbTypeName``: The name of the database type, such as “NUMBER” or “VARCHAR2”. For object types, this will be the object name.
1162-
- ``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.
1162+
- ``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.
11631163

1164-
- ``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.
1164+
- ``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.
11651165

11661166
- ``fetchType``: One of the :ref:`Node-oracledb Type Constant <oracledbconstantsnodbtype>` values.
11671167
- ``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

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1132,8 +1132,8 @@ Each of the configuration properties is described below.
11321132
"VARCHAR2".
11331133
- ``dbTypeClass``: The class associated with the database type. This is
11341134
only set if ``dbType`` is ``oracledb.DB_TYPE_OBJECT``.
1135-
- ``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>`__.
1136-
- ``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>`__.
1135+
- ``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>`__.
1136+
- ``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>`__.
11371137
- ``isJson``: Indicates if the column is known to contain JSON data.
11381138
- ``name``: The name of the column.
11391139
- ``nullable``: Indicates whether ``NULL`` values are permitted for this
@@ -1450,8 +1450,8 @@ Each of the configuration properties is described below.
14501450
connection has been released back to the pool. The pending connection
14511451
request will consume one worker thread.
14521452

1453-
See :ref:`Connecting to Sharded Databases <sharding>` for more
1454-
information.
1453+
See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`
1454+
for more information.
14551455

14561456
.. note::
14571457

@@ -3173,7 +3173,7 @@ Oracledb Methods
31733173
- Thick
31743174
- .. _getconnectiondbattrsshardingkey:
31753175

3176-
Allows a connection to be established directly to a database shard. See :ref:`Connecting to Sharded Databases <sharding>`.
3176+
Allows a connection to be established directly to a database shard. See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`.
31773177

31783178
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.
31793179

@@ -3189,7 +3189,7 @@ Oracledb Methods
31893189
- Thick
31903190
- .. _getconnectiondbattrssupershardingkey:
31913191

3192-
Allows a connection to be established directly to a database shard. See :ref:`Connecting to Sharded Databases <sharding>`.
3192+
Allows a connection to be established directly to a database shard. See :ref:`Connecting to Oracle Globally Distributed Database <sharding>`.
31933193

31943194
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.
31953195

‎doc/src/api_manual/pool.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -447,7 +447,7 @@ Pool Methods
447447
- Description
448448
* - ``poolAttrs``
449449
- Object
450-
- 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>`.
450+
- 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>`.
451451

452452
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.
453453

‎doc/src/user_guide/appendix_a.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,7 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
8080
* - Real Application Clusters (RAC) (see :ref:`connectionrac`)
8181
- Yes
8282
- Yes
83-
* - Oracle Sharded Databases (see :ref:`sharding`)
83+
* - Oracle Globally Distributed Database - previously known as Oracle Sharded Databases (see :ref:`sharding`)
8484
- No
8585
- Yes - No TIMESTAMP support
8686
* - Connection Pool Connection Load Balancing (CLB)

‎doc/src/user_guide/connection_handling.rst

Lines changed: 23 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -4725,22 +4725,29 @@ when configuration information from this configuration provider is required.
47254725
47264726
.. _sharding:
47274727
4728-
Connecting to Sharded Databases
4729-
===============================
4730-
4731-
`Oracle Sharding <https://www.oracle.com/database/technologies/high-
4732-
availability/sharding.html>`__ can be used to horizontally partition data
4733-
across independent databases. A database table can be split so each shard
4728+
Connecting to Oracle Globally Distributed Database
4729+
==================================================
4730+
4731+
`Oracle Globally Distributed Database <https://www.oracle.com/database/
4732+
distributed-database/>`__ is a feature of Oracle Database that lets you
4733+
automatically distribute and replicate data across a pool of Oracle databases
4734+
that share no hardware or software. It was previously known as Oracle
4735+
Sharding. It allows a database table to be split so that each database
47344736
contains a table with the same columns but a different subset of rows. These
4735-
tables are known as sharded tables. Sharding is configured in Oracle Database,
4736-
see the `Oracle Sharding <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
4737-
id=SHARD>`__ manual. Sharding requires Oracle Database and client libraries 12.2,
4738-
or later.
4737+
tables are known as sharded tables. From the perspective of an application, a
4738+
sharded table in Oracle Globally Distributed Database looks like a single
4739+
table: the distribution of data across those shards is completely transparent
4740+
to the application.
4741+
4742+
Sharding is configured in Oracle Database, see the `Oracle Globally
4743+
Distributed Database <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
4744+
SHARD>`__ manual. It requires Oracle Database and Oracle Client libraries
4745+
12.2, or later.
47394746
47404747
.. note::
47414748
4742-
In this release, sharding is only supported in the node-oracledb Thick
4743-
mode. See :ref:`enablingthick`.
4749+
In this release, Oracle Globally Distributed Database is only supported in
4750+
the node-oracledb Thick mode. See :ref:`enablingthick`.
47444751
47454752
When a connection is opened in node-oracledb using
47464753
:meth:`oracledb.getConnection()`, the
@@ -4768,11 +4775,11 @@ to VARCHAR2 sharding keys), Number (NUMBER), Date (DATE), or Buffer (RAW).
47684775
Multiple types may be used in each array. Sharding keys of TIMESTAMP type
47694776
are not supported by node-oracledb.
47704777
4771-
Examples to Connect to a Shard Based on the Sharding Key Type
4772-
-------------------------------------------------------------
4778+
Examples to Connect to a Globally Distributed Database Based on the Sharding Key Type
4779+
-------------------------------------------------------------------------------------
47734780
4774-
The examples listed in this section show how to establish connections to a
4775-
database shard based on the sharding key type.
4781+
The examples listed in this section show how to establish connections to an
4782+
Oracle Globally Distributed Database based on the sharding key type.
47764783
47774784
**VARCHAR2**
47784785

‎doc/src/user_guide/globalization.rst

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,122 @@ Setting the Client Character Set
5353

5454
In node-oracledb, the encoding used for all character data is AL32UTF8.
5555

56+
.. _oratzfile:
57+
58+
Time Zone Files
59+
===============
60+
61+
This section is only applicable to node-oracledb Thick mode.
62+
63+
Oracle Client libraries and Oracle Database use time zone files for date
64+
operations. The files are versioned, but do not always have to be the same
65+
version on the database and client. The name of the Oracle time zone file to
66+
use can be set in the ``ORA_TZFILE`` environment variable.
67+
68+
Finding the Time Zone Files in Use
69+
----------------------------------
70+
71+
You can find the time zone file used by the database itself by executing the
72+
following query:
73+
74+
.. code-block:: sql
75+
76+
SQL> SELECT * FROM v$timezone_file;
77+
78+
FILENAME VERSION CON_ID
79+
-------------------- ---------- ----------
80+
timezlrg_43.dat 43 0
81+
82+
The time zone files on the client side can be shown by running the utility
83+
``genezi -v``. In Instant Client, this is in the Basic and Basic Light
84+
packages. The output will be like::
85+
86+
$ genezi -v
87+
88+
. . .
89+
90+
TIMEZONE INFORMATION
91+
--------------------
92+
Operating in Instant Client mode.
93+
94+
Small timezone file = /opt/oracle/instantclient/oracore/zoneinfo/timezone_43.dat
95+
Large timezone file = /opt/oracle/instantclient/oracore/zoneinfo/timezlrg_43.dat
96+
97+
With Instant Client, the paths refer to a virtual file system in the Oracle
98+
libraries. These files are not present on the OS file system.
99+
100+
The larger file ``timezlrg_<n>.dat`` contains all time zone information. This
101+
is the file used by default. The smaller ``timezone_<n>.dat`` file contains
102+
only the most commonly used time zones. See `Time Zone Region Names <https://
103+
www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-21D14370-A707-4482-A3FE-
104+
9277263F292A>`__ for more information.
105+
106+
The filenames shows the version of the time zone files, in this example it is
107+
version 43.
108+
109+
The Oracle Database documentation contains more information about time zone
110+
files, see `Choosing a Time Zone File <https://www.oracle.com/pls/topic/
111+
lookup?ctx=dblatest&id=GUID-805AB986-DE12-4FEA-AF56-5AABCD2132DF>`__.
112+
113+
Changing the Oracle Client Time Zone File
114+
-----------------------------------------
115+
116+
You can get updated time zone files from a full Oracle Database installation,
117+
or by downloading a patch from `Oracle Support <https://support.oracle.com/>`_.
118+
For use with Instant Client, unzip the patch and copy the necessary files:
119+
installing the patch itself will not work.
120+
121+
**Using a New Time Zone File in Instant Client**
122+
123+
From Oracle Instant Client 12.2, you can use an external time zone file,
124+
allowing you to update time zone information without updating the complete
125+
Instant Client installation. Changing the file in earlier versions of Instant
126+
Client is not possible.
127+
128+
To change the time zone file, do one of the following:
129+
130+
- Create a subdirectory ``oracore/zoneinfo`` under the Instant Client
131+
directory and move the file into it. Then set ``ORA_TZFILE`` to the file
132+
name, without any absolute or relative directory prefix prefix. For
133+
example, if Instant Client is in ``/opt/oracle/instantclient``::
134+
135+
mkdir -p /opt/oracle/instantclient/oracore/zoneinfo
136+
cp timezone_43.dat /opt/oracle/instantclient/oracore/zoneinfo/
137+
export ORA_TZFILE=timezone_43.dat
138+
139+
- Alternatively, from Oracle Instant Client 19.18 onwards, you can place the
140+
external time zone file in any directory and then set the ``ORA_TZFILE``
141+
environment variable to the absolute path of the file. For example::
142+
143+
mkdir -p /opt/oracle/myconfig
144+
cp timezone_43.dat /opt/oracle/myconfig/
145+
export ORA_TZFILE=/opt/oracle/myconfig/timezone_43.dat
146+
147+
After installing a new client time zone file, run ``genezi -v`` again to check
148+
if it is readable.
149+
150+
**Using the Embedded Small Time Zone File in Instant Client**
151+
152+
By default, Instant Client uses its larger embedded ``timezlrg_<n>.dat`` file.
153+
If you want to use the smaller embedded ``timezone_<n>.dat`` file, then set the
154+
``ORA_TZFILE`` environment variable to the name of the file without any
155+
absolute or relative directory prefix. For example::
156+
157+
export ORA_TZFILE=timezone_43.dat
158+
159+
**Using a New Time Zone File in a Full Oracle Client**
160+
161+
If node-oracledb Thick mode is using Oracle Client libraries from a full
162+
Oracle Client software installation (such as installed with Oracle's GUI
163+
installer), and you want to use a non-default time zone file, then set
164+
``ORA_TZFILE`` to the file name with an absolute path directory prefix. For
165+
example::
166+
167+
export ORA_TZFILE=/opt/oracle/myconfig/timezone_43.dat
168+
169+
This also works if node-oracledb Thick mode is using libraries from an Oracle
170+
Database installation.
171+
56172
Setting the Client Locale
57173
=========================
58174

‎doc/src/user_guide/initialization.rst

Lines changed: 0 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -492,46 +492,6 @@ explicitly specified or a default location will be used. Do one of:
492492
installation, in ``$ORACLE_HOME/network/admin`` or
493493
``$ORACLE_BASE_HOME/network/admin``.
494494
495-
.. _oratzfile:
496-
497-
Using the Optional Time Zone File
498-
---------------------------------
499-
500-
The name of the Oracle time zone file to use can be set in
501-
``ORA_TZFILE``.
502-
503-
.. note::
504-
505-
The Oracle time zone file and ``ORA_TZFILE`` environment variable are only
506-
used in the node-oracledb Thick mode.
507-
508-
If node-oracledb is using Oracle Client libraries from an Oracle
509-
Database or full Oracle Client software installation, and you want to
510-
use a non-default time zone file, then set ``ORA_TZFILE`` to the file
511-
name with a directory prefix, for example:
512-
``export ORA_TZFILE=/opt/oracle/myconfig/timezone_31.dat``.
513-
514-
Oracle Instant Client includes embedded small and big time zone ‘files’,
515-
for example ``timezone_32.dat`` and ``timezlrg_32.dat``. The versions
516-
can be shown by running the utility ``genezi -v`` located in the Instant
517-
Client directory. The small file contains only the most commonly used
518-
time zones. By default the larger ``timezlrg_n.dat`` file is used. If
519-
you want to use the smaller ``timezone_n.dat`` file, then set the
520-
``ORA_TZFILE`` environment variable to the name of the file without any
521-
directory prefix, for example ``export ORA_TZFILE=timezone_32.dat``.
522-
From Oracle Instant Client 12.2, you can also use an external time zone
523-
file. Create a subdirectory ``oracore/zoneinfo`` under the Instant Client
524-
directory, and move the file into it. Then set ``ORA_TZFILE`` to the file
525-
name, without any directory prefix. The ``genezi -v`` utility will show
526-
the time zone file in use. With Oracle Instant Client 19.18 (or later), you
527-
can alternatively place the external time zone file in any directory and then
528-
set the ``ORA_TZFILE`` environment variable to the absolute path of the file.
529-
530-
The Oracle Database documentation contains more information about time
531-
zone files, see `Choosing a Time Zone
532-
File <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=GUID-805AB986-
533-
DE12-4FEA-AF56-5AABCD2132DF>`__.
534-
535495
.. _environmentvariables:
536496
537497
Oracle Environment Variables for node-oracledb Thick Mode

‎doc/src/user_guide/migrate.rst

Lines changed: 7 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -155,12 +155,13 @@ Upgrading from node-oracledb 6.2 to 6.3
155155
``annotations``, ``domainName``, and ``domainSchema`` identifies the
156156
`annotations <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
157157
GUID-1AC16117-BBB6-4435-8794-2B99F8F68052>`__ object, the name of the
158-
`SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
159-
GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`_, and the schema name of the
160-
`SQL domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&id=
161-
GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched
162-
column. Annotations and SQL domains are supported from Oracle Database 23ai
163-
onwards. For node-oracledb Thick mode, Oracle Client 23ai is also required.
158+
`data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
159+
id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`_, and the schema name of the
160+
`data use case domain <https://www.oracle.com/pls/topic/lookup?ctx=dblatest&
161+
id=GUID-17D3A9C6-D993-4E94-BF6B-CACA56581F41>`__ associated with the fetched
162+
column. Annotations and data use case domains are supported from Oracle
163+
Database 23ai onwards. For node-oracledb Thick mode, Oracle Client 23ai is
164+
also required.
164165

165166
- In node-oracledb Thin mode, ``SYS.XMLTYPE`` data can now be
166167
:ref:`fetched as strings <xmltype>`.

‎test/binding.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -766,7 +766,7 @@ describe('4. binding.js', function() {
766766
await connection.execute(sql, {ROWID: 1});
767767
},
768768
//NJS-098: 1 positional bind values are required but 0 were provided
769-
/ORA-01745:|NJS-098:/
769+
/ORA-01745:/
770770
);
771771
});
772772

0 commit comments

Comments
 (0)