The definitive source of the best
JavaScript libraries, frameworks, and plugins.

  • ×

    An extendable JSON database for Node and the browser powered by lodash
    Filed under 

    • 🔾81%Overall
    • 14,323
    • 13.6 days
    • 🕩671
    • 👥16


    Build Status npm

    Small JSON database for Node, Electron and the browser. Powered by Lodash. :zap:

      .push({ id: 1, title: 'lowdb is awesome'})


    npm install lowdb
    const low = require('lowdb')
    const FileSync = require('lowdb/adapters/FileSync')
    const adapter = new FileSync('db.json')
    const db = low(adapter)
    // Set some defaults (required if your JSON file is empty)
    db.defaults({ posts: [], user: {}, count: 0 })
    // Add a post
      .push({ id: 1, title: 'lowdb is awesome'})
    // Set a user using Lodash shorthand syntax
    db.set('', 'typicode')
    // Increment count
    db.update('count', n => n + 1)

    Data is saved to db.json

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

    You can use any of the powerful lodash functions, like _.get and _.find with shorthand syntax.

    // For performance, use .value() instead of .write() if you're only reading from db
      .find({ id: 1 })

    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, if you know Lodash, you already know how to use lowdb :wink:

    Important lowdb doesn't support Cluster and may have issues with very large JSON files (~200MB).


    npm install lowdb

    Alternatively, if you're using yarn

    yarn add lowdb

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

    <script src=""></script>
    <script src=""></script>
    <script src=""></script>
      var adapter = new LocalStorage('db')
      var db = low(adapter)



    Returns a lodash chain with additional properties and functions described below.

    db.[...].write() and db.[...].value()

    write() writes database to state.

    On the other hand, value() is just _.prototype.value() and should be used to execute a chain that doesn't change database state.

    db.set('', 'typicode')

    Please note that db.[...].write() is syntactic sugar and equivalent to

    db.set('', 'typicode')


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

      second: function(array) {
        return array[1]


    Returns database state.

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


    Replaces database state.

    const newState = {}


    Persists database using adapter.write (depending on the adapter, may return a promise).

    // With lowdb/adapters/FileSync
    console.log('State has been saved')
    // With lowdb/adapters/FileAsync
      .then(() => console.log('State has been saved'))

    Reads source using option (depending on the adapter, may return a promise).

    // With lowdb/FileSync
    console.log('State has been updated')
    // With lowdb/FileAsync
      .then(() => console.log('State has been updated'))

    Adapters API

    Please note this only applies to adapters bundled with Lowdb. Third-party adapters may have different options.

    For convenience, FileSync, FileAsync and LocalBrowser accept the following options:

    • defaultValue if file doesn't exist, this value will be used to set the initial state (default: {})
    • serialize/deserialize functions used before writing and after reading (default: JSON.stringify and JSON.parse)
    const adapter = new FileSync('array.yaml', {
      defaultValue: [],
      serialize: (array) => toYamlString(array),
      deserialize: (string) => fromYamlString(string)


    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() or .write() is called.

    Reading from existing JSON file

    If you are reading from a file adapter, the path is relative to execution path (CWD) and not to your code.


    So then you read it like this:

    // file src/my_example.js
    const adapter = new FileSync('db.json')
    // With lowdb/FileAsync
      .then(() => console.log('Content of my_project/db.json is loaded'))


    Check if posts exists.


    Set posts.

    db.set('posts', [])

    Sort the top five posts.

      .filter({published: true})

    Get post titles.


    Get the number of posts.


    Get the title of first post using a path.


    Update a post.

      .find({ title: 'low!' })
      .assign({ title: 'hi!'})

    Remove posts.

      .remove({ title: 'low!' })

    Remove a property.


    Make a deep clone of posts.


    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.


    const { nanoid } = require("nanoid")
    const idlength = 8
    const postId = db
      .push({ id: nanoid(idlength), title: 'low!' })
    const post = db
      .find({ id: postId })

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

    const lodashId = require('lodash-id')
    const FileSync = require('lowdb/adapters/FileSync')
    const adapter = new FileSync('db.json')
    const db = low(adapter)
    // We need to set some default values, if the collection does not exist yet
    // We also can store our collection
    const collection = db
      .defaults({ posts: [] })
    // Insert a new post...
    const newPost = collection
      .insert({ title: 'low!' })
    // ...and retrieve it using its id
    const post = collection

    How to create custom adapters

    low() accepts custom Adapter, so you can virtually save your data to any storage using any format.

    class MyStorage {
      constructor() {
        // ...
      read() {
        // Should return data (object or array) or a Promise
      write(data) {
        // Should return nothing or a Promise
    const adapter = new MyStorage(args)
    const db = low(adapter)

    See src/adapters for examples.

    How to encrypt data

    FileSync, FileAsync and LocalStorage accept custom serialize and deserialize functions. You can use them to add encryption logic.

    const adapter = new FileSync('db.json', {
      serialize: (data) => encrypt(JSON.stringify(data)),
      deserialize: (data) => JSON.parse(decrypt(data))


    See changes for each version in the release notes.


    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.


    MIT - Typicode :cactus:

    Show All