LowDB

Flat JSON file database for Node

• Serverless
• Speedy
• Evented
• 50+ methods coming from Lo-Dash

LowDB is built on Lo-Dash, this makes it quite different and unique compared to other serverless databases often based on MongoDB API.

LowDB powers JSON Server and JSONPlaceholder.

If you need something similar for the browser, check Underscore.db.

Usage

var low = require('lowdb')
low('songs').insert({title: 'low!'})

Database is automatically created and saved to db.json in a readable format.

{
  "songs": [
    {
      "title": "low!",
      "id": "e31aa48c-a9d8-4f79-9fce-ded4c16c3c4c"
    }
  ]
}

To query data, you can use Lo-Dash methods.

var songs = low('songs').where({ title: 'low!' }).value()

Or LowDB equivalent short syntax.

var songs = low('songs', { title: 'low!' })

Changes can also be monitored.

low.on('add', function(name, object) {
  console.log(object + 'added to' + name)
})

Benchmark

get    x 1000    0.837708 ms
update x 1000    4.433322 ms
insert x 1000    11.78481 ms
remove x 1000    24.60179 ms

To run the benchmark on your machine, clone the project and run npm install && npm run benchmark.

API

low(collection)

Returns or create a Lo-Dash wrapped array.

You can then use methods like: where, find, filter, sortBy, groupBy, ... and also methods from Underscore.db.

var topFiveSongs = low('songs')
  .where({published: true})
  .sortBy('views')
  .first(5)
  .value();
  
var songTitles = low('songs')
  .pluck('titles')
  .value()
  
var total = low('songs').size()

If you just want to modify the database, without getting the returned array or object, you can omit .value()

low.save([path])

Saves database to path or low.path. By default db.json.

low.load([path])

Loads database from path or low.path. By default db.json.

low.path

Database location. By default db.json.

low.path = '/some/path/file.json'

autoSave

Set to false to disable save on change, this turns LowDB into a read-only in-memory database. By default true.

low.autoSave = true

Events

• add(collectionName, insertedDoc)
• update(collectionName, updatedDoc, previousDoc)
• remove(collectionName, removedDoc)
• change()

Short syntax

LowDB short syntax covers only the most common operations but lets you write really concise code.

low('songs', id)
// == low('songs').get(id).value()

low('songs', {title: 'low!'})
// == low('songs').where({title: 'low!'}).value()

low('songs', {title: 'low!'}, +1)
// == low('songs').insert({title: 'low!'}).value()

low('songs', {title: 'low!'}, -1)
// == low('songs').removeWhere({title: 'low!'}).value()

low('songs', id, -1)
// == low('songs').remove(id).value()

low('songs', id, {title: 'new title'})
// == low('songs').update(id, {title: 'new title'}).value()

low('songs', {published: false}, {published: true})
// == low('songs').updateWhere({published: false}, {published: true}).value()

FAQ

How is database saved?

Database is only saved to disk when you call insert, update, updateWhere, remove, removeWhere. Also writing is synchronous but throttled to keep things fast.

Here's an example to illustrate:

low('posts').insert({ title: 'foo' }) // database is persisted synchronously
low('posts').insert({ title: 'foo' }) // database is not persisted
low('posts').insert({ title: 'foo' }) // database is not persisted
// 100 ms later database will be persisted synchronously

So in 1 second, LowDB will make, at most, 10 synchronous writes.

Future versions of LowDB may be fully asynchronous.

Does it support concurrency?

Yes. Node being single threaded and changes to database being synchronously written, there's no risk of having concurrency problems.

License

LowDB is released under the MIT License.