====== connect-mongodb-session ======

[[http://mongodb.com|MongoDB]]-backed session storage for [[https://www.npmjs.org/package/connect|connect]] and [[http://www.expressjs.com|Express]]. Meant to be a well-maintained and fully-featured replacement for modules like [[https://www.npmjs.org/package/connect-mongo|connect-mongo]]

[[https://travis-ci.org/mongodb-js/connect-mongodb-session|{{https://camo.githubusercontent.com/06357d245c5786515ba70704fba13f1b8b14db1b0694e7e6253b093fb86010c9/68747470733a2f2f7472617669732d63692e6f72672f6d6f6e676f64622d6a732f636f6e6e6563742d6d6f6e676f64622d73657373696f6e2e7376673f6272616e63683d6d6173746572|Build Status}}]] [[https://coveralls.io/r/mongodb-js/connect-mongodb-session?branch=master|{{https://camo.githubusercontent.com/80ca15c1b957a71685382e481a9c4142bb076fc46ec711311f25dbf5a11a5efd/68747470733a2f2f636f766572616c6c732e696f2f7265706f732f6d6f6e676f64622d6a732f636f6e6e6563742d6d6f6e676f64622d73657373696f6e2f62616467652e7376673f6272616e63683d6d6173746572|Coverage Status}}]]

====== MongoDBStore ======

This module exports a single function which takes an instance of connect (or Express) and returns a ''MongoDBStore'' class that can be used to store sessions in MongoDB.

===== It can store sessions for Express 4 =====

If you pass in an instance of the ''[[http://npmjs.org/package/express-session|express-session]]''[[http://npmjs.org/package/express-session| module]] the MongoDBStore class will enable you to store your Express sessions in MongoDB.

The MongoDBStore class has 3 required options:

  - ''uri'': a [[http://docs.mongodb.org/manual/reference/connection-string/|MongoDB connection string]]
  - ''databaseName'': the MongoDB database to store sessions in
  - ''collection'': the MongoDB collection to store sessions in

**Note:** You can pass a callback to the ''MongoDBStore'' constructor, but this is entirely optional. The Express 3.x example demonstrates that you can use the MongoDBStore class in a synchronous-like style: the module will manage the internal connection state for you.

<code>
var express = require('express');
var session = require('express-session');
var MongoDBStore = require('connect-mongodb-session')(session);

var app = express();
var store = new MongoDBStore({
  uri: 'mongodb://localhost:27017/connect_mongodb_session_test',
  collection: 'mySessions'
});

// Catch errors
store.on('error', function(error) {
  console.log(error);
});

app.use(require('express-session')({
  secret: 'This is a secret',
  cookie: {
    maxAge: 1000 * 60 * 60 * 24 * 7 // 1 week
  },
  store: store,
  // Boilerplate options, see:
  // * https://www.npmjs.com/package/express-session#resave
  // * https://www.npmjs.com/package/express-session#saveuninitialized
  resave: true,
  saveUninitialized: true
}));

app.get('/', function(req, res) {
  res.send('Hello ' + JSON.stringify(req.session));
});

server = app.listen(3000);
</code>

===== It throws an error when it can't connect to MongoDB =====

You should pass a callback to the ''MongoDBStore'' constructor to catch errors. If you don't pass a callback to the ''MongoDBStore'' constructor, ''MongoDBStore'' will ''throw'' if it can't connect.

<code>
var express = require('express');
var session = require('express-session');
var MongoDBStore = require('connect-mongodb-session')(session);

var app = express();
var numExpectedSources = 2;
var store = new MongoDBStore(
  {
    uri: 'mongodb://bad.host:27000/connect_mongodb_session_test?connectTimeoutMS=10',
    databaseName: 'connect_mongodb_session_test',
    collection: 'mySessions'
  },
  function(error) {
    // Should have gotten an error
  });

store.on('error', function(error) {
  // Also get an error here
});

app.use(session({
  secret: 'This is a secret',
  cookie: {
    maxAge: 1000 * 60 * 60 * 24 * 7 // 1 week
  },
  store: store,
  // Boilerplate options, see:
  // * https://www.npmjs.com/package/express-session#resave
  // * https://www.npmjs.com/package/express-session#saveuninitialized
  resave: true,
  saveUninitialized: true
}));

app.get('/', function(req, res) {
  res.send('Hello ' + JSON.stringify(req.session));
});

server = app.listen(3000);
</code>

===== It supports several other options =====

There are several other options you can pass to ''new MongoDBStore()'':

<code>
var express = require('express');
var session = require('express-session');
var MongoDBStore = require('connect-mongodb-session')(session);

var store = new MongoDBStore({
  uri: 'mongodb://localhost:27017/connect_mongodb_session_test',
  collection: 'mySessions',

  // By default, sessions expire after 2 weeks. The `expires` option lets
  // you overwrite that by setting the expiration in milliseconds
  expires: 1000 * 60 * 60 * 24 * 30, // 30 days in milliseconds

  // Lets you set options passed to `MongoClient.connect()`. Useful for
  // configuring connectivity or working around deprecation warnings.
  connectionOptions: {
    useNewUrlParser: true,
    useUnifiedTopology: true,
    serverSelectionTimeoutMS: 10000
  }
});
</code>