lowdb

What is lowdb?

Lowdb is a small local JSON database for Node, Electron, and the browser. It's a simple and lightweight way to store data locally using a JSON file. It is ideal for small projects, quick prototypes, and applications that do not require a full-fledged database.

What are lowdb's main functionalities?

Create and Read Data

This feature allows you to create and read data from a JSON file. The code initializes a lowdb instance, sets default values, adds a new post, and retrieves it.

const low = require('lowdb');
const FileSync = require('lowdb/adapters/FileSync');

const adapter = new FileSync('db.json');
const db = low(adapter);

db.defaults({ posts: [] }).write();

db.get('posts').push({ id: 1, title: 'lowdb is awesome' }).write();

const post = db.get('posts').find({ id: 1 }).value();
console.log(post);

Update Data

This feature allows you to update existing data in the JSON file. The code updates the title of the post with id 1 and retrieves the updated post.

db.get('posts').find({ id: 1 }).assign({ title: 'lowdb is super awesome' }).write();
const updatedPost = db.get('posts').find({ id: 1 }).value();
console.log(updatedPost);

Delete Data

This feature allows you to delete data from the JSON file. The code removes the post with id 1 and retrieves the remaining posts.

db.get('posts').remove({ id: 1 }).write();
const posts = db.get('posts').value();
console.log(posts);

Other packages similar to lowdb

nedb

NeDB is a lightweight JavaScript database that is similar to MongoDB but is meant for small projects. It supports indexing and querying and can be used both in Node.js and in the browser. Compared to lowdb, NeDB offers more advanced querying capabilities and indexing.

lokijs

LokiJS is a fast, in-memory database for Node.js and browsers. It is designed for performance and can handle large datasets efficiently. LokiJS offers more advanced features like indexing, binary serialization, and live querying compared to lowdb.

json-server

json-server is a full fake REST API with zero coding in less than 30 seconds. It is ideal for quick prototyping and mocking REST APIs. Unlike lowdb, json-server is more focused on providing a RESTful interface to your JSON data.

README

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.