simple-oracledb

simple-oracledb

Extend capabilities of oracledb with simplified API for quicker development.

• Overview
• Usage
  • query
  • release
• Installation
• Limitations
• API Documentation
• Release History
• License

Overview

This library enables to modify the oracledb main object, oracledb pool and oracledb connection.
The main goal is to provide an extended oracledb connection which provides more functionality for most use cases.
The new functionality aim is to be simpler and more strait forward to enable quicker development.

Usage

In order to use this library, you need to either extend the main oracledb object as follows:

//load the oracledb library
var oracledb = require('oracledb');

//load the simple oracledb
var SimpleOracleDB = require('simple-oracledb');

//modify the original oracledb library
SimpleOracleDB.extend(oracledb);

//from this point connections fetched via oracledb.getConnection(...) or pool.getConnection(...)
//have access to additional functionality.
oracledb.getConnection(function onConnection(error, connection) {
    if (error) {
        //handle error
    } else {
        //work with new capabilities or original oracledb capabilities
        connection.query(...);
    }
}

Another option is to modify your oracledb pool instance (in case the pool was created outside your code and out of your control), as follows:

//load the simple oracledb
var SimpleOracleDB = require('simple-oracledb');

function myFunction(pool) {    
    //modify the original oracledb pool instance
    SimpleOracleDB.extend(pool);
    
    //from this point connections fetched via pool.getConnection(...)
    //have access to additional functionality.
    pool.getConnection(function onConnection(error, connection) {
        if (error) {
            //handle error
        } else {
            //work with new capabilities or original oracledb capabilities
            connection.query(...);
        }
    }
}

One last option is to modify your oracledb connection instance (in case the connection was created outside your code and out of your control), as follows:

//load the simple oracledb
var SimpleOracleDB = require('simple-oracledb');

function doSomething(connection, callback) {    
    //modify the original oracledb connection instance
    SimpleOracleDB.extend(connection);
    
    //from this point the connection has access to additional functionality as well as the original oracledb capabilities.
    connection.query(...);
}

The rest of the API is the same as defined in the oracledb library: https://github.com/oracle/node-oracledb/blob/master/doc/api.md

'connection.query(sql, bindVariables, [options], callback)'

Provides simpler interface than the original oracledb connection.execute function to enable simple query invocation.
The callback output will be an array of objects, each object holding a property for each field with the actual value.
All LOBs will be read and all rows will be fetched.
This function is not recommended for huge results sets or huge LOB values as it will consume a lot of memory.
The function arguments used to execute the query are exactly as defined in the oracledb connection.execute function.

connection.query('SELECT department_id, department_name FROM departments WHERE manager_id < :id', [110], function onResults(error, results) {
  if (error) {
    //handle error...
  } else {
    //print the 4th row DEPARTMENT_ID column value
    console.log(results[3].DEPARTMENT_ID);
  }
});

'connection.release([callback])'

This function modifies the existing connection.release function by enabling the input callback to be an optional parameter.
Since there is no real way to release a connection that fails to be released, all that you can do in the callback is just log the error and continue.
Therefore this function allows you to ignore the need to pass a callback and makes it as an optional parameter.

connection.release(); //no callback needed

//still possible to call with a release callback function
connection.release(function onRelease(error) {
  if (error) {
    //now what?
  }
});

Installation

In order to use this library, just run the following npm install command:

npm install --save simple-oracledb

This library doesn't define oracledb as a dependency and therefore it is not installed when installing simple-oracledb.
You should define oracledb in your package.json and install it based on the oracledb installation instructions found at: https://github.com/oracle/node-oracledb/blob/master/INSTALL.md

Limitations

The simpler API can lead to higher memory consumption and therefore might not be suitable in all cases.

Also, since this is work in progress, only few capabilities currently were added.
However, in the near future more and more functionality will be added.

API Documentation

See full docs at: API Docs

Release History

Date	Version	Description
2015-10-16	v0.0.3	Maintenance
2015-10-15	v0.0.1	Initial release.

License

Developed by Sagie Gur-Ari and licensed under the Apache 2 open source license.