Get Started

npm install massive --save

Starting with version 3.0.0, Massive requires ES6 support and uses Promises exclusively. If you need a callback-based API or are using a pre-6.x release of Node.js, install massive@2 or download version 2.x from the Releases page.

Examples are presented using the standard then() construction for compatibility, but use of ES2017 async and await or a flow control library such as co to manage promises is highly recommended.

REPL

Massive ships with an interactive Read-Evaluate-Print Loop or REPL which lets you connect to a database and query it using JavaScript.

If you have Massive installed globally with the -g flag, you can simply massive; if you've installed it in a project, ./node_modules/.bin/massive. Pass --database mydb to connect to a local database, or --connection to use a connection string.

Changing the Promise Library

Massive uses ES6 promises by default. To use a different promise implementation such as Bluebird to enable long stack traces, pass the required promise module in the driver options.

const promise = require('bluebird');

massive(connectionInfo, {}, {
  promiseLib: promise
}).then(instance => {...});

Monitoring Queries

pg-monitor can help diagnose bugs and performance issues by logging all queries Massive emits to the database as they happen in realtime with more granularity than tailing the Postgres logfile. Note that while the driver options are not required while initializing Massive, db.driverConfig still contains the read-only pg-promise configuration.

const massive = require('massive');
const monitor = require('pg-monitor');

massive('postgres://localhost:5432/massive').then(db => {
  monitor.attach(db.driverConfig);

  db.query('select 1').then(data => {
    // monitor output appears in the console
  });
});

Streaming Results

To improve performance with large result sets, you might want to consider using a stream instead of getting your results in an array all at once. This has the upside of returning something to read right away (which can be a big deal for slow queries too!), but the price is that the connection remains open until you're done. To turn on streaming, add {stream: true} to your options object.

db.tests.find({priority: 'low'}, {stream: true}).then(stream => {
  const tests = [];

  stream.on('readable', () => {
    tests.push(stream.read());
  });

  stream.on('end', () => {
    // do something with tests here
  });
});