Add support for Interval datatypes (Issue #929)

Author: sharadraju

doc/src/api_manual/oracledb.rst

@@ -119,9 +119,13 @@ instead of ``result.metadata[0].fetchType == 2001``.
     * - ``oracledb.DB_TYPE_INTERVAL_DS``
       - 2015
       - INTERVAL DAY TO SECOND
+
+        .. versionadded:: 6.8
     * - ``oracledb.DB_TYPE_INTERVAL_YM``
       - 2016
       - INTERVAL YEAR TO MONTH
+
+        .. versionadded:: 6.8
     * - ``oracledb.DB_TYPE_JSON``
       - 2027
       - JSON
@@ -3745,6 +3749,45 @@ node-oracledb, allowing use of new features.
         BLOB columns with the ``IS JSON FORMAT OSON`` check constraint enabled
         can now be fetched as JSON type columns when this property is set.
 
+.. _intervalymclass:
+
+Oracledb IntervalYM Class
+=========================
+
+Objects of this class are returned for columns of type INTERVAL YEAR TO MONTH
+and can be passed to variables of type :ref:`oracledb.DB_TYPE_INTERVAL_YM
+<oracledbconstantsdbtype>` The class contains two optional integer attributes,
+``years`` and ``months``. These attributes can be set by a passed-in
+JavaScript object containing these attributes.
+
+If no JavaScript object is passed in or if these attributes are not defined in
+the passed-in JavaScript object, they are set to *0* by default.
+
+If these attribute values are not integers, then the ``NJS-007`` error is
+thrown when the object is being created.
+
+.. versionadded:: 6.8
+
+.. _intervaldsclass:
+
+Oracledb IntervalDS Class
+=========================
+
+Objects of this class are returned for columns of type INTERVAL DAY TO SECOND
+and can be passed to variables of type :ref:`oracledb.DB_TYPE_INTERVAL_DS
+<oracledbconstantsdbtype>` The class contains five optional integer
+attributes, ``days``, ``hours``, ``minutes``, ``seconds``, and ``fseconds``
+(fractional seconds denoted in nanoseconds). These attributes can be set by a
+passed-in JavaScript object containing these attributes.
+
+If no JavaScript object is passed in or if these attributes are not defined in
+the passed-in JavaScript object, they are set to *0* by default.
+
+If these attribute values are not integers, then the ``NJS-007`` error is
+thrown when the object is being created.
+
+.. versionadded:: 6.8
+
 .. _jsonid:
 
 Oracledb JsonId Class

doc/src/index.rst

@@ -27,6 +27,7 @@ User Guide
     user_guide/tuning.rst
     user_guide/lob_data.rst
     user_guide/json_data_type.rst
+    user_guide/interval_data_type.rst
     user_guide/xml_data_type.rst
     user_guide/vector_data_type.rst
     user_guide/objects.rst

doc/src/release_notes.rst

@@ -21,6 +21,10 @@ Common Changes
 
 #)  Added support for Oracle Database 23ai sparse vectors.
 
+#)  Added support for :ref:`interval year-to-month <intervalyeartomonth>` and
+    :ref:`interval day-to-second <intervaldaytosecond>` database column types.
+    See `Issue #929 <https://github.com/oracle/node-oracledb/issues/929>`__.
+
 #)  Fixed :attr:`~dbObject.length` property for the database object
     collection types, which was broken from node-oracledb 6.0.
 

doc/src/user_guide/appendix_a.rst

@@ -267,11 +267,11 @@ node-oracledb Thin and Thick modes. For more details see :ref:`modediff`.
       - Yes - Only read and write operations supported
       - Yes - Only read operations supported
     * - INTERVAL DAY TO SECOND data type (see :ref:`oracledbconstantsdbtype`)
-      - No
-      - No
+      - Yes
+      - Yes
     * - INTERVAL YEAR TO MONTH data type (see :ref:`oracledbconstantsdbtype`)
-      - No
-      - No
+      - Yes
+      - Yes
     * - Simple Oracle Document Access (SODA) (see :ref:`SODA <sodaoverview>`)
       - No
       - Yes
@@ -721,11 +721,11 @@ when binding numeric values.
       - DB_TYPE_TIMESTAMP_LTZ
       - Yes
     * - INTERVAL YEAR TO MONTH
-      - Not supported
-      - No
+      - DB_TYPE_INTERVAL_YM
+      - Yes
     * - INTERVAL DAY TO SECOND
-      - Not supported
-      - No
+      - DB_TYPE_INTERVAL_DS
+      - Yes
     * - RAW
       - DB_TYPE_RAW
       - Yes

doc/src/user_guide/interval_data_type.rst

@@ -0,0 +1,165 @@
+.. _intervaltype:
+
+*******************
+Using INTERVAL Data
+*******************
+
+Oracle Database supports two INTERVAL data types that store time durations -
+INTERVAL YEAR TO MONTH and INTERVAL DAY TO SECOND. For more information on
+these data types, see `Oracle Interval Types <https://www.oracle.com/pls/topic
+/lookup?ctx=dblatest&id=GUID-7690645A-0EE3-46CA-90DE-C96DF5A01F8F>`__.
+
+Node-oracledb does not support using INTERVAL data types in
+:ref:`Oracle Database Objects <dbobjectclass>`.
+
+.. _intervalyeartomonth:
+
+Using INTERVAL YEAR TO MONTH Data
+=================================
+
+The INTERVAL YEAR TO MONTH data type stores a period of time using years and
+months.
+
+To create a table with a column for INTERVAL YEAR TO MONTH data, for example:
+
+.. code-block:: sql
+
+    CREATE TABLE TableIntervalYM (IntervalCol INTERVAL YEAR TO MONTH);
+
+.. _insertintervalyeartomonth:
+
+Inserting INTERVAL YEAR TO MONTH
+--------------------------------
+
+You must create an IntervalYM object using :ref:`intervalymclass` to insert
+into an INTERVAL YEAR TO MONTH column. For example:
+
+.. code-block:: javascript
+
+    const interval = new oracledb.IntervalYM();
+
+This creates an Oracledb IntervalYM object with ``years`` and ``months``
+attributes set to *0*. You can also create an IntervalYM object with zero
+intervals using:
+
+.. code-block:: javascript
+
+    const interval = oracledb.IntervalYM({});
+
+You can define the optional ``years`` and ``months`` attributes in the
+IntervalYM class. For example, to create an Oracledb IntervalYM cobject with
+only the ``years`` attribute set to *2*:
+
+.. code-block:: javascript
+
+    const interval = new oracledb.IntervalYM({ years: 2 });
+
+An example of creating an IntervalYM object with ``years`` and ``months``
+attributes set to *1* and *6* respectively is shown below. This example is
+used in subsequent sections.
+
+.. code-block:: javascript
+
+    const interval = new oracledb.IntervalYM({ years: 1, months: 6 });
+
+If you specify non-integer values in the attributes of IntervalYM object, then
+the ``NJS-007`` error is raised.
+
+You can insert IntervalYM objects into an INTERVAL YEAR TO MONTH column by
+binding as ``oracledb.DB_TYPE_YM``, for example:
+
+.. code-block:: javascript
+
+    await connection.execute(
+        `INSERT INTO TableIntervalYM VALUES (:bv)`,
+        { bv: { val: interval, type: oracledb.DB_TYPE_YM }
+    );
+
+.. _fetchintervalyeartomonth:
+
+Fetching INTERVAL YEAR TO MONTH
+-------------------------------
+
+To query an INTERVAL YEAR TO MONTH column, you can use:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(`SELECT * FROM TableIntervalYM`);
+    console.log(result.rows[0][0]);
+
+This query prints::
+
+    IntervalYM { years: 1, months: 6 }
+
+.. _intervaldaytosecond:
+
+Using INTERVAL DAY TO SECOND Data
+=================================
+
+The INTERVAL DAY TO SECOND data type stores a period of time using days,
+hours, minutes, seconds, and fractional seconds.
+
+To create a table with a column for INTERVAL DAY TO SECOND data, for example:
+
+.. code-block:: sql
+
+    CREATE TABLE TableIntervalDS (IntervalDSCol INTERVAL DAY TO SECOND);
+
+.. _insertintervaldaytosecond:
+
+Inserting INTERVAL DAY TO SECOND
+--------------------------------
+
+You must create an IntervalDS object using :ref:`intervaldsclass` to insert
+into an INTERVAL DAY TO SECOND column. For example:
+
+.. code-block:: javascript
+
+    const interval = oracledb.IntervalDS();
+
+This creates an Oracledb IntervalDS object with ``days``, ``hours``,
+``minutes``, ``seconds``, and ``fseconds`` (fractional seconds) attributes set
+to *0*. You can also create an IntervalDS object with zero intervals using:
+
+.. code-block:: javascript
+
+    const interval = oracledb.IntervalDS({});
+
+You can define the optional ``days``, ``hours``, ``minutes``, ``seconds``, and
+``fseconds`` attributes in the IntervalDS object. For example, to create an
+Oracledb IntervalDS object with the ``days``and ``seconds`` attributes set to
+*2* and *40* respectively is shown below. This example is used in subsequent
+sections.
+
+.. code-block:: javascript
+
+    const data = new oracledb.IntervalDS({ days: 2, seconds: 40 });
+
+If you specify non-integer values in the attributes of IntervalDS object, then
+the ``NJS-007`` error is raised.
+
+You can insert IntervalDS objects into an INTERVAL DAY TO SECOND column by
+binding as ``oracledb.DB_TYPE_DS``, for example:
+
+.. code-block:: javascript
+
+    await connection.execute(
+        `INSERT INTO TableIntervalDS VALUES (:bv)`,
+        { bv: { val: data, type: oracledb.DB_TYPE_DS }
+    );
+
+.. _fetchintervaldaytosecond:
+
+Fetching INTERVAL DAY TO SECOND
+-------------------------------
+
+To query an INTERVAL DAY TO SECOND column, you can use:
+
+.. code-block:: javascript
+
+    const result = await connection.execute(`SELECT * FROM TableIntervalDS`);
+    console.log(result.rows[0][0]);
+
+This query prints::
+
+    IntervalDS { days: 2, hours: 0, minutes: 0, seconds: 40, fseconds: 0 }

doc/src/user_guide/sql_execution.rst

@@ -811,8 +811,7 @@ used to change the default mapping, or override a global mapping, for
 individual columns.
 
 Data types in ``SELECT`` statements that are unsupported give an error
-*NJS-010: unsupported data type in select list*. These include INTERVAL,
-BFILE, and XMLType types.
+*NJS-010: unsupported data type in select list*.
 
 Details are in the following sections.
 
@@ -954,8 +953,6 @@ ZONE columns are fetched as absolute dates.  Note that JavaScript Date has
 millisecond precision. Therefore, timestamps will lose any sub-millisecond
 fractional part when fetched.
 
-Oracle INTERVAL types are not supported.
-
 .. versionchanged:: 6.0
 
     Oracle Database DATE and TIMESTAMP types are now returned as JavaScript
@@ -1038,6 +1035,13 @@ For more information on time zones, see Oracle Support’s `Timestamps &
 time zones - Frequently Asked Questions, Doc ID 340512.1
 <https://support.oracle.com/epmos/faces/DocumentDisplay?id=340512.1>`__.
 
+.. _intervalhandling:
+
+Fetching Intervals
+++++++++++++++++++
+
+See :ref:`intervaltype`.
+
 .. _fetchasstringhandling:
 
 Fetching Numbers and Dates as String
@@ -1049,7 +1053,11 @@ columns <queryinglobs>`) queried by an application to be fetched as
 strings instead of in native format. Allowing data to be fetched as
 strings helps avoid situations where using JavaScript types can lead to
 numeric precision loss, or where date conversion is unwanted. This
-method can be used for CLOBs up to 1 GB in length.
+method can be used for CLOBs up to 1 GB in length. The
+:ref:`INTERVAL data types <intervalhandling>` cannot be fetched as strings
+using :attr:`~oracledb.fetchAsString`. You can use
+:ref:`fetch type handlers <fetchtypehandler>` to fetch interval data types as
+strings.
 
 For example, to force all dates and numbers used by queries in an
 application to be fetched as strings:

lib/connection.js

@@ -416,7 +416,9 @@ class Connection extends EventEmitter {
         bindInfo.type !== types.DB_TYPE_TIMESTAMP &&
         bindInfo.type !== types.DB_TYPE_TIMESTAMP_LTZ &&
         bindInfo.type !== types.DB_TYPE_TIMESTAMP_TZ &&
-        bindInfo.type !== types.DB_TYPE_RAW) {
+        bindInfo.type !== types.DB_TYPE_RAW &&
+        bindInfo.type !== types.DB_TYPE_INTERVAL_YM &&
+        bindInfo.type !== types.DB_TYPE_INTERVAL_DS) {
       errors.throwErr(errors.ERR_INVALID_TYPE_FOR_ARRAY_BIND);
     }