connect-db2

connect-db2
===========

An IBM DB2 session store for express.js.

* The key idea behind this project is to allow using IBM dashDB for session storage for Node.js express apps deployed to IBM Bluemix.
* Database access is provided through the node-ibm_db package (so their issues may affect us).

Setup
-----

Install via npm:
``sh
npm install connect-db2 express-session --save
`

Pass the express-session store into connect-db2 to create a Db2Store constructor.

`js
var session = require('express-session');
var Db2Store = require('connect-db2')(session);

var options = {
host: 'localhost',
port: 50000,
username: 'db2user',
password: 'password',
database: 'BLUDB'
};

var sessionStore = new Db2Store(options);
app.use(session({
store: sessionStore,
secret: 'keyboard cat'
}));
`

$3

An altenative to supplying individual settings is to supply the full DSN string in the config instead:

`js
var session = require('express-session');
var Db2Store = require('connect-db2')(session);

var options = {
dsn: 'DRIVER={DB2};DATABASE=BLUDB;HOSTNAME=loclhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;'
};

var sessionStore = new Db2Store(options);
app.use(session({
store: sessionStore,
secret: 'keyboard cat'
}));
`

Note: When a DSN is available in the store config it will always be preferred over individual connection settings.

$3


`js
var session = require('express-session');
var Db2Store = require('connect-db2')(session);
var ibmdb = require('ibm_db');

var dsn = 'DRIVER={DB2};DATABASE=BLUDB;HOSTNAME=loclhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;';
var options = {};
var conn = ibmdb.openSync(dsn);

var sessionStore = new Db2Store(options, conn);
app.use(session({
store: sessionStore,
secret: 'keyboard cat'
}));
`

$3

Set options.use_ssl to true if you want to connect using SSL when using individual settings.

`js
var session = require('express-session');
var Db2Store = require('connect-db2')(session);

var options = {
host: 'localhost',
port: 50001, // SSL port
username: 'db2user',
password: 'password',
database: 'BLUDB',
use_ssl: true
};

var sessionStore = new Db2Store(options);
app.use(session({
store: sessionStore,
secret: 'keyboard cat'
}));
`

When using a DSN, you can either set the options.dsn to an SSL connection string or set options.use_ssl = true, and use the options.ssldsn property.

`js
var session = require('express-session');
var Db2Store = require('connect-db2')(session);

var options = {
ssldsn: 'DRIVER={DB2};DATABASE=BLUDB;HOSTNAME=loclhost;PORT=50001;PROTOCOL=TCPIP;UID=db2user;PWD=password;Security=SSL;',
use_ssl: true
};

var sessionStore = new Db2Store(options);
app.use(session({
store: sessionStore,
secret: 'keyboard cat'
}));
`

So when using DSNs, options.ssldsn and options.dsn can both be set and valid and you can choose between them using the options.use_ssl flag.
This makes it convenient when working within the Bluemix environment where both properties are pre-set in the service config.


Creating the session table
--------------------------

You can ask the store to create the session table for you:

`js
sessionStore.createDatabaseTable(function(error){
if(error){
// deal with it
return;
}
});
`

This will ofcourse fail if the table already exists.
To create the table only when it does not exist, use:

`js
sessionStore.hasDatabaseTable(function(error, hasTable){
if(error){
// deal with it
return;
}
if(hasTable === false) {
sessionStore.createDatabaseTable(function(error){

});
}
});
`

Closing the session store
-------------------------

To cleanly close the session store:
`js
sessionStore.close(function(error){
if(error){
// deal with it
return;
}
});
`

Options
-------

Here is a list of all available options together with their default values:
`js
var options = {
host: 'localhost', // Host name for database connection.
port: 50000, // Port number for database connection.
username: 'db2user', // Database user.
password: 'password', // Password for the above database user.
database: 'BLUDB', // Database name.
expiration: 2592000, // The maximum age of a valid session; milliseconds.
use_ssl: false // If true, use options.ssldsn or create a SSL DSN when connecting.
schema: {
tableName: 'sessions',
columnNames: {
session_id: 'session_id',
expires: 'expires',
data: 'data'
}
},
allowDrop: false // When true, allows dropping the session table by calling sessionStore.dropDatabaseTable()
};
`

Contributing
------------

![GitHub issues](https://github.com/wallali/connect-db2/issues)

There are a number of ways you can contribute:

* Improve or correct the documentation - All the documentation is in this readme file. If you see a mistake, or think something should be clarified or expanded upon, please submit a pull request
* Add test cases - There is need for more test cases and unit-tests to cover uncovered areas of code. It is a great way to get started with this project.
* Report a bug - Please review existing issues before submitting a new one; to avoid duplicates. If you can't find an issue that relates to the bug you've found, please create a new one.
* Fix a bug - Have a look at the existing issues for the project. If there's a bug in there that you'd like to tackle, please feel free to do so. Please submit a test case with that covers your code. After you've done all that, you can submit a pull request with your changes.
* Request a feature - Again, please review the existing issues before posting a feature request. If you can't find an existing one that covers your feature idea, please create a new one. This project is maintained in my free time, chances are you will need to implement your feature idea yourself or wait till I get the chance to do it.

Before you contribute code, please read through at least some of the source code for the project. I would appreciate it if any pull requests for source code changes follow the coding style of the rest of the project. Use npm run lint to lint your code before submission.

Configure Local Dev Environment
---------------------------


$3

First, you'll need to pull down the code from GitHub:
`
git clone https://github.com/wallali/connect-db2.git
`

$3

Second, you'll need to install the project dependencies as well as the dev dependencies. To do this, simply run the following from the directory you created in step 1:
`
npm install
`

$3

Now, you'll need to set up a local test database or create a free dashDB instance on IBM Bluemix:

`js
{
host: 'localhost',
port: 50000,
username: 'db2user',
password: 'password',
database: 'BLUDB',
dsn: ''
};
`
The test database settings are located in test/config.js

Alternatively, you can provide custom database configurations via environment variables:
`
DB_HOST="localhost"
DB_PORT="50000"
DB_USER="db2user"
DB_PASS="password"
DB_NAME="BLUDB"
`

or a DSN via environment variables:
`
DB_DSN="DRIVER={DB2};DATABASE=BLUDB;HOSTNAME=localhost;PORT=50000;PROTOCOL=TCPIP;UID=db2user;PWD=password;"
`

$3

With your local environment configured, running tests is as simple as:
`
npm test
`

Debugging
---------

connect-db2 uses the debug module to output debug messages to the console. To output all debug messages, run your node app with the DEBUG environment variable:
`
DEBUG=connect:db2 node your-app.js
`
This will output debugging messages from connect-db2`.

See Also
--------
* IBM dashDB Reference
* IBM developer Q&A
* DB2 Q&A on Stackoverflow

License
-------

MIT