Node-oracledb 1.13.0 is available on npm

Node-oracledb 1.13.0, the Node.js add-on for Oracle Database, is onnpm.

Top node-oracledb feature: a fetchAsBuffer mode for fetching BLOBs.

A side note: Oracle Database 12.2 is also here! And Oracle Instant Client 12.2 is available too. Node-oracledb works with 12.2 client libraries (as well as 11.2 and 12.1). With 12.2 client, you can connect to 11.2, 12.1 and 12.2 databases, using Oracle's cross version interoperability which allows Oracle clients to connect to older (or newer) databases. One feature I like in the 12.2 client is its internal Session Pool connection checking, which transparently improves application connection reliability in unstable network environments.

BLOB Enhancements in node-oracledb

The final big piece of LOB support has been added to node-oracledb 1.13 with the addition of a new fetchAsBuffer option. This allows queries to return small BLOBs directly as Node.js Buffers. The new option is ideal for the many applications where BLOBs are kilobyte-sized or, at most, a few megabytes. Fetching as a Buffer is an alternative to the previous method of streaming which should continue to be used for larger BLOBs that can't (or shouldn't) be one chunk of Node.js memory.

There is an example of fetchAsBuffer inexamples/lobselect.js:

oracledb.fetchAsBuffer = [ oracledb.BLOB ];

connection.execute(
  "SELECT b FROM mylobs WHERE id = :idbv",
  [2],
  function(err, result)
  {
    if (err) { . . . }
    if (result.rows.length === 0) { . . . } // no resultsvar blob = result.rows[0][0];  // This is a Buffer

    fs.writeFile('output.jpg', blob, "binary", function(err) {
      return cb(err, connection);
    });
  });

An alternative to the global oracledb.fetchAsBuffer is to use a fetchInfo option for the column atexecute() time:

  { fetchInfo: {"B": {type: oracledb.BUFFER}} }, [ . . . ]

Pull Requests

A small improvement was made to PL/SQL Index-by array binding error messages in 1.13. This was based on PR #470 submitted by Hariprasad Kulkarni. In an array bind situation, if a value with an unexpected data type is used, then messages NJS-037 and NJS-052 now give the bind variable name (or position), and the index of the unexpected data in the input data array. This makes it easier to find and fix the problem. The PR is much appreciated.

Bug fixes

Some bugs were happily squashed in node-oracledb 1.13:

• Fixed several crashes and a memory leak using CLOBs with fetchAsString.

• Fixed several issues including a crash using NULLs and empty strings for LOB BIND_INOUT binds.

• Automatically clean up sessions in the connection pool when they become unusable after an ORA-56600 occurs.

Overall, this is a good release for users working with CLOBs and BLOBs.

Plans for node-oracledb version 2

We are now going to work on a version 2 branch that incorporates the new ODPI-C layer. The code is mostly ready, though testing will take some time. We'll push a development release to GitHub soonish so you check it out and comment during the stabilization phase. Initially node-oracledb 2.x will have the same functionality as 1.x, with a few small additions made possible by ODPI-C.

The plan is for node-oracledb 1.x to go into maintenance mode.Maintenance of node-oracledb 1.x will end on 1st April 2018, coinciding with the end-of-life of Node 4.

Some more details are in the earlier announcement.

Resources

Issues and questions about node-oracledb can be posted on GitHub. We value your input to help prioritize work on the add-on. Drop us a line!

node-oracledb installation instructions are here.

Node-oracledb documentation is here.

Finally, contributions to node-oracledb are more than welcome, see CONTRIBUTING.