SDKs overview

Micro DB, primarily known through its core product lowdb, is a JSON-based database designed for simplicity and ease of use in JavaScript and Node.js applications. It stores data directly in a single JSON file, making it suitable for scenarios where a full-fledged database server is not required or practical. The primary interaction method with lowdb is through its official JavaScript SDK, which provides a fluent API for common database operations such as creating, reading, updating, and deleting data.

The design philosophy of lowdb emphasizes minimal setup and a developer experience similar to working with JavaScript objects and arrays, particularly inspired by the Lodash utility library. This approach aims to reduce the learning curve for developers familiar with JavaScript, enabling rapid prototyping and local data persistence. While the official offering is focused on JavaScript, its open-source nature allows for community-driven extensions and integrations, though these are less prevalent due to its niche as an embedded, file-based database.

Developers typically integrate lowdb directly into their application's codebase, managing the JSON file that serves as the database. This direct integration eliminates the need for network calls or external database configurations, streamlining development workflows for specific use cases. The SDK handles file I/O and data serialization internally, abstracting these details from the developer.

Official SDKs by language

The primary and official SDK for Micro DB (lowdb) is developed in JavaScript. It is designed to run in both Node.js environments and modern web browsers, providing a consistent API across different JavaScript execution contexts. This single SDK serves as the foundational tool for all interactions with lowdb databases.

The official SDK is maintained by the project's creators and is distributed via npm, the package manager for JavaScript. Its API is well-documented within the project's GitHub repository README, detailing methods for data manipulation, querying, and configuration. The SDK's design prioritizes a straightforward, synchronous-like interaction model for common operations, though asynchronous adapters are available for more complex I/O patterns.

Below is a summary of the official SDK:

Language Package Name Install Command Maturity
JavaScript lowdb npm install lowdb Stable

The SDK's architecture supports different storage adapters, allowing developers to choose how data is persisted. The default adapter uses a simple JSON file, but community contributions or custom implementations can extend this to other file formats or storage mechanisms. This flexibility, while not part of the core official distribution, is enabled by the SDK's modular design.

Installation

Installing the Micro DB (lowdb) SDK is a standard process for JavaScript projects using npm. The installation procedure typically involves adding the lowdb package as a dependency to your project.

Prerequisites

  • Node.js and npm installed on your development machine. You can verify your installation by running node -v and npm -v in your terminal. For installation instructions, refer to the official Node.js download page.
  • A JavaScript project or a simple script where you intend to use lowdb.

Installation Steps

To install the official lowdb package, navigate to your project's root directory in your terminal and execute the following command:

npm install lowdb

This command downloads the lowdb package and its dependencies and adds them to your project's node_modules directory. It also updates your package.json file to include lowdb as a dependency, ensuring that other developers working on your project can easily install it.

For projects using Yarn, an alternative package manager, the command is:

yarn add lowdb

After installation, you can import and use lowdb in your JavaScript files. The package provides both CommonJS and ES module exports, allowing compatibility with various module systems used in Node.js and modern browser environments. For example, in a Node.js environment, you might use require('lowdb'), while in a modern front-end project with a bundler, you might use import lowdb from 'lowdb'.

Quickstart example

This quickstart demonstrates how to set up and perform basic operations with Micro DB (lowdb) in a Node.js environment. This example uses the JSONFile adapter, which is common for file-based persistence, and the Memory adapter for in-memory operations.

Step 1: Initialize the Database

First, import the necessary modules from lowdb. You'll need Low for the database instance and an adapter (e.g., JSONFile) to specify how data is stored.

import { Low } from 'lowdb';
import { JSONFile } from 'lowdb/node'; // For Node.js environment

// Use JSONFile for file-based storage
const adapter = new JSONFile('db.json');
const db = new Low(adapter, {}); // Default data is an empty object

// Read data from db.json. If file doesn't exist, it will be created with default data.
await db.read();

// If db.data is null (e.g., file was empty or new), set initial data
db.data = db.data || { posts: [], users: [] };

console.log('Database initialized:', db.data);

In this step, db.json will be created if it doesn't exist. The db.data property holds the current state of your database.

Step 2: Write Data

You can add data to your database by modifying the db.data object and then calling db.write() to persist the changes.

// 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 changes to the file
await db.write();

console.log('Data written:', db.data);

After running this, your db.json file will contain the added posts and users.

Step 3: Read Data

To read data, you simply access properties of db.data. After reading, you can manipulate the data using standard JavaScript array and object methods, similar to how you would with a standard JSON object.

// Find a post
const firstPost = db.data.posts.find(post => post.id === 1);
console.log('First post:', firstPost);

// Get all users
const allUsers = db.data.users;
console.log('All users:', allUsers);

Step 4: Update Data

Updating data involves finding the item, modifying its properties, and then calling db.write().

// Update the title of the first post
const postToUpdate = db.data.posts.find(post => post.id === 1);
if (postToUpdate) {
  postToUpdate.title = 'lowdb is even more awesome!';
}

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

console.log('Data updated:', db.data);

Step 5: Delete Data

Deleting data typically involves filtering arrays within db.data and then persisting the changes.

// Delete a user
db.data.users = db.data.users.filter(user => user.id !== 1);

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

console.log('Data after deletion:', db.data);

Complete Example

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

async function runLowdbExample() {
  const adapter = new JSONFile('db.json');
  const db = new Low(adapter, {});

  await db.read();
  db.data = db.data || { posts: [], users: [] };

  console.log('Initial DB state:', db.data);

  // Add data
  db.data.posts.push({ id: 1, title: 'lowdb is awesome', author: 'typicode' });
  db.data.users.push({ id: 1, name: 'Alice' });
  await db.write();
  console.log('After adding data:', db.data);

  // Read data
  const firstPost = db.data.posts.find(post => post.id === 1);
  console.log('Found post:', firstPost);

  // Update data
  if (firstPost) {
    firstPost.title = 'lowdb is even more awesome!';
    await db.write();
    console.log('After updating post:', db.data);
  }

  // Delete data
  db.data.users = db.data.users.filter(user => user.id !== 1);
  await db.write();
  console.log('After deleting user:', db.data);
}

runLowdbExample().catch(console.error);

This example demonstrates the fundamental CRUD (Create, Read, Update, Delete) operations using the lowdb SDK, highlighting its straightforward, file-based interaction model.

Community libraries

Given Micro DB's (lowdb) specific niche as a lightweight, JSON-based database primarily for JavaScript environments, the ecosystem of community-contributed libraries is typically focused on extending its core functionality or integrating it into specific frameworks. While lowdb itself is a community-driven open-source project, direct SDKs in other programming languages are less common due to its JavaScript-centric design and file-based nature.

Instead, community contributions often take the form of:

  • Storage Adapters: Developers might create custom adapters to store lowdb data in different locations or formats beyond the default JSON file. This could include browser local storage, session storage, or even remote storage with custom synchronization logic. These adapters typically implement the lowdb adapter interface, allowing them to plug directly into the core library.
  • Framework Integrations: Utilities or helper libraries might emerge to simplify lowdb's use within specific JavaScript frameworks like React, Vue, or Angular, or backend frameworks like Express.js. These integrations often aim to manage database instances, provide reactive data access, or integrate lowdb into a framework's state management patterns.
  • Migration Tools: As projects evolve, there might be a need to migrate data from lowdb to a more robust database like SQLite or MongoDB. Community scripts or tools could assist in converting lowdb's JSON data structure into a format compatible with other database systems.
  • TypeScript Definitions: While lowdb aims to provide its own TypeScript definitions, community efforts sometimes contribute to improving these definitions or creating more specific type helpers for complex data structures.

Because lowdb is fundamentally a JavaScript library, developers in other languages would typically interact with it indirectly, for example, by building a Node.js API layer that uses lowdb and then consuming that API from a different language. The project's GitHub repository is the primary hub for discovering such community contributions, often found in the discussions, issues, or linked projects sections.