node package manager



congo is a wrapper for node-mongodb-native that makes connections and collections a little easier. Thanks to Thom Seddon's work on co-mongo, congo can also be used with ES6 generators.



npm install congo


npm install


The first thing you must do is call configure to tell congo where the database is and various other options about how the database connection should be made.

var database = require('congo');
  host: 'localhost',
  name: 'test',
  port: 27017,
  pool: 5,
  generators: false,
  reconnect: false,
  collections: []
Key Default Meaning
host localhost hostname of database
name test name of database
port 27017 database port
pool 5 number of pooled connections
generators false allows congo to be used with generators if true (see below)
reconnect false whether to use mongodb-native's reconnect/replay behaviour
collections [] list of known collections to map onto the db object


Get Database

After the call to configure, call get to retrieve a database object.

database.get(function(err, db) {
  // db is a connected database object 


All non-system collections are attached directly onto the database object, so querying a collection is as simple as:

database.get(function(err, db) {
  db.users.findOne({}, function(err, user) {

For convenience, congo also attaches a new findAll function to each collection. This allows you skip dealing with the cursor if you simply want to retrieve all results from a multi-result query:

database.get(function(err, db) {
  db.users.findAll({}, function(err, users) {
    // users is an array of all users from the database 

New Collections

Because congo queries all existing collections and attaches them to the database object, new collections you intend to create won't have a corresponding db.[collection]. In this situation, you can supply an array of collection names in the config that are always mapped onto the database object:

var database = require('congo');
  host: 'localhost',
  name: 'mydb',
  collections: ['users', 'products', 'orders']
database.get(function(err, db) {
  // db.users, db.products and db.orders will all be available, 
  // regardless of whether they existed before or not 


One pooled database connection is created internally and congo reuses it. This means you can call database.get anywhere and not worry about creating unnecessary additional connections.

If { reconnect: true } is set on the configuration object, the mongo driver will reconnect automatically. This also queues commands and replays them once connections are re-established.

If { reconnect: false } is set (the default), congo itself reconnects closed connections on each database.get call and does not queue any failed commands.


If { generators: true } is set, all applicable driver functions are thunked via co-mongo to enable you to yield calls instead of using callbacks.


var database = require('congo');
var co = require('co');
  name: 'database',
  generators: true
co(function*() {
  var db = yield database.get();
  var user = yield db.users.findOne({ name: 'bob' });
  var users = yield db.users.findAll();
  var total = yield db.users.count();
  yield db.close();


Database events such as 'close' and 'error' are propogated. If you're interested in them, pass a handler to database.on:

database.on('close', function() {
  // database connection was closed 
database.on('error', function() {
  // error occurred on the database 

ObjectID, DBRef, BSON, etc. Functions

The ObjectID et al. functions that you would normally be able to access from require('mongo').[func] have been extended onto congo and can be used in exactly the same way:

var database = require('congo');
database.get(function(err, db) {
  db.users.findOne({ _id: database.ObjectID('...') }, function(err, user) {


There are two sets of end-to-end tests to cover the primary driver functions in both callback and generator configurations. The test setup and teardown functions require the mongo executable to be on the path.

To run the regular callback tests, npm test is all you need.

To run the generator tests, run npm run test-generators.