node package manager
Stop writing boring code. Discover, share, and reuse within your team. Create a free org »


Simple Node DB

NPM version Build Status Dependency Status

   _____            __      _  __        __         ____ 
  / __(_)_ _  ___  / /__   / |/ /__  ___/ /__   ___/ / / 
 _\ \/ /  ' \/ _ \/ / -_) /    / _ \/ _  / -_) / _  / _ \
/___/_/_/_/_/ .__/_/\__/ /_/|_/\___/\_,_/\__/  \_,_/_.__/


A database implementation on top of levelup, leveldown, and memdown. SimpleNodeDb leverages the document store aspects of level up to provide a data-model/domain centric implementation.

Models are stored as JSON strings with domain-scoped keys. For example a user data model's key of '12345' would have an associated domain key of 'user:12345'. So querying for users as opposed to orders or inventory parts is as easy as including records where keys begin with 'user:'.

Automatic model attributes include dateCreated, lastUpdated and version. The version attribute is used to enforce optimistic locking.

Typically SimpleNodeDb is well suited for small to medium datasets (less than 100K rows) or data stores that don't require complex querying. It also provides robust caching when used as an in-memory data store. To support more than 100K rows you should probably create alternate indexing schemes or stick with redis, mongo, or a traditional SQL database.

Note: levelup is a simple key/value store. It may be more appropriate to use this for simple, single user access storage. SimpleNodeDb is designed to work more as a formal domain data store with simulated domains that contain keyed JSON documents. For most use cases, it is more appropriate to use redis or another server based document store if multi-user access is required...

Change Log

0.91.x (requires node 4.x)

Note: Future changes: for now support goes back to node 4.x; the next release will require 6.x to support more es6 features.


$ npm install simple-node-db --save

Testing And Examples

Basic testing is in place for all implemented methods. Examples can be found under ./examples.



// create an in-memory database 
const SimpleDb = require('simple-node-db');
let db = new SimpleDb({memory:true});
// create a file based database 
db = new SimpleDb('/path/to/database');
// create a database with options 
const options = {
    log:new Logger('db'),
    readAfterChange:true // read-back record after insert/update; else return model 
db = new SimpleDb( options );

query( params, rowCallback, completeCallback )

// query for all list rows where the key begins with 'mydomain:' 
const rowCallback = function(key, value) {
    // put appropriate query conditions here  
    if ( key.indexOf('mydomain:') >= 0) ) {
        // parse and return the value 
        return JSON.parse( value );
const completeCallback = function(err, list) {
    if (err) throw err;
    assert list.length === 25
const params = {
    end:'mydomain:~'  // the tilde insures all 'my domain' rows are found 
db.query(params, rowCallback, completeCallback);

queryKeys( params, completeCallback )

// query for all keys and dump to the console... 
db.queryKeys( {}, console.log );

find( key, callback )

// create the key based on domain and model id 
const key = db.createDomainKey( 'user', id );
// value is saved as a json object 
const callback = function(err, model) {
    if (err) throw err;
    // do something with the model... 
db.find( key, callback );

insert( key, model, callback )

// a simple user model 
Const user = {
    name:'Sam Sammyson',
// key is created for the 'user' domain 
const key = db.createDomainKey( 'user', )
const callback = function(err, model) {
    if (err) throw err;
    assert model.dateCreated;
    assert model.lastUpdated === model.dateCreated;
    assert model.version === 0;
// model must have an 'id' attribute 
db.insert( key, model, callback );

update( key, model, callback )

// the version and lastUpdated attributes are automatically updated 
const user = {
    dateCreated:new Date(),
    lastUpdated:new Date(),
    name:'Sam Sammyson',
const key = db.createDomainKey( 'user', )
const callback = function(err, model) {
    if (err) throw err;
    assert model.version === user.version + 1;
    assert model.lastUpdated.getTime() > user.dateCreated.getTime();
// model must have an 'id' attribute 
db.update( key, model, callback );

delete( key, callback )

// very simple, merciless delete -- use at your own risk... 
const callback = function(err) {
    if (err) throw err;
db.delete( key, callback );


// create a model id from uuid without dashes 
const id = db.createModelId();
assert id === '01BDA6RVHSFRQ2FKZ6FVJPFFSW';

createDomainKey( domain, id );

const model = {
const key = db.createDomainKey( 'user', );
assert key.contains( 'user:' );
assert key.contains( );
assert key === 'user:01BDA6V2JGXN8WHTSF5DX8H21S';

backup( filename, callback )

// stream dump of keys and values row-by-row, CR/LF delimited 
const filename = '/path/to/backup/file';
const callback = function(err, rowsWritten) {
    if (err) throw err;
    assert rowsWritten > 0;
db.backup( filename, callback );

restore( filename, callback )

// read the key/value file and batch put the rows; uses stream reader to  
const callback = function(err, rowsRead) {
    if (err) throw err;
    assert rowsRead > 0;
const filename = '/path/to/my/backup';
db.restore( filename, callback );

stats( callback )

// reports the domains and number of rows 
db.stats( console.log );

close( callback )

db.close(function(err) {'db is now closed...');

open( callback ) {'db is now open...');


if (db.isInMemory()) {'database is in-memory, data will be lost if not backed up...');

SimpleNodeDb.createREPL( db )

A REPL is available to enable database manipulation from the node repl.

// creates a REPL for SimpleNoeDb and opens the database 'db' 
// if db is null, then an in-memory db is opened 
db = require('simple-node-db').createREPL( './mydb' );
db.stats() // shows the domains, row counts, etc 
db.query() // dumps all the rows 
db.queryKeys() // dumps all the keys 
db.find('user:01BDA1K893NMBH2W1FFRD4W76A') // will return the user if it exists 
// query for all users 
// or, an alternative to find all the users... 
let rowcb = (key, value) => {
    if (key.startsWith('user:')) {
        return JSON.parse(value);
db.query({}, rowcb)
Copyright © 2014-2017, rain city software, inc. | Version 0.91.14