This project is maintained by arvindr21

A Lightweight Disk based JSON Database with a MongoDB like API for Node

diskDB

A Lightweight Disk based JSON Database with a MongoDB like API for Node.

You will never know that you are interacting with a File System

Contents

Getting Started

Install the module locally :

$ npm install diskdb

var db = require ( 'diskdb' ); db = db . connect ( '/path/to/db-folder' , [ 'collection-name' ]); // you can access the traditional JSON DB methods here

Documentation

Connect to DB

db . connect ( pathToFolder , [ 'filename' ]);

Filename will be the name of the JSON file. You can omit the extension, diskDB will take care of it for you.

var db = require ( 'diskdb' ); db = db . connect ( '/examples/db' , [ 'articles' ]); // or simply db . connect ( '/examples/db' , [ 'articles' ]);

This will check for a directory at given path, if it does not exits, diskDB will throw an error and exit.

If the directory exists but the file/collection does not exist, diskDB will create it for you.

Note : If you have manually created an empty JSON file, please make sure that it contains at least an empty array.

[]

Else it will throw an error like

undefined: 0 ^ SyntaxError: Unexpected end of input

Load Collections

Alternatively you can also load collections like

var db = require ( 'diskdb' ); // this db = db . connect ( '/examples/db' ); db . loadCollections ([ 'articles' ]); //or db . connect ( '/examples/db' ); db . loadCollections ([ 'articles' ]); //or db . connect ( '/examples/db' ) . loadCollections ([ 'articles' ]); //or db . connect ( '/examples/db' , [ 'articles' ]);

Load Multiple Collections

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' , 'comments' , 'users' ]);

Write/Save to Collection

db . collectioName . save ( object );

Once you have loaded a collection, you can access the collection's methods using the dot notation like

db .[ collectionName ].[ methodname ]

To save the data, you can use

var db = require ( 'diskdb' ); db . connect ( 'db' , [ 'articles' ]); var article = { title : "diskDB rocks" , published : "today" , rating : "5 stars" } db . articles . save ( article ); // or db . articles . save ([ article ]);

The saved data will be

[ { "title" : "diskDB rocks" , "published" : "today" , "rating" : "5 stars" , "_id" : "0f6047c6c69149f0be0c8f5943be91be" } ]

You can also save multiple objects at once like

var db = require ( 'diskdb' ); db . connect ( 'db' , [ 'articles' ]); var article1 = { title : 'diskDB rocks' , published : 'today' , rating : '5 stars' } var article2 = { title : 'diskDB rocks' , published : 'yesterday' , rating : '5 stars' } var article3 = { title : 'diskDB rocks' , published : 'today' , rating : '4 stars' } db . articles . save ([ article1 , article2 , article3 ]);

And this will return the inserted objects

[ { title : 'diskDB rocks' , published : 'today' , rating : '4 stars' , _id : 'b1cdbb3525b84e8c822fc78896d0ca7b' }, { title : 'diskDB rocks' , published : 'yesterday' , rating : '5 stars' , _id : '42997c62e1714e9f9d88bf3b87901f3b' }, { title : 'diskDB rocks' , published : 'today' , rating : '5 stars' , _id : '4ca1c1597ddc4020bc41b4418e7a568e' } ]

Read from Collection

There are 2 methods available for reading the JSON collection

db.collectioName.find(query)

db.collectioName.findOne(query)

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . find ();

This will return all the records

[{ title : 'diskDB rocks' , published : 'today' , rating : '5 stars' , _id : '0f6047c6c69149f0be0c8f5943be91be' }]

You can also query with a criteria like

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . find ({ rating : "5 stars" });

This will return all the articles which have a rating of 5.

Nested JSON :

var articleComments = { title : 'diskDB rocks' , published : '2 days ago' , comments : [{ name : 'a user' , comment : 'this is cool' , rating : 2 }, { name : 'b user' , comment : 'this is ratchet' , rating : 3 }, { name : 'c user' , comment : 'this is awesome' , rating : 2 }] }

var savedArticle = db . articles . save ([ articleComments ); foundArticles = db . articles . find ({ rating : 2 });

Since diskDB is mostly for light weight data storage, avoid nested structures and huge datasets.

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . findOne ();

If you do not pass a query, diskDB will return the first article in the collection. If you pass a query, it will return first article in the filtered data

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . findOne ({ _id : '0f6047c6c69149f0be0c8f5943be91be' });

Update Collection

db . collectioName . update ( query , data , options );

You can also update one or many objects in the collection

options = { multi : false , // update multiple - default false upsert : false // if object is not found, add it (update-insert) - default false }

Usage

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); var query = { title : 'diskDB rocks' }; var dataToBeUpdate = { title : 'diskDB rocks again!' , }; var options = { multi : false , upsert : false }; var updated = db . articles . update ( query , dataToBeUpdate , options ); console . log ( updated ); // { updated: 1, inserted: 0 }

Remove Collection

db . collectioName . remove ( query , multi );

You can remove the entire collection (including the file) or you can remove the matched objects by passing in a query. When you pass a query, you can either delete all the matched objects or only the first one by passing multi as false . The default value of multi is true .

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . remove ({ rating : "5 stars" });

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . remove ({ rating : "5 stars" }, true ); // remove all matched. Default - multi = true

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . remove ({ rating : "5 stars" }, false ); // remove only the first match

Using remove without any params will delete the file and will remove the db instance.

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . remove ();

After the above operation db.articles is undefined .

Count

db . collectioName . count ();

Will return the count of objects in the Collection

var db = require ( 'diskdb' ); db . connect ( '/examples/db' , [ 'articles' ]); db . articles . count (); // will give the count

Examples

Refer to the examples folder.

Performance

To validate diskDB's performance and to check if it meets your needs, you can clone this repo and run

$ node performance/time.js

An average of few tests (run on OS X - 10.9.3 | 2.9GHZ i7 | 8GB 1600MHz DDR3) can be found below

Time taken to process x number of objects (in ms) vs Action Performed

1 (object) 1000 (objects) 10000 (objects) 100000 (objects) 1000000 (objects) Save 1 (ms) 15 (ms) 137 (ms) 1782 (ms) 14425 (ms) Find all without query 0 (ms) 2 (ms) 12 (ms) 204 (ms) 2923 (ms) Find all with query 0 (ms) 2 (ms) 17 (ms) 738 (ms) 1985 (ms) Find one without query 0 (ms) 1 (ms) 9 (ms) 791 (ms) 1676 (ms) Find one with query 0 (ms) 1 (ms) 8 (ms) 219 (ms) 1410 (ms) Update all records 1 (ms) 7 (ms) 61 (ms) 206 (ms) 48035 (ms) Get count 0 (ms) 3 (ms) 11 (ms) 260 (ms) 2420 (ms) Remove with query 0 (ms) 7 (ms) 59 (ms) 984 (ms) 48191 (ms) Remove collection 0 (ms) 1 (ms) 4 (ms) 52 (ms) 154 (ms) File size 0.000111 (MB) 0.116671 (MB) 1.196671 (MB) 12.266671 (MB) 125.666671 (MB)

Contributing

See the CONTRIBUTING Guidelines

Release History

0.1.x Base Module with Connect to a Folder Access a Collection/File Create Read Update Delete on JSON object Minor fixes and tests



License

Copyright (c) 2014 Arvind Ravulavaru. Licensed under the MIT license.