oracledb 3.1.2 → 4.2.0

package/CHANGELOG.md

@@ -1,19 +1,292 @@
 # Change Log
 
+## 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
-  `conn.unsubscribe()` calls are made on the same subscription.
+  `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.
 
-- Correct the DPI-1050 error text displayed when the Oracle Client
+- 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
@@ -127,12 +400,12 @@
 ## node-oracledb v3.0.0 (1 Oct 2018)
 
 - Added new APIs for Simple Oracle Document Access
-  ([SODA](https://github.com/oracle/node-oracledb/blob/master/doc/api.md#sodaoverview)),
+  ([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://github.com/oracle/node-oracledb/blob/master/doc/api.md#poolclose),
+  [`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).