Timezone changes

Author: sharadraju

doc/src/release_notes.rst

@@ -43,6 +43,12 @@ node-oracledb `v6.0.0 <https://github.com/oracle/node-oracledb/compare/v5.5.0...
 #)  Multiple calls to ``initOracleClient()`` with the same arguments no longer
     result in an error.
 
+#)  Oracle Database DATE and TIMESTAMP types are now returned as JavaScript date
+    types in the application's timezone, and no longer fetched or bound as
+    TIMESTAMP WITH LOCAL TIME ZONE.  The connection session time zone no longer
+    impacts these types.  This behavior aligns with other Oracle Database tools
+    and drivers.
+
 #)  Query column metadata now always returns unique column names regardless of
     the value of the ``outFormat`` setting.  Previously they were only unique when
     ``oracledb.OUT_FORMAT_OBJECT`` was used.

lib/connection.js

@@ -386,9 +386,9 @@ class Connection extends EventEmitter {
     // handle binding dates
     } else if (util.isDate(value)) {
       this._checkBindType(bindInfo, iterNum,
-        types.DB_TYPE_TIMESTAMP_LTZ,
-        types.DB_TYPE_TIMESTAMP_TZ,
         types.DB_TYPE_TIMESTAMP,
+        types.DB_TYPE_TIMESTAMP_TZ,
+        types.DB_TYPE_TIMESTAMP_LTZ,
         types.DB_TYPE_DATE);
       bindInfo.values[iterNum] = value;
 

lib/oracledb.js

@@ -983,7 +983,7 @@ module.exports = {
   BUFFER: types.DB_TYPE_RAW,
   CLOB: types.DB_TYPE_CLOB,
   CURSOR: types.DB_TYPE_CURSOR,
-  DATE: types.DB_TYPE_TIMESTAMP_LTZ,
+  DATE: types.DB_TYPE_TIMESTAMP,
   NCLOB: types.DB_TYPE_NCLOB,
   NUMBER: types.DB_TYPE_NUMBER,
   STRING: types.DB_TYPE_VARCHAR,

lib/settings.js

@@ -61,6 +61,56 @@ class Settings {
     this.fetchTypeHandler = undefined;
   }
 
+  //---------------------------------------------------------------------------
+  // _getDateComponents()
+  //
+  // Returns the components of a date. DATE and TIMESTAMP data from the
+  // database are returned as though they used the JavaScript time zone
+  // setting. TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE data
+  // are returned in native JavaScript format (since they contain time zone
+  // information).
+  //---------------------------------------------------------------------------
+  _getDateComponents(useLocal, date) {
+    if (useLocal) {
+      return [
+        date.getFullYear(),
+        date.getMonth() + 1,
+        date.getDate(),
+        date.getHours(),
+        date.getMinutes(),
+        date.getSeconds(),
+        date.getMilliseconds() * 1000 * 1000
+      ];
+    } else {
+      return [
+        date.getUTCFullYear(),
+        date.getUTCMonth() + 1,
+        date.getUTCDate(),
+        date.getUTCHours(),
+        date.getUTCMinutes(),
+        date.getUTCSeconds(),
+        date.getUTCMilliseconds() * 1000 * 1000
+      ];
+    }
+  }
+
+  //---------------------------------------------------------------------------
+  // _makeDate()
+  //
+  // Returns a date from the given components. DATE and TIMESTAMP data from the
+  // database are returned as though they used the JavaScript time zone
+  // setting. TIMESTAMP WITH TIME ZONE and TIMESTAMP WITH LOCAL TIME ZONE data
+  // are returned in native JavaScript format (since they contain time zone
+  // information).
+  //---------------------------------------------------------------------------
+  _makeDate(useLocal, year, month, day, hour, minute, second, fseconds, offset) {
+    if (useLocal) {
+      return new Date(year, month - 1, day, hour, minute, second, fseconds);
+    }
+    return new Date(Date.UTC(year, month - 1, day, hour, minute, second,
+      fseconds) - offset * 60000);
+  }
+
   //---------------------------------------------------------------------------
   // addToOptions()
   //
@@ -97,7 +147,7 @@ class Settings {
           map.set(types.DB_TYPE_BINARY_INTEGER, types.DB_TYPE_VARCHAR);
           map.set(types.DB_TYPE_NUMBER, types.DB_TYPE_VARCHAR);
           break;
-        case types.DB_TYPE_TIMESTAMP_LTZ:
+        case types.DB_TYPE_TIMESTAMP:
           map.set(types.DB_TYPE_DATE, types.DB_TYPE_VARCHAR);
           map.set(types.DB_TYPE_TIMESTAMP, types.DB_TYPE_VARCHAR);
           map.set(types.DB_TYPE_TIMESTAMP_TZ, types.DB_TYPE_VARCHAR);

lib/thin/protocol/buffer.js

@@ -28,6 +28,7 @@
 
 const constants = require("./constants.js");
 const errors = require("../../errors.js");
+const settings = require("../../settings.js");
 const types = require("../../types.js");
 
 /**
@@ -176,18 +177,14 @@ class BaseBuffer {
   // timestamps and the server returns the data in that format, too. The Date
   // type in Node.js doesn't support time zone information.
   //---------------------------------------------------------------------------
-  parseOracleDate(buf, offset) {
+  parseOracleDate(buf, useLocalTime = true) {
     let fseconds = 0;
     if (buf.length >= 11) {
-      fseconds = Math.floor(buf.readUInt32BE(7) / 1000);
+      fseconds = Math.floor(buf.readUInt32BE(7) / (1000 * 1000));
     }
     const year = (buf[0] - 100) * 100 + buf[1] - 100;
-    let dateRet = new Date(Date.UTC(year, buf[2] - 1, buf[3], buf[4] - 1, buf[5] - 1,
-      buf[6] - 1, fseconds / 1000, fseconds % 1000));
-    if (offset) {
-      dateRet = new Date(dateRet.getTime() - offset * 60000);
-    }
-    return dateRet;
+    return settings._makeDate(useLocalTime, year, buf[2], buf[3], buf[4] - 1,
+      buf[5] - 1, buf[6] - 1, fseconds, 0);
   }
 
   //---------------------------------------------------------------------------
@@ -395,12 +392,12 @@ class BaseBuffer {
   // Reads an Oracle date from the buffer and returns a Date or a String,
   // depending on the desired type.
   //---------------------------------------------------------------------------
-  readOracleDate(desiredType, offset) {
+  readOracleDate(desiredType, useLocalTime) {
     const buf = this.readBytesWithLength();
     if (!buf) {
       return null;
     }
-    const val = this.parseOracleDate(buf, offset);
+    const val = this.parseOracleDate(buf, useLocalTime);
     if (desiredType === types.DB_TYPE_VARCHAR) {
       return val.toString();
     }
@@ -698,11 +695,14 @@ class BaseBuffer {
   //---------------------------------------------------------------------------
   // writeOracleDate()
   //
-  // Writes the date to the buffer. The length specifies the amount of
-  // information the server is expecting for the particular date type.
+  // Writes the date to the buffer using the given Oracle type. Note that if a
+  // timestamp with zero milliseconds is written, the type is automatically
+  // changed to DB_TYPE_DATE (except for DB_TYPE_TIMESTAMP_TZ which requires
+  // the full amount to be written).
   //---------------------------------------------------------------------------
-  writeOracleDate(date, length, writeLength = true) {
+  writeOracleDate(date, type, writeLength = true) {
     let fsec;
+    let length = type._bufferSizeFactor;
     if (length > 7) {
       fsec = date.getUTCMilliseconds() * 1000 * 1000;
       if (fsec === 0 && length <= 11)
@@ -712,14 +712,25 @@ class BaseBuffer {
       this.writeUInt8(length);
     }
     const ptr = this.reserveBytes(length);
-    const year = date.getUTCFullYear();
-    ptr[0] = Math.floor(year / 100) + 100;
-    ptr[1] = year % 100 + 100;
-    ptr[2] = date.getUTCMonth() + 1;
-    ptr[3] = date.getUTCDate();
-    ptr[4] = date.getUTCHours() + 1;
-    ptr[5] = date.getUTCMinutes() + 1;
-    ptr[6] = date.getUTCSeconds() + 1;
+    if (type === types.DB_TYPE_DATE || type == types.DB_TYPE_TIMESTAMP) {
+      const year = date.getFullYear();
+      ptr[0] = Math.floor(year / 100) + 100;
+      ptr[1] = year % 100 + 100;
+      ptr[2] = date.getMonth() + 1;
+      ptr[3] = date.getDate();
+      ptr[4] = date.getHours() + 1;
+      ptr[5] = date.getMinutes() + 1;
+      ptr[6] = date.getSeconds() + 1;
+    } else {
+      const year = date.getUTCFullYear();
+      ptr[0] = Math.floor(year / 100) + 100;
+      ptr[1] = year % 100 + 100;
+      ptr[2] = date.getUTCMonth() + 1;
+      ptr[3] = date.getUTCDate();
+      ptr[4] = date.getUTCHours() + 1;
+      ptr[5] = date.getUTCMinutes() + 1;
+      ptr[6] = date.getUTCSeconds() + 1;
+    }
     if (length > 7) {
       ptr.writeInt32BE(fsec, 7);
       if (length > 11) {

lib/thin/protocol/constants.js

@@ -429,7 +429,6 @@ module.exports = {
   TNS_MSG_TYPE_ONEWAY_FN: 26,
 
   // parameter keyword numbers,
-  TNS_KEYWORD_AL8KW_TIMEZONE: 163,
   TNS_KEYWORD_NUM_CURRENT_SCHEMA: 168,
   TNS_KEYWORD_NUM_EDITION: 172,
 
@@ -472,11 +471,6 @@ module.exports = {
   // session return constants
   TNS_SESSGET_SESSION_CHANGED: 4,
 
-  // timezone constants
-  TNS_LDIREGIDFLAG: 120,
-  TNS_LDIREGIDSET: 181,
-  TNS_LDIMAXTIMEFIELD: 60,
-
   // LOB operations
   TNS_LOB_OP_GET_LENGTH: 0x0001,
   TNS_LOB_OP_READ: 0x0002,

lib/thin/protocol/messages/auth.js

@@ -143,20 +143,19 @@ class AuthMessage extends Message {
   }
 
   getAlterTimezoneStatement() {
-    let tzHour, tzMinutes, timezoneMinutes, sign, tzRepr;
-    let date = new Date();
-    timezoneMinutes = date.getTimezoneOffset();
-    tzHour = Math.trunc(timezoneMinutes / 60);
-    tzMinutes = Math.abs((timezoneMinutes - tzHour * 60) % 60);
-    this.conn.tzOffset = -tzHour * 60 + tzMinutes;
+    let sign;
+    const date = new Date();
+    const timezoneMinutes = date.getTimezoneOffset();
+    let tzHour = Math.trunc(timezoneMinutes / 60);
+    const tzMinutes = Math.abs((timezoneMinutes - tzHour * 60) % 60);
     if (tzHour < 0) {
       sign = '+';  // getTimezoneOffset() = localtime - timeUTC
       tzHour = -tzHour;
     } else {
       sign = '-';
     }
     tzHour = tzHour.toLocaleString('en-US', {minimumIntegerDigits: 2});
-    tzRepr = `${sign}${tzHour}:${tzMinutes}`;
+    const tzRepr = `${sign}${tzHour}:${tzMinutes}`;
     return `ALTER SESSION SET TIME_ZONE ='${tzRepr}'\x00`;
   }
 

lib/thin/protocol/messages/withData.js

@@ -387,13 +387,9 @@ class MessageWithData extends Message {
       oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP_LTZ ||
       oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP_TZ
     ) {
-      let offset;
-      if (oraTypeNum === constants.TNS_DATA_TYPE_DATE ||
-        oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP) {
-        offset = this.connection.tzOffset;
-      }
-      colValue = buf.readOracleDate(outputType, offset);
-
+      const useLocalTime = (oraTypeNum === constants.TNS_DATA_TYPE_DATE ||
+        oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP);
+      colValue = buf.readOracleDate(outputType, useLocalTime);
     }  else if (oraTypeNum === constants.TNS_DATA_TYPE_ROWID) {
       if (!this.inFetch) {
         colValue = buf.readStr(constants.TNS_CS_IMPLICIT);
@@ -464,7 +460,6 @@ class MessageWithData extends Message {
   processReturnParameter(buf) {
     let keywordNum = 0;
     let keyTextValue;
-    let keyBinaryValue;
     let numParams = buf.readUB2();              // al8o4l (ignored)
 
     for (let i = 0; i < numParams; i++) {
@@ -482,19 +477,9 @@ class MessageWithData extends Message {
       }
       numBytes = buf.readUB2();                 // value
       if (numBytes > 0) {
-        keyBinaryValue = buf.readBytesWithLength();
+        buf.skipBytesChunked();
       }
       keywordNum = buf.readUB2();               // keyword num
-      if (keywordNum === constants.TNS_KEYWORD_AL8KW_TIMEZONE) {
-        let hour;
-        if (keyBinaryValue[2] > constants.TNS_LDIREGIDFLAG) {
-          hour = keyBinaryValue[4] - constants.TNS_LDIREGIDSET;
-        } else {
-          hour = keyBinaryValue[4] - constants.TNS_LDIMAXTIMEFIELD;
-        }
-        const minute = keyBinaryValue[5] - constants.TNS_LDIMAXTIMEFIELD;
-        this.connection.tzOffset = hour * 60 + minute;
-      }
       if (keywordNum === constants.TNS_KEYWORD_NUM_CURRENT_SCHEMA) {
         this.connection.currentSchema = keyTextValue;
       } else if (keywordNum === constants.TNS_KEYWORD_NUM_EDITION) {
@@ -741,7 +726,7 @@ class MessageWithData extends Message {
       oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP_TZ ||
       oraTypeNum === constants.TNS_DATA_TYPE_TIMESTAMP_LTZ
     ) {
-      buf.writeOracleDate(value, variable.type._bufferSizeFactor);
+      buf.writeOracleDate(value, variable.type);
     } else if (oraTypeNum === constants.TNS_DATA_TYPE_BINARY_DOUBLE) {
       buf.writeBinaryDouble(value);
     } else if (oraTypeNum === constants.TNS_DATA_TYPE_BINARY_FLOAT) {

lib/thin/protocol/oson.js

@@ -520,10 +520,10 @@ class OsonTreeSegment extends GrowableBuffer {
     } else if (util.isDate(value)) {
       if (value.getUTCMilliseconds() === 0) {
         this.writeUInt8(constants.TNS_JSON_TYPE_TIMESTAMP7);
-        this.writeOracleDate(value, 7, false);
+        this.writeOracleDate(value, types.DB_TYPE_DATE, false);
       } else {
         this.writeUInt8(constants.TNS_JSON_TYPE_TIMESTAMP);
-        this.writeOracleDate(value, 11, false);
+        this.writeOracleDate(value, types.DB_TYPE_TIMESTAMP, false);
       }
 
     // handle buffers

lib/types.js

@@ -248,7 +248,8 @@ const DB_TYPE_CONVERSION_MAP = new Map([
     [DB_TYPE_TIMESTAMP_LTZ, DB_TYPE_TIMESTAMP_LTZ]
   ])],
   [DB_TYPE_TIMESTAMP_LTZ, new Map([
-    [DB_TYPE_VARCHAR, DB_TYPE_VARCHAR]
+    [DB_TYPE_VARCHAR, DB_TYPE_VARCHAR],
+    [DB_TYPE_TIMESTAMP_TZ, DB_TYPE_TIMESTAMP_TZ]
   ])],
   [DB_TYPE_TIMESTAMP_TZ, new Map([
     [DB_TYPE_VARCHAR, DB_TYPE_VARCHAR],
@@ -270,7 +271,7 @@ const DB_TYPE_FETCH_TYPE_MAP = new Map([
   [DB_TYPE_CHAR, DB_TYPE_CHAR],
   [DB_TYPE_CLOB, DB_TYPE_CLOB],
   [DB_TYPE_CURSOR, DB_TYPE_CURSOR],
-  [DB_TYPE_DATE, DB_TYPE_TIMESTAMP_LTZ],
+  [DB_TYPE_DATE, DB_TYPE_DATE],
   [DB_TYPE_INTERVAL_DS, DB_TYPE_INTERVAL_DS],
   [DB_TYPE_INTERVAL_YM, DB_TYPE_INTERVAL_YM],
   [DB_TYPE_JSON, DB_TYPE_JSON],
@@ -284,9 +285,9 @@ const DB_TYPE_FETCH_TYPE_MAP = new Map([
   [DB_TYPE_OBJECT, DB_TYPE_OBJECT],
   [DB_TYPE_RAW, DB_TYPE_RAW],
   [DB_TYPE_ROWID, DB_TYPE_ROWID],
-  [DB_TYPE_TIMESTAMP, DB_TYPE_TIMESTAMP_LTZ],
-  [DB_TYPE_TIMESTAMP_LTZ, DB_TYPE_TIMESTAMP_LTZ],
-  [DB_TYPE_TIMESTAMP_TZ, DB_TYPE_TIMESTAMP_LTZ],
+  [DB_TYPE_TIMESTAMP, DB_TYPE_TIMESTAMP],
+  [DB_TYPE_TIMESTAMP_LTZ, DB_TYPE_TIMESTAMP_TZ],
+  [DB_TYPE_TIMESTAMP_TZ, DB_TYPE_TIMESTAMP_TZ],
   [DB_TYPE_UROWID, DB_TYPE_UROWID],
   [DB_TYPE_VARCHAR, DB_TYPE_VARCHAR]
 ]);