1.0.2 • Public • Published

Database Stream API Specification for Node.js

See avinoamr.github.io/dbstream/

A Database Stream (or Cursor) is an abstract interface for creating portable and generic modules for accessing databases using Node Streams. The API specification is Database-agnostic which makes it easy to switch databases, configurations and implementations seamlessly. Write your code once - and it will run against any database.

Due to the massive fragmentation of Node libraries for accessing different databases, it's difficult to write elegant code that is fully portable across database systems. This API has been designed to encourage similarity between Node modules that are used to access databases. Inspired by Python's PEP 249

Available Implementations


This example shows the effectiveness of using Node streams, and the functional, stream-lined API of the dbstream API.

var db = require( "dbstream-somedb" );
var connection = db.connect( /* settings */ );
// write data
var cursor = new connect.Cursor(); 
cursor.write({ name: "Hello", id: 1 }); // upsert where id == 1
cursor.write({ name: "World" }); // insert
// read data
new connect.Cursor()
  .find({ name: "Hello" })
  .on( "data", console.log ) 

Because cursors are just Node Streams, you can pipe them together to construct functional data-processing pipelines:

var es = require("event-stream");
cursor.find({ name: "Hello" })
  .pipe(es.map(function(obj, callback){
    obj.name += "!";
  .pipe(new Cursor()) // write the modifications back to the database
  .pipe(process.stdout) // write the saved object to stdout

Class: dbstream.Cursor

Cursors provide the core functionality of the API. They are simply Node Streams that expose an API for defining a Database operation in a DB-agnostic manner:

Cursors represent a single database operation, and are executed lazily when the cursor.read() method is executed (or in flowing mode, when a listener is attached to the 'data' event)


  • query a key-value Object that defines the database query selection
  • Returns the Cursor instance itself

Sets the query object of the cursor

cursor.find({ name: "Hello" });
cursor.on("data", console.log);
cursor.on("end", function() {
  console.log("Done reading");

cursor.sort(key [, direction])

  • key A String for the field-name to sort by
  • direction An integer that defines the sort direction: 1 for ascending (default), -1 for decending
  • Returns the Cursor instance itself

Sets the sort key and direction of the cursor. Can be called multiple times to define multiple sort keys.


  • n Number of rows to skip
  • Returns the Cursor instance itself

Sets the number of rows that need to be skipped


  • n Number of maximum rows to return
  • Returns Cursor object itself

Sets the maximum number of rows to return

cursor.write(object, encoding, callback)

  • object an Object to save. If id exists, the operation will be an upsert
  • Returns a boolean indicating if the object was processed internally

See Node Stream.write()

cursor.write({ name: "Hello" });
cursor.write({ name: "World", id: 1 }); // upsert
cursor.on("finish", function() {
  console.log( "Everything was saved" );

cursor.remove(object, callback)

  • object an Object to remove. Only relevant when there's an id field
  • Returns a boolean indicating if the object was processed internally

Works exactly like .write, only removes the object instead of saving it

cursor.remove({ id: 1 });
cursor.on( "finish", function() {
  console.log( "ID: 1 was removed" );


  • other is another dbstream Cursor
  • Returns the Cursor instance itself

Copies the query information from the other cursor into the current one.


Any module that implements this API, is dbstreams-compatible, which will make it fully portable across database systems. However, this module provides a skeleton Cursor that you can extend which will make the construction of libraries easier. Your module just needs to implement the _save, _load, _remove and the connect method on the module:

var db = require("dbstream");
var util = require("util");
util.inherits(MyCursor, db.Cursor);
function MyCursor () {
  MyCursor.super_.call( this );
MyCursor.prototype._load = function (size) {
  // read objects from the database, and call this.push( object ) for each one
  // when you're done reading, call this.push( null )
  // Use this._query, this._sort, this._skip and this._limit
MyCursor.prototype._save = function (object, callback) {
  // insert (or upsert, if there's an id)  the object, and call callback() when done
MyCursor.prototype._remove = function (object, callback) {
  // remove object (preferrably by id) and call callback() when done
module.exports.connect = function( settings ) {
  return {
    Cursor: MyCursor // expose the Cursor constructor



Package Sidebar


npm i dbstream

Weekly Downloads






Last publish


  • avinoamr