⚡️ lowdb is a small local database powered by lodash (supports Node, the browser and Electron)
JavaScript
Latest commit c4238ad Dec 15, 2016 @typicode committed on GitHub Update README.md
Permalink
Failed to load latest commit information.
examples Fix minor typos in examples/README.md Jun 5, 2016
src Update tests Jun 8, 2016
test Update tests Jun 8, 2016
.babelrc Update Dec 14, 2015
.gitignore Update May 8, 2016
.npmignore Update Dec 14, 2015
.travis.yml Update Dec 14, 2015
LICENSE First commit Apr 2, 2014
README.md Update README.md Dec 15, 2016
lowdb.d.ts Added typescript definition Jun 5, 2016
package.json 0.14.0 Oct 25, 2016
webpack.config.js Update devDependencies and set lodash as a dependency again Oct 25, 2016

README.md

Lowdb NPM version Build Status

A small local database powered by lodash API

Used by json-server and more than 80 awesome projects on npm.

const db = low('db.json')

db.defaults({ posts: [], user: {} })
  .value()

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

db.set('user.name', 'typicode')
  .value()

Data is automatically saved to db.json

{
  "posts": [
    { "id": 1, "title": "lowdb is awesome"}
  ],
  "user": {
    "name": "typicode"
  }
}

And you can query it using lodash API

db.get('posts')
  .find({ id: 1 })
  .value()

Lowdb is perfect for CLIs, small servers, Electron apps and npm packages in general.

It supports Node, the browser and uses lodash API, so it's very simple to learn. Actually... you may already know how to use lowdb 😉

Why lowdb?

  • Lodash API
  • Minimal and simple to use
  • Highly flexible
    • Custom storage (file, browser, in-memory, ...)
    • Custom format (JSON, BSON, YAML, XML, ...)
    • Mixins (id support, ...)
    • Read-only or write-only modes
    • Encryption

Important lowdb doesn't support Cluster.

Install

npm install lowdb --save

Alternatively, if you're using yarn

yarn add lowdb

A UMD build is also available on unpkg for testing and quick prototyping:

<script src="https://unpkg.com/lodash@4/lodash.min.js"></script>
<script src="https://unpkg.com/lowdb/dist/lowdb.min.js"></script>
<script>
  var db = low('db')
</script>

API

low([source, [options])

  • source string or null, will be passed to storage
  • options object
    • storage object, by default lowdb/lib/file-sync or lowdb/lib/browser.
      • read function or null
      • write function or null
    • format object
      • serialize function, by default JSON.stringify
      • deserialize function, by default JSON.parse
    • writeOnChangeboolean

Creates a lodash chain, you can use any lodash method on it. When .value() is called data is saved using storage.

You can use options to configure how lowdb should persist data. Here are some examples:

// in-memory
low()

// persisted using async file storage
low('db.json', { storage: require('lowdb/lib/file-async') })

// persisted using a custom storage
low('some-source', { storage: require('./my-custom-storage') })

// write on change disabled
low('db.json', { writeOnChange: false })

// read-only
const fileSync = require('lowdb/lib/file-sync')
low('db.json', {
  storage: {
    read: fileSync.read
  }
})

// write-only
low('db.json', {
  storage: {
    write: fileSync.write
  }
})

db._

Database lodash instance. Use it to add your own utility functions or third-party mixins like underscore-contrib or underscore-db.

db._.mixin({
  second: function(array) {
    return array[1]
  }
})

const post1 = db.get('posts').first().value()
const post2 = db.get('posts').second().value()

db.getState()

Use whenever you want to access the database state.

db.getState() // { posts: [ ... ] }

db.setState(newState)

Use it to drop database or set a new state (database will be automatically persisted).

const newState = {}
db.setState(newState)

db.write([source])

Persists database using storage.write option. Depending on the storage, it may return a promise (for example, with `file-async').

By default, lowdb automatically calls it when database changes.

const db = low('db.json')
db.write()            // writes to db.json
db.write('copy.json') // writes to copy.json

db.read([source])

Reads source using storage.read option. Depending on the storage, it may return a promise.

const db = low('db.json')
db.read()            // reads db.json
db.read('copy.json') // reads copy.json

Guide

How to query

With lowdb, you get access to the entire lodash API, so there are many ways to query and manipulate data. Here are a few examples to get you started.

Please note that data is returned by reference, this means that modifications to returned objects may change the database. To avoid such behaviour, you need to use .cloneDeep().

Also, the execution of methods is lazy, that is, execution is deferred until .value() is called.

Examples

Check if posts exists.

db.has('posts')
  .value()

Set posts.

db.set('posts', [])
  .value()

Sort the top five posts.

db.get('posts')
  .filter({published: true})
  .sortBy('views')
  .take(5)
  .value()

Get post titles.

db.get('posts')
  .map('title')
  .value()

Get the number of posts.

db.get('posts')
  .size()
  .value()

Get the title of first post using a path.

db.get('posts[0].title')
  .value()

Update a post.

db.get('posts')
  .find({ title: 'low!' })
  .assign({ title: 'hi!'})
  .value()

Remove posts.

db.get('posts')
  .remove({ title: 'low!' })
  .value()

Make a deep clone of posts.

db.get('posts')
  .cloneDeep()
  .value()

How to use id based resources

Being able to get data using an id can be quite useful, particularly in servers. To add id-based resources support to lowdb, you have 2 options.

underscore-db provides a set of helpers for creating and manipulating id-based resources.

const db = low('db.json')

db._.mixin(require('underscore-db'))

const postId = db.get('posts').insert({ title: 'low!' }).value().id
const post = db.get('posts').getById(postId).value()

uuid is more minimalist and returns a unique id that you can use when creating resources.

const uuid = require('uuid')

const postId = db.get('posts').push({ id: uuid(), title: 'low!' }).value().id
const post = db.get('posts').find({ id: postId }).value()

How to use a custom storage or format

low() accepts custom storage or format. Simply create objects with read/write or serialize/deserialize methods. See src/browser.js code source for a full example.

const myStorage = {
  read: (source, deserialize) => // must return an object or a Promise
  write: (source, obj, serialize) => // must return undefined or a Promise
}

const myFormat = {
  serialize: (obj) => // must return data (usually string)
  deserialize: (data) => // must return an object
}

low(source, {
  storage: myStorage,
  format: myFormat
})

How to encrypt data

Simply encrypt and decrypt data in format.serialize and format.deserialize methods.

For example, using cryptr:

const Cryptr = require("./cryptr"),
const cryptr = new Cryptr('my secret key')

const db = low('db.json', {
  format: {
    deserialize: (str) => {
      const decrypted = cryptr.decrypt(str)
      const obj = JSON.parse(decrypted)
      return obj
    },
    serialize: (obj) => {
      const str = JSON.stringify(obj)
      const encrypted = cryptr.encrypt(str)
      return encrypted
    }
  }
})

Changelog

See changes for each version in the release notes.

Limits

lowdb is a convenient method for storing data without setting up a database server. It is fast enough and safe to be used as an embedded database.

However, if you seek high performance and scalability more than simplicity, you should probably stick to traditional databases like MongoDB.

License

MIT - Typicode