@rtinternal/oracledb/CHANGELOG.md

[Fork of oracle/node-oracledb ] Oracle Database driver for Node.js maintained by Oracle Corp.

# Change Log

## node-oracledb v5.3.0 (22 Oct 2021)

- Added a
  [`keepInStmtCache`](https://oracle.github.io/node-oracledb/doc/api.html#propexeckeepinstmtcache)
  option to `execute()`, `executeMany()`, and `queryStream()` to control
  whether executed statements are retained in the Statement Cache.
  ([Issue #182](https://github.com/oracle/node-oracledb/issues/182)).

- Encapsulated the connection pool statistics in a [PoolStatistics
  Class](https://oracle.github.io/node-oracledb/doc/api.html#poolstatisticsclass).
  Added a
  [`poolstatistics.logStatistics()`](https://oracle.github.io/node-oracledb/doc/api.html#poolstatisticslogstatistics)
  function, equivalent to the existing `pool.logStatistics()` function.  Exposed
  pool properties `user`, `connectString`, `edition`, `events`,
  `externalAuth`, and `homogeneous` on the Pool and PoolStatistics classes.

- Added [Two-Phase Commit](https://oracle.github.io/node-oracledb/doc/api.html#twopc) support.

- Fixed `queryStream()` logical error handling ([Issue
  1391](https://github.com/oracle/node-oracledb/issues/1391)).

- Prevent intermingling of `queryStream()` streaming and `getRow()`/`getRows()`
  calls.

- Made an internal change for TypeScript 4.4's imported function behavior with
  'this' ([Issue 1408](https://github.com/oracle/node-oracledb/issues/1408)).

## node-oracledb v5.2.0 (7 Jun 2021)

- Connection pool changes:

    - Pool attributes can be changed during application runtime with
      [`pool.reconfigure()`](https://oracle.github.io/node-oracledb/doc/api.html#poolreconfigure).
      This lets properties such as the pool size be changed dynamically instead
      of having to restart the application or create a new pool.

    - Formalized pool statistics with the addition of a pool creation attribute
      [`enableStatistics`](https://oracle.github.io/node-oracledb/doc/api.html#createpoolpoolattrsstats),
      and with the functions
      [`pool.getStatistics()`](https://oracle.github.io/node-oracledb/doc/api.html#poolgetstatistics)
      and
      [`pool.logStatistics()`](https://oracle.github.io/node-oracledb/doc/api.html#poollogstatistics).
      Pool statistics can be be enabled, disabled, or reset with
      `pool.reconfigure()`.  The older `_enableStats` attribute and
      `_logStats()` function are aliases for the new functionality but will be
      removed in a future version of node-oracledb.

    - Added `currentQueueLength` and `poolMaxPerShard` to the pool statistics.

    - Fixed connection pool statistics "minimum time in queue" and "maximum
      time in queue" calculations.

    - Fixed the statement cache size set for the initial `poolMin` connections
      created by `oracledb.createPool()`.

    - Fixed `queueTimeout` of 0 to allow pool connection requests to be queued
      indefinitely.  See [Issue
      1338](https://github.com/oracle/node-oracledb/issues/1338).

- Concurrent operations on a single connection are now queued in the JavaScript
  layer, which can help reduce thread usage for applications that are unable to
  do their own queuing.  A new
  [`oracledb.errorOnConcurrentExecute`](https://oracle.github.io/node-oracledb/doc/api.html#propdberrconexecute)
  property can be used during development to throw an error if concurrent
  operations are attempted on any single connection.

- Enhanced dead connection detection.  If an Oracle Database error indicates
  that a connection is no longer usable, the error `DPI-1080: connection was
  closed by ORA-%d` is now returned.  The `%d` will be the Oracle error causing
  the connection to be closed.  Using the connection after this will give
  `DPI-1010: not connected`.  This behavior also applies for
  [`oracle.callTimeout`](https://oracle.github.io/node-oracledb/doc/api.html#propconncalltimeout)
  errors that result in an unusable connection. ([ODPI-C
  change](https://github.com/oracle/odpi/commit/072739355b8b9d5a4bba3583a79ed53deb15907e)).

- Enhanced
  [`getRows()`](https://oracle.github.io/node-oracledb/doc/api.html#getrows) to
  be able to return all rows in one call.

- Added `username` as an alias for `user` in connection properties.

- Enhanced the numeric suffix feature (for duplicate SELECT column names when
  using `oracledb.OUT_FORMAT_OBJECT` mode) to also support nested cursors and
  REF CURSORS.

- Added support for caching the database version number in pooled connections
  with Oracle Client 19 and earlier (later Oracle Clients handle this caching
  internally).  This optimization eliminates a round-trip previously often
  required when reusing a pooled connection.  ([ODPI-C
  change](https://github.com/oracle/odpi/commit/87268e832363083c1e228922ee11e2fa7aaf8880)).

- [SODA](https://oracle.github.io/node-oracledb/doc/api.html#sodaoverview) changes:

    - Added [SODA metadata
      cache](https://oracle.github.io/node-oracledb/doc/api.html#sodamdcache)
      support to connection pools.  This significantly improves the performance
      of opening collections.  Caching is available when using Oracle Client
      version 21.3 (or later).  It is also available in Oracle Client 19 from
      19.11 onwards.

    - Added a SODA
      [`hint()`](https://oracle.github.io/node-oracledb/doc/api.html#sodaoperationclasshint)
      SodaOperation method and equivalent hint option to
      `sodaCollection.insertManyAndGet()`, `sodaCollection.insertOneAndGet()`,
      and `sodaCollection.saveAndGet()` to allow monitoring and passing hints.

- Fixed crashes seen with Worker threads ([ODPI-C
  change](https://github.com/oracle/odpi/commit/09da0065409702cc28ba622951ca999a6b77d0e9)).

- Fixed a failure when using JavaScript functions on OUT bind variables from
  `executeMany()` that require the connection, for example accessing database
  objects or streaming LOBs.

- Fixed use of `oracledb.NCLOB` in `fetchAsString`.  See [Issue
  1351](https://github.com/oracle/node-oracledb/issues/1351).

- Test and documentation improvements.

## node-oracledb v5.1.0 (8 Dec 2020)

- Added
  [`oracledb.dbObjectAsPojo`](https://oracle.github.io/node-oracledb/doc/api.html#propdbobjpojo)
  and a `connection.execute()` option
  [`dbObjectAsPojo`](https://oracle.github.io/node-oracledb/doc/api.html#propexecobjpojo).
  These specify whether Oracle Database named objects or collections that are
  queried should be returned to the application as "plain old JavaScript
  objects" or kept as database-backed objects.  This option also applies to
  output `BIND_OUT` bind variables.

- Enhanced JSON support to work with Oracle Database 21's native JSON storage
  format.  A new type `oracledb.DB_TYPE_JSON` was added.

- Numeric suffixes are now added to duplicate SELECT column names when using
  `oracledb.OUT_FORMAT_OBJECT` mode, allowing all columns to be represented in
  the JavaScript object.

- The value of `prefetchRows` set when getting a REF CURSOR as a BIND_OUT
  parameter is now used in the subsequent data retrieval from that cursor.

- Fixed a compatibility regression affecting SODA "get" operations using older
  Oracle Client releases.

- Fixed a memory leak getting attributes of objects or elements of collections
  that are themselves objects.

## node-oracledb v5.0.0 (29 Jun 2020)

- Stated compatibility is now for Node.js 10.16+, 12 and 14.

- Installation Changes:

    - Added an
      [`oracledb.initOracleClient()`](https://oracle.github.io/node-oracledb/doc/api.html#odbinitoracleclient)
      function to specify the directories that the Oracle Client libraries and
      optional Oracle configuration files are in, and to specify other
      configuration values, see [Initializing
      Node-oracledb](https://oracle.github.io/node-oracledb/doc/api.html#initnodeoracledb).

    - macOS Instant Client installation instructions have necessarily changed to
      work with recent Node.js versions.  Instant Client libraries in `~/lib`
      will no longer be used.  See
      [INSTALL](https://oracle.github.io/node-oracledb/INSTALL.html#instosx).

    - Fixed how the module binary is found when using Webpack.

      Webpack users should copy the node-oracledb binary into a sub-directory of
      the output directory.  For example if the output directory is `dist`, then
      the binary should be in
      `dist/node_modules/oracledb/build/Release/oracledb-5.0.0-linux-x64.node`.
      A copy plugin in `webpack.config.js` can do this by copying
      `node_modules/oracledb/build` to a directory of that same name.  See
      [Issue 1156](https://github.com/oracle/node-oracledb/issues/1156).

    - Updated [Docker installation
      documentation](https://oracle.github.io/node-oracledb/INSTALL.html#docker)
      for changes to the Node.js image ([Issue #1201](https://github.com/oracle/node-oracledb/issues/1201)).

    - Removed use of git in `package/buildpackage.js` making offline builds cleaner
      for self-hosting node-oracledb.

- Connection Pool changes:

    - Added
      [`oracledb.queueMax`](https://oracle.github.io/node-oracledb/doc/api.html#propdbqueuemax)
      and equivalent `createPool()` option attribute
      [`queueMax`](https://oracle.github.io/node-oracledb/doc/api.html#createpoolpoolattrsqueuemax)
      to limit the number of pending `pool.getConnection()` calls in the pool
      queue ([Issue #514](https://github.com/oracle/node-oracledb/issues/514)).

    - Made an internal change to use an Oracle Client 20 Session Pool feature
      allowing node-oracledb connection pools to shrink to `poolMin` even when
      there is no pool activity.

- Added
  [`oracledb.prefetchRows`](https://oracle.github.io/node-oracledb/doc/api.html#propdbprefetchrows)
  and equivalent `execute()` option attribute
  [`prefetchRows`](https://oracle.github.io/node-oracledb/doc/api.html#propexecprefetchrows)
  for query row fetch tuning to optimize round-trips, or disable prefetching
  altogether.  See [Tuning Fetch
  Performance](https://oracle.github.io/node-oracledb/doc/api.html#rowfetching).

- Added support for queries containing cursor expressions that return [nested
  cursors](https://oracle.github.io/node-oracledb/doc/api.html#nestedcursors).

- Added database instance startup and shutdown functions
[`oracledb.startup()`](https://oracle.github.io/node-oracledb/doc/api.html#odbstartup),
[`oracledb.shutdown()`](https://oracle.github.io/node-oracledb/doc/api.html#odbshutdown),
[`connection.startup()`](https://oracle.github.io/node-oracledb/doc/api.html#constartup),
and
[`connection.shutdown()`](https://oracle.github.io/node-oracledb/doc/api.html#conshutdown).

- Added a new constant
  [`oracledb.SYSPRELIM`](https://oracle.github.io/node-oracledb/doc/api.html#oracledbconstantsprivilege)
  to allow preliminary database connections, such as required when starting a
  database.

- Added support for ResultSet IN binds to PL/SQL REF CURSOR parameters.

- Added support for PL/SQL Collection Associative Arrays "index-by tables" of
  the following types: `oracledb.DB_TYPE_NVARCHAR`, `oracledb.DB_TYPE_CHAR`,
  `oracledb.DB_TYPE_NCHAR`, `oracledb.DB_TYPE_BINARY_FLOAT`,
  `oracledb.DB_TYPE_BINARY_DOUBLE`, `oracledb.DB_TYPE_DATE`,
  `oracledb.DB_TYPE_TIMESTAMP`, `oracledb.DB_TYPE_TIMESTAMP_LTZ`,
  `oracledb.DB_TYPE_TIMESTAMP_TZ` and `oracledb.DB_TYPE_RAW`.

- Refactored the module's JavaScript code layer to use async/await.

- Removed support for custom Promise libraries.  Use the native Node.js Promise
  implementation instead.  This change was necessitated by the refactored
  JavaScript implementation.

- NJS-005 and NJS-009 are now passed through the callback (if one is used).

- Fixed a segfault that occurred when binding a database object IN/OUT without
  providing the database object class.

- Fixed OUT binds of type `oracledb.DB_TYPE_DATE`, `oracledb.DB_TYPE_TIMESTAMP`
  and `oracledb.DB_TYPE_TIMESTAMP_TZ` to correctly return Dates.

- [SODA](https://oracle.github.io/node-oracledb/doc/api.html#sodaoverview) changes:

    - The value of `oracledb.fetchArraySize` now tunes SODA `getCursor()` and
      `getDocuments()` performance when using Oracle Client 19.5.  Added the
      SODA `find()` non-terminal function
      [`fetchArraySize()`](https://oracle.github.io/node-oracledb/doc/api.html#sodaoperationclassfetcharraysize)
      to tune individual `find()` operations.

    - Added Oracle Database 20c SODA 'upsert' functions
      [`sodaCollection.save()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollsave)
      and
      [`sodaCollection.saveAndGet()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollsaveandget).

    - Added Oracle Database 20c SODA function
      [`sodaCollection.truncate()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacolltruncate).

- Lob Changes:

    - Fixed Lob class
      [`lob.type`](https://oracle.github.io/node-oracledb/doc/api.html#proplobtype)
      and
      [`metaData.fetchType`](https://oracle.github.io/node-oracledb/doc/api.html#execmetadata)
      when streaming NCLOB data.  They are now `oracledb.NCLOB` instead of
      `oracledb.CLOB`.

    - Fixed `Lob.destroy()` so it does not call the old `Lob.close()` method, which
      emits a duplicate close event.

    - Lobs being streamed to are now correctly destroyed on error.

- Made an internal change to use an Oracle Client 20 feature to avoid a
  round-trip when accessing
  [`connection.oracleServerVersion`](https://oracle.github.io/node-oracledb/doc/api.html#propconnoracleserverversion)
  or [`connection.oracleServerVersionString`](https://oracle.github.io/node-oracledb/doc/api.html#propconnoracleserverversionstring)
  for the first time.

- Updated examples and documentation to make more use of Node.js 8's Stream
  `destroy()` method, allowing resources to be freed early.

- Test and documentation improvements.

## node-oracledb v4.2.0 (24 Jan 2020)

- Added support for binding using the node-oracledb [Database Type
  Constants](https://oracle.github.io/node-oracledb/doc/api.html#oracledbconstantsdbtype)
  `DB_TYPE_DATE`, `DB_TYPE_CHAR`, `DB_TYPE_NCHAR`, `DB_TYPE_NVARCHAR`,
  `DB_TYPE_NCLOB`, `DB_TYPE_BINARY_DOUBLE`, `DB_TYPE_BINARY_FLOAT`,
  `DB_TYPE_BINARY_INTEGER`, `DB_TYPE_TIMESTAMP`, and `DB_TYPE_TIMESTAMP_TZ`.

- Added support for binding using `DB_TYPE_BOOLEAN` (Diego Arce).

- Added support for creating temporary NCLOBS with
  [`connection.createLob(oracledb.NCLOB)`](https://oracle.github.io/node-oracledb/doc/api.html#connectioncreatelob).

- Added [client initiated
  connection](https://oracle.github.io/node-oracledb/doc/api.html#consubscribeoptclientinitiated)
  support for Continuous Query Notification (CQN) and other subscription based
  notifications.

- Added
  [`result.lastRowid`](https://oracle.github.io/node-oracledb/doc/api.html#execlastrowid)
  to `execute()`.  It contains the ROWID of the last row affected by an INSERT,
  UPDATE, DELETE or MERGE statement.

- Changed the Error object
  [`offset`](https://oracle.github.io/node-oracledb/doc/api.html#properroffset)
  to be 32-bit, allowing the
  [`batchErrors`](https://oracle.github.io/node-oracledb/doc/api.html#executemanyoptbatcherrors)
  mode of `executeMany()` to show row `offset` values up to (2^32)-1 ([ODPI-C
  change](https://github.com/oracle/odpi/commit/294d5966cd513d0c29fdeec3bbbdfad376f81d4f)).

- Avoid intermediate conversion from the database national character set to the
  database character set when querying NCLOB columns as String.

- Fixed various execution failures with Node.js 13.2 due to a Node.js NULL pointer behavior change ([ODPI-C
  change](https://github.com/oracle/odpi/commit/7693865bb6a98568546aa319cc0fdb9e208cf9d4)).

- Fixed connection pooling so sharded `pool.getConnection()` requests respect
  `queueTimeout` when `poolMaxPerShard` has been reached.

- Added a directory to the binary module search to help Webpack use, though a
  copy plugin is still required, see
  [here](https://github.com/oracle/node-oracledb/issues/1156#issuecomment-571554125).

- Fixed some static code analysis warnings.

- Updated Lob streaming documentation and examples. Applications should use the
  `end` event (for readable streams) and `finish` event (for writeable streams)
  instead of the `close` event.  The node-oracledb `lob.close()` method is now
  deprecated in favor of the more functional Node.js 8 Stream `destroy()`
  method.

- Test and documentation improvements.

## node-oracledb v4.1.0 (26 Nov 2019)

- Added end-to-end tracing attributes
  [`connection.clientInfo`](https://oracle.github.io/node-oracledb/doc/api.html#propconnclientinfo)
  and [`connection.dbOp`](https://oracle.github.io/node-oracledb/doc/api.html#propconndbop).

- Added support for [Oracle
  Sharding](https://oracle.github.io/node-oracledb/doc/api.html#sharding).

- Fixed a [regression](https://github.com/oracle/node-oracledb/issues/1152) when
  binding dates with alternative JavaScript frameworks.

- Fixed "NJS-024: memory allocation failed" errors seen on AIX.

- Fixed a JavaScript memory leak when getting Oracle Database named type
  information, such as with `getDbObjectClass()`.

- Corrected support for PLS_INTEGER and BINARY_INTEGER types when used in PL/SQL
  records ([ODPI-C
  change](https://github.com/oracle/odpi/commit/4e80a81257ce6e1066f4f6242fed533eaed45753)).

- Corrected `queryStream()` documentation and examples to show the `'close'`
  event should be received before closing connections.  If connections are
  closed on the `'end'` event, then significant C layer memory may be [held
  open](https://github.com/oracle/node-oracledb/issues/1173) until the garbage
  collector frees the associated JavaScript resource.

- Reverted the
  [`events`](https://oracle.github.io/node-oracledb/doc/api.html#propdbevents)
  default back to pre-4.0 behavior due to connection creation timeouts in some
  environments.  It is now *false* again.

- Error changes:

    - Ensured that `queryStream()` errors raised during close are emitted in the
      `'error'` event.

    - Enforce only one of `connectString` or `connectionString` being used for
      connection.

    - Improved some error messages.

    - Refactored implementation of function argument checking.

- Test and documentation improvements.

## node-oracledb v4.0.1 (19 Aug 2019)

- Fixed a regression causing a segfault when setting `oracledb.connectionClass`
  and not creating a pool ([ODPI-C change](https://github.com/oracle/odpi/commit/f945355f3e58e7337dd798cba0404ab5755f0692)).

- Fixed a regression when enumerable properties were added to
  `Object.prototype`.
  ([#1129](https://github.com/oracle/node-oracledb/issues/1129)).

- Fixed a regression with missing `metaData` from `connection.getStatementInfo()`

- Fixed crashes with spurious subscription (e.g. CQN) notifications, and when
  unsubscribing an invalid subscription.

- A more meaningful error is returned when calling `connection.subscribe()` with
  SQL that is not a SELECT statement ([ODPI-C
  change](https://github.com/oracle/odpi/commit/f95846bef6cf70e8114cbbb59ca04fbe2e7a3903))

- Fixed passing DbObjects and JavaScript objects as the `payload` attribute for
  AQ message enqueues when using an object queue.

- Made the error message for AQ `queue.deqMany(0)` the same NJS-005 given when a
  negative number is used.

- Fixed a compilation warning seen on Windows.

- Improve portability of buildbinary.js, a package creation script ([#1129](https://github.com/oracle/node-oracledb/issues/1129)).

## node-oracledb v4.0.0 (25 Jul 2019)

- Refactored the node-oracledb implementation to use
  [N-API](https://nodejs.org/api/n-api.html) in place of
  [NAN](https://github.com/nodejs/nan).
    - Node-oracledb 4 requires Node.js 8.16 or Node.js 10.16, or higher.  Node.js 8.16, 10.16, 11.12 and 12 contain an important N-API performance fix.
    - N-API allows node-oracledb binaries to be portable between Node.js versions on a given operating system, subject to N-API compatibility.  Node-oracledb uses N-API version 4.
    - Oracle Client libraries are still required at runtime.  These can be from Oracle Instant Client, the full Oracle Client, or an Oracle Database installation.
    - The string representation of classes has changed to `[object Object]` as a consequence of using N-API.  Use `Object.getPrototypeOf()` to get class information.
    - The C compiler required for building from source code no longer needs C++11 compatibility.  The node-oracledb source code is now pure C.

- Added support for querying and binding [Oracle Database Objects and
  Collections](https://oracle.github.io/node-oracledb/doc/api.html#objects).

- Added support for [Oracle Advanced Queuing (AQ)](https://oracle.github.io/node-oracledb/doc/api.html#aq):

    - Added support for "RAW" queues, allowing String and Buffer
      messages to be used.

    - Added support for object queues, allowing Oracle Database object
      messages to be used.

    - Added support for notifications with `oracledb.SUBSCR_NAMESPACE_AQ`.

- Added support for [Implicit
  Results](https://oracle.github.io/node-oracledb/doc/api.html#implicitresults),
  allowing query results to be returned from PL/SQL without needing
  parameters or bind variables.

- Added asynchronous method
  [`lob.getData()`](https://oracle.github.io/node-oracledb/doc/api.html#lobgetdata)
  to return all data from a Lob readable stream.

- Added a new `dbTypeName` attribute to [`extendedMetaData`
  output](https://oracle.github.io/node-oracledb/doc/api.html#execmetadata).
  It contains the name of the type the column has in the database,
  such as "VARCHAR2".

- Enhanced BIND_IN of PL/SQL Collection Associative Arrays (Index-by)
  so a bind definition object can be omitted (see
  [#1039](https://github.com/oracle/node-oracledb/issues/1039)).

- Continuous Query Notification (CQN) Improvements:

    - Added support for getting the [registration
      id](https://oracle.github.io/node-oracledb/doc/api.html#consubscribecallback)
      for CQN subscriptions.

    - Added support and message type constants for database startup
      and shutdown events.

    - Fixed a crash that occurred when unsubscribing from CQN while
      notifications were ongoing ([ODPI-C
      change](https://github.com/oracle/odpi/commit/b96b11b7fe58f32f011c7f7419555e40268d5bf4)).

- Added
  [`connection.currentSchema`](https://oracle.github.io/node-oracledb/doc/api.html#propconncurrentschema)
  for setting the schema qualifier to be used when a qualifier is
  omitted in SQL statements.  This is an efficient alternative to
  `ALTER SESSION SET CURRENT_SCHEMA`.

- Renumbered [node-oracledb Type
  Constants](https://oracle.github.io/node-oracledb/doc/api.html#oracledbconstantsnodbtype)
  and [Oracle Database Type
  Constants](https://oracle.github.io/node-oracledb/doc/api.html#oracledbconstantsdbtype)
  to allow for future enhancements.

- Introduced [Query `outFormat`
  Constants](https://oracle.github.io/node-oracledb/doc/api.html#oracledbconstantsoutformat)
  `oracledb.OUT_FORMAT_ARRAY` and `oracledb.OUT_FORMAT_OBJECT`.  The
  previous constants `oracledb.ARRAY` and `oracledb.OBJECT` are
  deprecated but still usable.

- Improved the performance of [`oracledb.outFormat`](#propdboutformat) mode `oracledb.OUT_FORMAT_OBJECT`.

- Improved the fetch performance of LOBs in some cases by reducing the
  number of round-trips required between node-oracledb and Oracle
  Database ([ODPI-C
  change](https://github.com/oracle/odpi/commit/58e6a07ff5bb428a09068456ef5231884fcb77db)).

- Change the
  [`events`](https://oracle.github.io/node-oracledb/doc/api.html#propdbevents)
  default to *true*.

- Updated the JavaScript syntax in class implementations.

- Class methods are now configurable.  For example via
  `Object.defineProperty`.

- Error handling changes:

    - Corrected the error message returned when invalid types are used for
      boolean options.

    - Standardized error messages for incorrect function parameters.  Now
      NJS-005 and NJS-007 are used in place of NJS-006 and NJS-008,
      respectively.

    - Exceptions from user getters for parameter object attribute access
      are now passed through the error callback.

    - The NJS-014 error when setting a read-only property was replaced
      with a standard JavaScript message.

    - When passing 0 or a negative value for the number of iterations to
      `connection.executeMany()`, errors now occur through the error callback.

    - Some error numbers may have changed due to code refactoring.
      Some message text was updated.

- [SODA](https://oracle.github.io/node-oracledb/doc/api.html#sodaoverview) changes:

    - Added SODA bulk insert methods
      [`sodaCollection.insertMany()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmany)
      and
      [`sodaCollection.insertManyAndGet()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollinsertmanyandget).

    - Document that the general SODA API is out of Preview status when
      using Oracle Client 18.5 or Oracle Client 19.3, or later. The
      new node-oracledb 4.0 methods `sodaCollection.insertMany()` and
      `sodaCollection.insertManyAndGet()` are in Preview status and
      should not be used in production.

    - Corrected the type of
      [`sodaCollection.metaData`](https://oracle.github.io/node-oracledb/doc/api.html#sodacollectionpropmetadata).
      It is now an Object, as was documented.

    - Corrected processing of the `force` option in SODA [`sodaCollection.dropIndex()`](https://oracle.github.io/node-oracledb/doc/api.html#sodacolldropindex).

    - Corrected the error message parameter number for SODA
      [`sodaDatabase.getCollectionNames()`](https://oracle.github.io/node-oracledb/doc/api.html#sodadbgetcollectionnames).

- Fixed writing of multi-byte characters to CLOBs when multiple writes
  are required.

- Fixed a crash occurring when draining the connection pool ([ODPI-C
  change](https://github.com/oracle/odpi/commit/https://github.com/oracle/odpi/commit/7666dc3208087383f7f0f5e49c1ee423cb154997)).

- Corrected `pool.status` to be read-only, as was documented.

- Updated documentation.

- Added new tests.

- Added new examples.  Updated existing examples to the Node.js 8 Async/Await style of programming.

## node-oracledb v3.1.2 (22 Feb 2019)

- Fixed a bug causing CQN crashes when multiple queries are registered
  ([ODPI-C change](https://github.com/oracle/odpi/issues/96)).

- Fixed a CQN race condition to prevent a crash when a multiple
  `connection.unsubscribe()` calls are made on the same subscription.

- Improved validation of `executeMany()` arguments to prevent a crash.

- Standardized error message for SODA `createCollection()` with
  invalid metadata.

- Corrected the DPI-1050 error text displayed when the Oracle Client
  libraries are too old ([ODPI-C change](https://github.com/oracle/odpi/commit/d2fea3801286d054e18b0102e60a69907b7faa9a)).

- Allow `npm run buildbinary` to succeed even if `git` is not
  available.

- Use a relative URL for the ODPI-C submodule to make cloning from
  oss.oracle.com also use ODPI-C from oss.oracle.com

## node-oracledb v3.1.1 (25 Jan 2019)

- Rebuild npm package to resolve Linux binary build issue.

## node-oracledb v3.1.0 (22 Jan 2019)

- Support tagging of pooled connections when releasing them to the
  connection pool.  When using Oracle Client libraries 12.2 or later,
  Oracle's multi-property tagging is used, and a PL/SQL "session"
  state fix-up procedure can be called when a requested connection tag
  does not match the actual tag.  This removes the need to reset
  connection session state after every `pool.getConnection()` call.

- Support a Node.js callback function for connection pools.  It is
  called when a connection is newly created and has never been
  acquired from the pool before, or when a requested connection tag
  does not match the actual tag.

- Support explicit dropping of connections from connection pools.

- Support passing parameters in `oracledb.getConnection()` (such as
  `poolAlias`, `tag` and proxy authentication credentials) for use
  with the pool cache.

- Support the combination of a user proxy and external authentication
  with standalone connections (ODPI-C change).

- Defer initialization of the Oracle Client libraries until the first
  use of `oracledb.getConnection()`, `oracledb.createPool()`,
  `oracledb.oracleClientVersion`, or
  `oracledb.oracleClientVersionString`.

  If the Oracle Client cannot be loaded, `getConnection()` and
  `createPool()` will return an error via the callback.  Accessing
  `oracledb.oracleClientVersion` or
  `oracledb.oracleClientVersionString` with throw an error.

  This change allows `require('oracledb')` to always succeed, allowing
  node-oracledb constants and other attributes to be accessed even if
  the Oracle Client is not installed.

  This makes it easier to include node-oracledb in multi-database
  applications where not all users will be accessing Oracle Database.

  It allows code generation tools to access node-oracledb constants
  without needing Oracle Client installed (see
  [#983](https://github.com/oracle/node-oracledb/issues/983)).

  Applications now have more scope to alter Oracle environment
  variables referenced by the Oracle Client layer. Note it is still
  recommended that the environment be set before Node.js is executed
  due to potential for confusion or unexpected behavior due to
  order-of-execution issues.

- Support fetching XMLTYPE columns in queries.  They will return as
  String limited to the VARCHAR2 length.

- Updated install processes by bundling all pre-built binaries into
  the https://www.npmjs.com/package/oracledb package, removing the
  need for a separate binary package download from GitHub.  At runtime
  an appropriate binary is loaded by `require()`, if it exists,
  allowing one `node_modules/oracledb` install to be usable in
  different environments.

  Source code is no longer included in the npm package.  It is still
  available from GitHub and oss.oracle.com.

  The steps for self-hosting a node-oracledb package have changed, see
  [INSTALL](https://oracle.github.io/node-oracledb/INSTALL.html#selfhost).

- Fixed a crash with high frequency notifications from CQN
  ([#1009](https://github.com/oracle/node-oracledb/issues/1009)).

- Fixed `poolPingInterval` with Oracle client libraries 12.2 or later
  (ODPI-C change).

- Fixed an issue with `poolPingInterval` that could cause usable
  pooled connections to be unnecessarily dropped by
  `connection.close()`.  (ODPI-C change).

- Fixed a memory leak under certain cirumstances when pooled
  connections are released back to the pool. (ODPI-C change)

- Display correct error message for SODA `createIndex()` when no
  parameter is passed.

- Fixed some SODA stability issues (node-oracledb and ODPI-C changes).

- Improved the statement error Allow List to avoid unnecessarily
  dropping statements from the statement cache (ODPI-C change).

- Made internal changes to fix V8 deprecation compilation warnings
  with Node.js 10.12, and fixed other static analysis warnings.

## node-oracledb v3.0.1 (15 Nov 2018)

- Improve validation for SODA `createDocument()` arguments.

- Stated compatibility is now for Node.js 6, 8, 10, and 11.

- Upgraded NAN dependency from 2.10 to 2.11.1.

## node-oracledb v3.0.0 (1 Oct 2018)

- Added new APIs for Simple Oracle Document Access
  ([SODA](https://oracle.github.io/node-oracledb/doc/api.html#sodaoverview)),
  available when using Oracle Database 18.3 and Oracle client
  libraries version 18.3, or later.

- Added a `drainTime` argument to
  [`pool.close()`](https://oracle.github.io/node-oracledb/doc/api.html#poolclose),
  allowing pools to be force-closed after a specified number of
  seconds.  PR #950 (Danilo Silva).

- Added a
  [`connection.callTimeout`](https://oracle.github.io/node-oracledb/doc/api.html#propconncalltimeout)
  property to interrupt long running database calls, available when
  using Oracle client libraries version 18.1, or later.

- Added support for specifying the number of iterations to
  `executeMany()` instead of always requiring an input binds array.
  This is useful when there are no binds, or only OUT binds.

- Added binary installer basic proxy authentication support.  Reuse
  `npm config` proxy.  PR #919 (Cemre Mengu).

- Additionally enable `poolPingInterval` functionality when using
  Oracle client libraries 12.2, or later, to aid silent pool
  connection re-establishment after connections exceed database
  session resource limits (e.g. ORA-02396), or are explicitly closed
  by DBAs (e.g. ORA-00028).  (ODPI-C change).

- Removed the connection pool
  [`queueRequests`](https://oracle.github.io/node-oracledb/doc/api.html#propdbqueuerequests)
  property.  Now `pool.getConnection()` calls are always queued if the
  pool is fully in use.

- Altered the internal `pool.getConnection()` logic to work better
  with Oracle client 18 library pool changes and retain backward
  compatibility with older Oracle clients.  This prevents
  `pool.getConnection()` returning ORA-24418 when the connection pool
  needs to grow and Oracle client 18 libraries are being used.

- Unused properties in objects such as the `execute()` result are no
  longer set.  Previously some were set to `undefined`.

- On Windows, Oracle Client libraries in
  `node_modules\oracledb\build\Release` adjacent to the oracledb.node
  binary will now be used in preference to those in PATH. (ODPI-C
  change).

- Change the binary package filename format from '...-node-vXX...' to
  to '...-node-abiXX...' to reduce Node version and ABI confusion.

- Eliminated a memory leak when fetching LOBs and more than one
  internal fetch occurs.

- Test updates.

- Documentation updates, including an attribute type correction from
  PR #970 (Cemre Mengu)

- Examples were added and updated.

## node-oracledb v2.3.0 (7 Jun 2018)

- The stated compatibility is now for Node.js 6, 8, and 10 due to EOL
  of Node.js 4, and the release of Node 10.

- Added support for heterogeneous connection pooling and for proxy
  support in connection pools.  This allows each connection in the
  pool to use different database credentials.

- Added support for Oracle Database Continuous Query Notifications
  (CQN), allowing JavaScript methods to be called when database
  changes are committed.

- Added support to `fetchAsString` and `fetchInfo` for fetching RAW
  columns as STRING (hex-encoded).

- Added Windows support for building binary packages for self-hosting
  on internal networks. PR #891 (Danilo Silva).

- Eliminated a memory leak when binding LOBs as `oracledb.BIND_INOUT`.

- Added an error message indicating that `batchErrors` and
  `dmlRowCounts` can only be used with INSERT, UPDATE, DELETE and
  MERGE statements.

- Fixed a bug that caused `queryStream()` to emit multiple close
  events in Node.js 10.

- Fixed a crash when getting the list of names for an undefined object
  with Node.js 6.

- Remove deprecated `Buffer()` function in tests in order to eliminate
  a deprecation warning with Node.js 10.

- Upgraded NAN dependency from 2.8 to 2.10.

- Made some internal changes to fix NAN 2.10 deprecations: Replaced
  `v8::String::Utf8Value` with `Nan::Uft8String`.  Replaced
  `MakeCallback()` with `runInAsyncScope()`.

- Mention that `queueRequests` is deprecated and will be removed in a
  future version; connection pool queuing will always be enabled in
  that future version.

## node-oracledb v2.2.0 (3 Apr 2018)

- Added
  [`oracledb.oracleClientVersionString`](https://oracle.github.io/node-oracledb/doc/api.html#propdboracleclientversionstring)
  and
  [`connection.oracleServerVersionString`](https://oracle.github.io/node-oracledb/doc/api.html#propconnoracleserverversionstring)
  to complement the existing numeric properties.

- Added
  [`oracledb.edition`](https://oracle.github.io/node-oracledb/doc/api.html#propdbedition)
  to support Edition-Based Redefinition.  This removes the need to use
  an `ALTER SESSION` command or `ORA_EDITION` environment variable.

- Added
  [`oracledb.events`](https://oracle.github.io/node-oracledb/doc/api.html#propdbevents)
  to allow the Oracle client library to receive Oracle Database
  service events, such as FAN and RLB events.  This removes the need
  to use an `oraaccess.xml` file to enable event handling.

- Added
  [`connection.changePassword()`](https://oracle.github.io/node-oracledb/doc/api.html#changingpassword)
  for changing passwords, and also added support for changing the
  password during `oracledb.getConnection()`.

- Added
  [`connection.executeMany()`](https://oracle.github.io/node-oracledb/doc/api.html#executemany)
  for efficient batch DML (e.g. INSERT, UPDATE and DELETE) and PL/SQL
  execution with multiple records.

- Added
  [`connection.getStatementInfo()`](https://oracle.github.io/node-oracledb/doc/api.html#getstmtinfo)
  to find information about a SQL statement without executing it.

- Added
  [`connection.ping()`](https://oracle.github.io/node-oracledb/doc/api.html#connectionping)
  to support system health checks.

- Added support for binding RAW types into Buffers in DML RETURNING statements.

- Created GitHub 'pages' for hosting documentation.  See:
    - https://oracle.github.io/node-oracledb
    - https://oracle.github.io/node-oracledb/INSTALL.html
    - https://oracle.github.io/node-oracledb/doc/api.html

- Simplified the binary installer messages to reduce user uncertainty.

- Improved the text for the NJS-045 runtime loader failure error.

- Made the implementations of `connection.close()` and `pool.close()`
  the primary code paths in place of their respective aliases
  `connection.release()` and `pool.terminate()`.

- An empty object for `fetchInfo` no longer produces an error.

- Updated database abstraction layer to ODPI-C 2.3

- Fixed compilation warnings on Windows.

- Updated the node-oracledb implementation to replace V8 deprecations.

## node-oracledb v2.1.2 (21 Feb 2018)

- Fixed regression with end-to-end tracing attributes not being set.

- Fix binary installer proxy 403 (Bruno Jouhier)

## node-oracledb v2.1.1 (16 Feb 2018)

- Fixed regression with `queryStream()` in Node 4 & 6
  ([#847](https://github.com/oracle/node-oracledb/issues/847)).

## node-oracledb v2.1.0 (15 Feb 2018)

- Added support for [privileged standalone
  connections](https://oracle.github.io/node-oracledb/doc/api.html#privconn):
  SYSDBA, SYSOPER, SYSASM, SYSBACKUP, SYSDG, SYSKM, and SYSRAC

- Improved the
  [Error](https://oracle.github.io/node-oracledb/doc/api.html#properror)
  object with new `errorNum` and `offset` properties for Oracle
  errors.

- Added new
  [`versionString`](https://oracle.github.io/node-oracledb/doc/api.html#propdbversionstring)
  and
  [`versionSuffix`](https://oracle.github.io/node-oracledb/doc/api.html#propdbversionsuffix)
  attributes to aid showing node-oracledb version and release status.

- Added
  [`connectionString`](https://oracle.github.io/node-oracledb/doc/api.html#createpoolpoolattrsconnectstring)
  as an alias for `connectString` in `oracledb.createPool()` and
  `oracledb.getConnection()` (Sagie Gur-Ari).

- Updated the ODPI-C layer:
    - Eliminate DPI-1054 errors, allowing connections to be closed when ResultSets and Lobs are open.
    - Avoid unnecessary roundtrips for rollbacks at connection close.

- Replaced obsolete [NAN](https://github.com/nodejs/nan) API calls in
  internal implementation and fixed other static analysis warnings.
  This means node-oracledb 2.1 no longer builds with Node.js 0.10 or
  Node.js 0.12.

- Improved [`queryStream()`](https://oracle.github.io/node-oracledb/doc/api.html#querystream) streaming:

    - Add support for the Stream `destroy()` method available with Node 8.

    - Simplified the internal implementation by reusing `ResultSet.getRow()`.

    - Fixed some timing and race issues.

    - Made sure the 'close' event is emitted after the 'end' event.

- Simplified query direct fetch implementation and improved
  performance by reusing ResultSet code.

- Exceptions are no longer raised when accessing attributes on closed
  Connections, Pools, Lobs or ResultSets.

- ResultSets are now closed on error to free resources earlier.

- Improved NJS-010 message content by adding the position and invalid
  data type number.

- Fixed support for integers that are larger than Node.js's 32-bit
  integer is capable of handling.

- Updated [INSTALL](https://oracle.github.io/node-oracledb/INSTALL.html)
  to mention:
    - The [yum.oracle.com](http://yum.oracle.com/oracle-linux-nodejs.html) Node.js RPM Packages for Oracle Linux
    - The [Oracle mirror](oss.oracle.com/git/oracle) of [github.com/oracle](https://github.com/oracle).

- Correct the error message text when attempting to set `oracledb.oracleClientVersion`.

## node-oracledb v2.0.15 (15 Dec 2017) changes since node-oracledb version 1

- Release testing is now done for Node.js 4, 6, 8 and 9.

- Node-oracledb now uses the [ODPI-C](https://github.com/oracle/odpi)
  database abstraction library.

- Upgraded [NAN](https://github.com/nodejs/nan) build dependency to 2.8.

- Installation has significantly improved.  Some pre-built binaries
  are available for convenience, or the add-on can be continue to built
  from source code.  Refer to
  [INSTALL](https://oracle.github.io/node-oracledb/INSTALL.html).

    - Added utilities to /package for building binaries for
      distribution, and for installing them.

    - When building from source code:
        - Oracle header files are no longer needed.
        - The `OCI_LIB_DIR` and `OCI_INC_DIR` environment variables are not needed.

    - A single node-oracledb binary now works with any of the Oracle
      11.2, 12.1 or 12.2 clients.  This improves portability when the
      node-oracledb add-on is copied between machines.  Applications
      should be tested with their target environment to make sure
      expected Oracle functionality is available.

    - At run time, users of macOS must put the Oracle client libraries
      in `~/lib` or `/usr/local/lib`.  Linux users of Instant Client
      RPMs must always set `LD_LIBRARY_PATH` or use ldconfig - the
      previous RPATH linking option is not available.  Other Linux users
      should continue to use `LD_LIBRARY_PATH` or ldconfig.  Windows
      users should continue to put Oracle client libraries in `PATH`.

    - On non-Windows platforms, if Oracle client libraries are not
      located in the system library search path
      (e.g. `LD_LIBRARY_PATH`), then node-oracledb attempts to use
      libraries in `$ORACLE_HOME/lib`.

    - A new [Troubleshooting
      section](https://oracle.github.io/node-oracledb/INSTALL.html#troubleshooting)
      was add to INSTALL.

    - Improvements were made to `require('oracledb')` failure messages
      to help users resolve problems.

    - Changed the installation message prefix in binding.gyp from
      'node-oracledb' to 'oracledb'.

- Improved query handling:

    - Enhanced direct fetches to allow an unlimited number of rows to be
      fetched.  This occurs when `oracledb.maxRows = 0`

    - Changed the default value of `oracledb.maxRows` to 0, meaning
      unlimited.

    - Replaced `prefetchRows` (used for internal fetch buffering and
      tuning) with a new property `fetchArraySize`.  This affects direct
      fetches, ResultSet `getRow()` and `queryStream()`.

    - `getRows(numRows,...)` internal fetch buffering is now only tuned
      by the `numRows` value.

    - Implemented `getRow()` in JavaScript for better performance.

- Tightened up checking on in-use ResultSets and Lobs to avoid leaks
  and threading issues by making sure the application has closed them
  before connections can be closed.  The error DPI-1054 may now be
  seen if connections are attempted to be closed too early.

- Added support for fetching columns types LONG (as String) and LONG
  RAW (as Buffer).  There is no support for streaming these types, so
  the value stored in the database may not be able to be completely
  fetched if Node.js and V8 memory limits are reached.

- Added support for TIMESTAMP WITH TIME ZONE date type.  These are
  mapped to a Date object in node-oracledb using LOCAL TIME ZONE.
  The TIME ZONE component is not available in the Date object.

- Added support for ROWID data type.  Data is fetched as a String.

- Added support for UROWID data type. Data is fetched as a String.

- Added query support for NCHAR and NVARCHAR2 columns.  Note binding
  these types for DML may not insert data correctly, depending on the
  database character set and the database national character set.

- Added query support for NCLOB columns.  NCLOB data can be streamed
  or fetched as String.  Note binding NCLOB for DML may not insert
  data correctly, depending on the database character set and the
  database national character set.

- Removed node-oracledb size restrictions on LOB `fetchAsString` and
  `fetchAsBuffer` queries, and also on LOB binds.  Node.js memory
  restrictions will still prevent large LOBs being manipulated in
  single chunks.

- In LOB binds, the bind `val` can now be a String when `type` is
  CLOB, and `val` can now be a Buffer when `type` is BLOB.

- Improved validation for invalid attribute and parameter values.

- The error parameter of function callbacks is now always null if no
  error occurred.

- Database error messages no longer have an extra newline.

- Statements that generate errors are now dropped from the statement
  cache.  Applications running while table definitions change will no
  longer end up with unusable SQL statements due to stale cache
  entries.  Note that Oracle best-practice is never to change table
  definitions while applications are executing.

- Prevent use of NaN with Oracle numbers to avoid data corruption.

- For LOB streaming, make sure 'close' is the very last event, and
  doesn't occur before an 'error' event.

- Fix duplicate 'close' event for error conditions when streaming LOBs
  in Node 8.

- `connection.createLob()` now uses Oracle Call Interface's (OCI)
  underlying 'cache' mode.

- `Lob.close()` now marks LOBs invalid immediately rather than during
  the asynchronous portion of the `close()` method, so that all other
  attempts are no-ops.

- Relaxed the restriction preventing `oracledb.connectionClass` being
  used with dedicated connections; it previously gave ORA-56609.  Now
  DRCP can now be used with dedicated connections but the
  `CLIENT_DRIVER` value in `V$SESSION_CONNECT_INFO` will not be set in
  this case.  The recommendation is still to use a session pool when
  using DRCP.

- Fixed a crash with LOB out binds in DML RETURNING statements when the
  number of rows returned exceeds the number of rows originally
  allocated internally.

- Empty arrays can now be used in PL/SQL Collection Associative Array
  (Index-by) binds.

- Some NJS and DPI error messages and numbers have changed.  This is
  particularly true of DPI errors due to the use of ODPI-C.

- Many new tests have been created.

- Updated examples for new functionality.

- Documentation has been updated and improved.

## node-oracledb v2.0.15 (15 Dec 2017)

- The stated compatibility is now for Node.js 4, 6, 8 and 9.

- Improved query handling:

    - Enhanced direct fetches to allow an unlimited number of rows to be
      fetched.  This occurs when `oracledb.maxRows = 0`

    - Changed the default value of `oracledb.maxRows` to 0, meaning
      unlimited.

    - Replaced `prefetchRows` (used for internal fetch buffering and
      tuning) with a new property `fetchArraySize`.  This affects direct
      fetches, ResultSet `getRow()` and `queryStream()`.

    - `getRows(numRows,...)` internal fetch buffering is now only tuned
      by the `numRows` value.

    - Implemented `getRow()` in JavaScript for better performance.

    - Moved operations on REF CURSORS out of the main thread in order to
      improve performance and memory usage.

- Fixed proxy support in the binary installer.

- Ensured the callback error parameter is null, not undefined, when no
  error occurred.

- Improvements were made to `require('oracledb')` failure messages to
  help users resolve installation and usage problems.

- Fixed compiler deprecation warnings regarding `Nan::ForceSet`.

## node-oracledb v2.0.14 Development (20 Nov 2017)

- Added infrastructure to /package for creating binary installs.
  Updated INSTALL.md.

- Improved validation for invalid attribute and parameter values.

- In LOB binds, the bind "val" can now be a String when "type" is
  CLOB, and "val" can now be a Buffer when "type" is BLOB.

- Changed binding.gyp message prefix from 'node-oracledb' to 'oracledb'.

- Fix compiler warning with va_start

- Eliminate memory leak when processing result sets containing LOBs
  that require more than one fetch operation (regression from v1).

- Move fetch buffer allocation to reduce memory use for Result Sets
  (regression from v1).

- Upgraded NAN dependency from 2.5 to 2.8.

- Updated ODPI-C submodule:
    - Reinstate safe size limit for LOB bind to PL/SQL (node-oracledb regression from v1).
    - Fix valgrind byte overrun when loading `libclntsh` from `$ORACLE_HOME`.
    - Do not prevent connections from being explicitly closed when a fatal error has taken place.
    - Eliminate race condition on initialization.  Add finalization code.
    - Eliminate use of OCI wrappers for use of mutexes, which improves performance (now uses native threading, e.g. pthreads).
    - Prevent use of NaN with Oracle numbers to avoid data corruption.
    - Prevent ORA-1010 during connection ping to pre 10g Oracle Database.
    - Improve debug trace output format.
    - Prevent crash for DML RETURNING of variables that require dynamic binding.

- Updated examples to avoid "DPI-1054: connection cannot be closed
  when open statements or LOBs exist" and to avoid duplicate callbacks
  on stream errors.

- Check for