Micro DB Getting Started: Quickstart Guide (2026)

Getting started overview

Micro DB, specifically the lowdb library, facilitates local data persistence using a straightforward JSON file. This getting started guide outlines the necessary steps to set up lowdb in a Node.js project and perform basic data operations. The process involves installing the package, initializing a database instance, and then executing read, write, and update commands. Since lowdb is a client-side database, there are no external servers or accounts to provision; setup focuses on package management and code integration.

The following table provides a high-level overview of the getting started steps:

Create an account and get keys

Micro DB (lowdb) does not require account creation, API keys, or any form of external authentication. It is an embedded, file-based database. This means all data is stored locally within your project's file system, typically in a .json file, and accessed directly by your application code. There are no cloud services to register for or credentials to manage, simplifying the setup process significantly for local development or small, self-contained applications.

To begin, ensure you have Node.js installed, which includes npm, the Node.js package manager. These are the primary tools required to install and manage JavaScript libraries like lowdb in your development environment.

Your first request

This section guides you through installing lowdb and performing a basic write and read operation. You will create a simple JavaScript file, configure lowdb to use a JSON file as its persistence layer, and then interact with it.

Prerequisites

• Node.js and npm installed on your system.
• A text editor or IDE.

Step 1: Initialize a Node.js project

Open your terminal or command prompt, create a new directory for your project, and navigate into it. Then, initialize a new Node.js project:

mkdir microdb-example
cd microdb-example
npm init -y

The npm init -y command creates a package.json file with default values, which is necessary for managing project dependencies.

Step 2: Install lowdb

Install the lowdb package using npm:

npm install lowdb

This command adds lowdb to your project's node_modules directory and updates your package.json file to reflect the new dependency. Instructions are mirrored in the lowdb official installation guide.

Step 3: Create your application file

Create a new JavaScript file, for example, app.js, in your project directory. This file will contain the code to interact with lowdb.

Step 4: Initialize the database and perform operations

Add the following code to your app.js file. This code demonstrates how to set up lowdb with a file adapter, write initial data, and then read data from the database.

import { Low } from 'lowdb';
import { JSONFile } from 'lowdb/node';

// Configure the database file path
const file = 'db.json';
const adapter = new JSONFile(file);
const db = new Low(adapter, {}); // Default data is an empty object

async function run() {
  // Read data from db.json
  await db.read();

  // Set a default value if the database is empty (optional)
  db.data = db.data || { posts: [], users: [] };

  // Add a new post
  db.data.posts.push({ id: 1, title: 'lowdb is awesome', author: 'typicode' });

  // Add a new user
  db.data.users.push({ id: 1, name: 'Alice' });

  // Write the changes to db.json
  await db.write();

  console.log('Database initialized and data written.');

  // Read and log all posts
  console.log('\nAll Posts:');
  console.log(db.data.posts);

  // Filter and log specific posts (example of querying)
  const awesomePost = db.data.posts.find(post => post.title === 'lowdb is awesome');
  console.log('\nAwesome Post:');
  console.log(awesomePost);

  // Update a post
  if (awesomePost) {
    awesomePost.title = 'lowdb is even more awesome!';
    await db.write();
    console.log('\nPost updated and saved.');
    console.log(db.data.posts);
  }

  // Delete a user
  db.data.users = db.data.users.filter(user => user.id !== 1);
  await db.write();
  console.log('\nUser deleted and saved.');
  console.log(db.data.users);

  // Verify the content of the db.json file directly
  await db.read(); // Re-read to ensure we have the latest state
  console.log('\nFinal db.json content:');
  console.log(db.data);
}

run().catch(console.error);

Step 5: Run your application

Execute your app.js file from the terminal:

node app.js

You should see output in your console indicating that data has been written and read. More importantly, a new file named db.json will be created in your project directory. Open this file to inspect its contents. It will contain the JSON data that lowdb has persisted, reflecting the operations performed in app.js.

{
  "posts": [
    {
      "id": 1,
      "title": "lowdb is even more awesome!",
      "author": "typicode"
    }
  ],
  "users": []
}

This demonstrates a complete cycle of database initialization, data writing, and data reading with Micro DB (lowdb).

Common next steps

After successfully completing your first request with Micro DB (lowdb), consider these common next steps to further integrate and utilize it within your projects:

1. Explore Advanced Querying: lowdb's API is inspired by Lodash utilities, offering rich capabilities for querying, filtering, and manipulating data within your JSON structure. Familiarize yourself with methods like .filter(), .find(), .sortBy(), and .get() to handle more complex data retrieval scenarios. The official lowdb API documentation provides comprehensive examples.

2. Integrate with a Web Framework: For developing mock APIs or simple backend services, integrate lowdb with a lightweight web framework like Express.js. This allows you to create RESTful endpoints that serve and manage data from your lowdb instance, simulating a full-stack application experience without a complex database server.

3. Browser Usage: lowdb can also be used directly in the browser through a different adapter, typically LocalStorage. This enables client-side data persistence for single-page applications. Consult the lowdb adapters documentation for browser-specific setup.

4. Error Handling: Implement robust error handling around your database operations. While lowdb is generally stable, file system operations can fail (e.g., due to permissions issues or disk space). Wrapping await db.write() and await db.read() calls in try...catch blocks is a recommended practice.

5. Schema Enforcement (Optional): lowdb is schemaless by default, meaning you can store any valid JSON. For larger projects, you might consider implementing your own validation logic to ensure data consistency before writing to the database. Libraries like Joi or Yup can be used for this purpose.

6. Backup and Restoration: Since the database is a single JSON file, backing up involves simply copying the file. Consider strategies for backing up your db.json file, particularly in production-like environments where data integrity is critical, or for sharing data among development team members.

Troubleshooting the first call

When encountering issues with your initial Micro DB (lowdb) setup or first request, consider the following troubleshooting steps:

• Check Node.js and npm Installation: Verify that Node.js and npm are correctly installed and accessible from your terminal. Run node -v and npm -v to confirm their versions. If not, follow the official Node.js installation instructions.

• Verify lowdb Installation: Ensure that lowdb is listed in the dependencies section of your package.json file, and that the node_modules directory contains the lowdb package. If not, re-run npm install lowdb.

• File Path Issues: Double-check the file path provided to the JSONFile adapter (e.g., const file = 'db.json';). Ensure the path is correct relative to where your app.js script is executed. Incorrect paths can lead to the db.json file not being created or written to the expected location.

• Asynchronous Operations: lowdb operations like db.read() and db.write() are asynchronous and return Promises. Ensure you are using await with these calls inside an async function, or handling the Promises with .then() and .catch(). Neglecting this can lead to operations completing out of order or data not being persisted correctly.

  // Incorrect (might not write before exiting)
  // db.write();
  
  // Correct
  await db.write();
  

• Permissions Errors: If you receive errors related to file access or writing, check your file system permissions for the directory where db.json is supposed to be created. The Node.js process needs write access to this directory.

• Initial Data Handling: Remember to initialize db.data if it might be null or undefined, especially on the first run when db.json doesn't exist yet. The line db.data = db.data || { posts: [], users: [] }; in the example code handles this.

• Console Logging: Add strategic console.log() statements throughout your code to inspect the state of db.data at different points, and to confirm that each step of your application is reached and executed as expected.

• Refer to Official Documentation: The lowdb README on GitHub is the primary source for detailed information, examples, and troubleshooting tips. Reviewing the examples in the README can often clarify implementation details.