README.md

connect-waterline

Waterline session store for Connect and Express.

Overview

connect-waterline is inspired by the popular connect-mongo but instead of using MongoDB as its datastore it's able to use any Waterline adapter. Connect-waterline can use its own instance of Waterline or you can pass a model from an existing Waterline instance.

Currently, official adapters exist for MySQL, PostgreSQL, MongoDB, Redis, local disk, and local memory. Community adapters exist for CouchDB, neDB, TingoDB, SQLite, Oracle, MSSQL, DB2, ElasticSearch, Riak, neo4j, OrientDB, Amazon RDS, DynamoDB, Azure Tables, and RethinkDB.

Instalation

npm i connect-waterline -S

Usage

Express or Connect integration

Express 4.x, 5.0 and Connect 3.x:

var session = require('express-session');
var WaterlineStore = require('connect-waterline')(session);

app.use(session({
    secret: 'foo',
    store: new WaterlineStore(options)
}));

Express 2.x, 3.x and Connect 1.x, 2.x:

var WaterlineStore = require('connect-waterline')(express);

app.use(express.session({
    secret: 'foo',
    store: new WaterlineStore(options)
}));

For Connect 1.x and 2.x, just replace express by connect.

Waterline instance

In many circumstances, connect-waterline will not be the only part of your application which need a waterline instance. It could be interesting to re-use an existing waterline instance.

Alternatively, you can configure connect-waterline to create it own instance of waterline.

Re-use waterline instance

var Waterline = require('waterline');
var ConnectWaterline = require('connect-waterline');

var extendedCollections = [
  Waterline.Collection.extend(_.defaults({ connection: 'connect-waterline' }, ConnectWaterline.defaultModelDefinition))
  // plus your app collections
];
var waterline = new Waterline();

extendedCollections.forEach(function (collection) {
  waterline.loadCollection(collection);
});

// Initialize Waterline
waterline.initialize({
  adapters: {
    'sails-disk': require('sails-disk')  // or any other waterline adapter
  },
  connections: {
    'connect-waterline': {
      adapter: 'sails-disk'
      // place adapter and connection specific options here
    }
  }
}, function waterlineReady(function(err, ontology){
  mySessionModel = ontology.collections.sessions;
}));

// after waterline is initialized
app.use(session({
  secret: 'foo',
  store: new WaterlineStore({ model: mySessionModel });
}));

Create new waterline instance

var WaterlineStore = require('connect-waterline');

var options = {
  adapters: {
    'default': require('sails-disk')  // or any other sails adapter
  },
  connections: {
    'connect-waterline': {
      adapter: 'default'
      // specific adapter connection options
      // user: '',
      // password: '',
      // host: 'localhost',
      // database: 'sessions'
    }
  },
  autoRemoveInterval: 6*60  // expired sessions will be cleaned every 6h
})

app.use(session({
  secret: 'foo',
  store: new WaterlineStore(options);
}));

Tip: it's usually a good idea to place app.use(session(/*...*/)); after your app.use(express.static(/*...*/)); statement to avoid creating sessions for every static asset (like .css or image files) that you have on your website. More about this here.

Testing

Test are written with mocha. To run all tests (requires all official adapters and respective DBs):

npm test

To run unit tests (requires sails-memory):

make test-unit

About Waterline

Waterline is a new kind of storage and retrieval engine.

It provides a uniform API for accessing stuff from different kinds of databases, protocols, and 3rd party APIs. That means you write the same code to get and store things like users, whether they live in OrientDB, Redis, mySQL, LDAP, MongoDB, or Postgres.

Waterline strives to inherit the best parts of ORMs like ActiveRecord, Hibernate, and Mongoose, but with a fresh perspective and emphasis on modularity, testability, and consistency across adapters.

License

MIT