mdbxjs

A Node.js binding for libmdbx - a fast, compact, embeddable key-value database.

Features

• Full binding to the libmdbx C API
• Simple JavaScript-friendly API
• TypeScript support
• Beginner-friendly interface with reasonable defaults
• Promise-based and callback-based interfaces
• Handles Buffer, string, number, and JSON values automatically
• Comprehensive error messages

Installation

# With npm
npm install mdbxjs

# With yarn
yarn add mdbxjs

Prerequisites

To build the native module, you'll need:

• Node.js 12.x or later
• npm 6.x or later
• CMake 3.10 or later
• A C/C++ compiler toolchain (GCC, Clang, or MSVC)

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install -y cmake build-essential

On macOS:

brew install cmake

On Windows:

• Install Visual Studio with C++ development tools
• Install CMake from https://cmake.org/download/

Development Installation

If you want to build from source:

git clone https://github.com/anders94/mdbxjs.git
cd mdbxjs
npm install

Simple Usage

const mdbx = require('mdbxjs');

// Open database with default options
const env = mdbx.open('./my-data');

// Create a collection (database)
const users = mdbx.collection(env, 'users');

// Store data
users.put('user:1', { name: 'Alice', email: '[email protected]' });
users.put('user:2', { name: 'Bob', email: '[email protected]' });

// Retrieve data
const user = users.get('user:1');
console.log(user); // { name: 'Alice', email: '[email protected]' }

// Query data
const results = users.find({ 
  gte: 'user:1', 
  lte: 'user:2'
});
console.log(results); 

// Delete data
users.del('user:1');

// Close the environment when done
env.close();

Advanced Usage

const mdbx = require('mdbxjs');
const { EnvFlags, DatabaseFlags, WriteFlags, TransactionMode } = mdbx;

// Open environment with specific options
const env = new mdbx.Environment();
env.open({
  path: './my-data',
  mapSize: 1024 * 1024 * 1024, // 1GB
  maxDbs: 10,
  flags: EnvFlags.NOSYNC | EnvFlags.WRITEMAP
});

// Begin transaction
const txn = env.beginTransaction({
  mode: TransactionMode.READWRITE
});

// Open database
const db = env.openDatabase({
  name: 'users',
  create: true,
  flags: DatabaseFlags.CREATE
});

try {
  // Write data
  txn.put(db, 'user:1', JSON.stringify({ name: 'Alice' }));
  
  // Read data
  const data = txn.get(db, 'user:1');
  console.log(JSON.parse(data.toString()));
  
  // Delete data
  txn.del(db, 'user:1');
  
  // Use a cursor for more advanced operations
  const cursor = txn.openCursor(db);
  
  // Commit the transaction
  txn.commit();
} catch (err) {
  // Abort the transaction on error
  txn.abort();
  throw err;
} finally {
  // Close database when done
  db.close();
  
  // Close environment
  env.close();
}

Examples

See the examples directory for more usage examples.

API Documentation

Environment Class

The main entry point for working with an MDBX database.

new Environment(options?)

Creates a new environment object.

open(options?)

Opens the environment with the given options.

Options:

• path: Path to database directory (default: './mdbxjs-data')
• mapSize: Maximum size of the memory map (default: 10GB)
• maxDbs: Maximum number of databases (default: 10)
• maxReaders: Maximum number of reader slots (default: 126)
• flags: Environment flags

close()

Closes the environment.

beginTransaction(options?)

Begins a new transaction.

Options:

• mode: TransactionMode.READONLY or TransactionMode.READWRITE
• parent: Parent transaction for nested transactions

openDatabase(options?)

Opens a database within the environment.

Options:

• name: Database name (null for default database)
• create: Whether to create the database if it doesn't exist
• flags: Database flags

sync(force?)

Flushes data to disk.

stat()

Returns statistics about the environment.

info()

Returns information about the environment.

copy(path)

Copies the environment to a new location.

setMapSize(size)

Changes the maximum size of the memory map.

Transaction Class

A transaction for working with a database.

abort()

Aborts the transaction.

commit()

Commits the transaction.

reset()

Resets a read-only transaction.

renew()

Renews a read-only transaction.

get(dbi, key)

Gets a value from the database.

put(dbi, key, value, flags?)

Stores a key-value pair in the database.

del(dbi, key, value?)

Deletes a key-value pair from the database.

openCursor(dbi)

Opens a cursor for the database.

Database Class

A handle to a specific database within an environment.

close()

Closes the database.

drop()

Deletes the database and all its data.

stat(txn)

Returns statistics about the database.

Cursor Class

A cursor for traversing a database.

close()

Closes the cursor.

del(flags?)

Deletes the current key-value pair.

get(op, key?, value?)

Retrieves data based on the cursor operation.

put(key, value, flags?)

Stores a key-value pair using the cursor.

count()

Returns the number of duplicate values for the current key.

Simplified Interface

open(path, options?)

Opens an environment with simplified options.

collection(env, name?, options?)

Creates a simplified database interface with the following methods:

• get(key, txnOptions?)
• put(key, value, txnOptions?)
• del(key, txnOptions?)
• find(options)
• count(txnOptions?)
• drop()
• clear()

License

MIT