node-berkeleydb

Nodejs bindings for Berkeley DB 6.x

Based on the initial work dbstore by Lee Iverson.

Installation

npm install berkeleydb

Usage

var bdb = require("berkeleydb");

All calls are synchronous, since berkeleydb itself is synchronous.

DB

Represents a Berkeley DB database object. Provides a simple put/get/del synchronous interface.

varbdb=require("berkeleydb");vardb=newbdb.Db();// create a new Db objectdbenv.open("filename.db");varkey="foo";varval="bar";// data accessdb.put(key,val);// putvarout1=db.get(key)// getdb.del(key);// delvarout2=db.get(key);// get deleted keyassert(out1.toString()===val);assert(out2.toString()==="");// delete all keysdb.truncate();db.close()

• new bdb.Db([dbenv]) - Creates a new Db instance.
  • param: [dbenv] - [bdb.DbEnv] - Optional, but needed if you wish to use transactions.
  • returns [bdb.Db] - A new Db instance.
• open(filename, [db]) - Opens a local db file. Will create file if it doesn't exist.
  • param: filename - [String] - The filename of the db to load, relative to the process.cwd.
  • param: db - [String] - The name of the sub-database to load.
  • returns [number] - 0 if successful, otherwise an error occurred.
• close() - Closes a database file. This is neccessary before shutdown to avoid data corruption.
  • returns [number] - 0 if successful, otherwise an error occurred.
• get(key, [opts]) - Gets a value from the db.
  • param: key - [String] - The key of the value to get.
  • param: [opts] - [Object] - An options object.
  • returns [Buffer|String|Object] - The data stored at the key - "" if the key doesn't exist, a String is returned if opts.encoding is set, an Object if opts.json is set to true, otherwise as a Buffer.
• put(key, val, [opts]) - Stores or updates a value at the given key.
  • param: key - [String] - The key to store/update.
  • param: val - [Buffer|String|Object] - The value to store.
  • param: [opts] - [Object] - An options object.
  • returns [number] - 0 if successful, otherwise an error occurred.
• del(key, [opts]) - Deletes a key.
  • param: key - [String] - The key to delete.
  • param: [opts] - [Object] - An options object.
  • returns [number] - 0 if successful, otherwise an error occurred.
• truncate() - Deletes all keys in the db.
  • returns [number] - 0 if successful, otherwise an error occurred.

Options object

The following options are available for the put/get/del methods:

• opts.json - [Boolean] - Store or retrieve value as a json object. Uses JSON.stringify/JSON.parse on value.
• opts.encoding - [String] - If specified, the buffer will be encoded/decoded as the specified format and stored/returned as a String.
• opts.txn - [bdb.DbTxn] - Apply the operation to the given transaction. This will not perform the operation until the transaction is commited.

// get/put support 'json' as an optionvaropts={json: true};varput_data={test: "json1",n: 1};db.put("json",put_data,opts)vardata=db.get("json",opts);assert(typeofdata=='object');assert(data.test==put_data.test);assert(data.n==put_data.n);// get/put support 'json' as an optionvaropts={encoding: 'hex'};varenc_str="4f4ca1";db.put("hex",enc_str,opts)varout=db.get("hex",opts);assert(enc_str==out);

DB_ENV

A DbEnv enables logging, transactions and other berkeley db features, and instead of using a single file, it can store multiple files (dbs) in a directory, along with meta data.

vardbenv=newbdb.DbEnv();console.log("open env",dbenv.open("db"));// Pass the dbenv into the db constructorvardb=newbdb.Db(dbenv);dbenv.open("filename.db");
...
// make sure to close the db firstdb.close();dbenv.close();

• new bdb.DbEnv() - Creates a new DbEnv instance.
  • returns [bdb.DbEnv] - A new DbEnv instance.
• open(dirname) - Opens a local db env directory. The folder must exist before execution, but may be empty uninitialized.
  • param: dirname - [String] - The path of the db directory to use, relative to the process.cwd.
  • returns [number] - 0 if successful, otherwise an error occurred.
• close() - Closes a database dir. This is neccessary before shutdown to avoid data corruption, but after Db.close().
  • returns [number] - 0 if successful, otherwise an error occurred.

DB_TXN

Transactions provides ACID-ity to the db operations. See Berkeley Db Transaction Documentation for full explanation.

// pass DbEnv into DbTxn constructorvartxn=newbdb.DbTxn(dbenv);vartxn2=newbdb.DbTxn(dbenv);// pass txn into optionsvaropts={"txn": txn};varopts2={"txn": txn2};// commitdb.put("1","one",opts);db.put("2","two",opts);db.put("3","three",opts);txn.commit();varout1=db.get("1");varout2=db.get("2");varout3=db.get("3");assert("one"==out1);assert("two"==out2);assert("three"==out3);// abortdb.put("4","four",opts2);db.put("5","five",opts2);db.put("6","six",opts2);txn2.abort();varout4=db.get("4");varout5=db.get("5");varout6=db.get("6");assert(""==out4);assert(""==out5);assert(""==out6);

• new bdb.DbTxn([dbenv]) - Creates a new Db instance.
  • param: [dbenv] - [bdb.DbEnv] - The env to acquire a txn from.
  • returns [bdb.DbTxn] - A new DbTxn instance.
• commit() - Commits the operations associated to the transaction, with appropriate locking.
  • returns [number] - 0 if successful, otherwise an error occurred.
• abort() - Aborts the transaction.
  • returns [number] - 0 if successful, otherwise an error occurred.

DBCursor

Represents a Berkeley DBCursor database object. Allows moving the cursor to a given record, fetching the current record and enumerate over all keys, forward or backward.

// create the cursor, pass in the Db, and a new DbTxn if the Db is in an envvartxn=newbdb.DbTxn(dbenv);varcursor=newbdb.DbCursor(dbtxn);// put some sample data in the dbdb.put("1","one");db.put("2","two");db.put("3","three");db.put("4","four");// get and move the cursor to the next element (starts at first, if not set)varres=cursor.next();assert(res.key=="1");assert(res.value.toString()=="one");// get and move the cursor to the last elementres=cursor.last();assert(res.key=="4");assert(res.value.toString()=="four");// get and move the cursor to the prev elementres=cursor.prev();assert(res.key=="3");assert(res.value.toString()=="three");// get and move the cursor to element with key = "2"res=cursor.set("2");assert(res.key=="2");assert(res.value.toString()=="two");// put a value at the current elementres=cursor.put("twotwo");assert(res==0);// get the current element, dont moveres=cursor.current();assert(res.key=="2");assert(res.value.toString()=="twotwo");// get and move the cursor to the first elementres=cursor.first();assert(res.key=="1");assert(res.value.toString()=="one");// before the first element isnullres=cursor.prev();assert(res.key==null);assert(res.value.toString()=="");// after the last element is also nullres=cursor.last();res=cursor.next();assert(res.key==null);assert(res.value.toString()=="");// iterate over all elements and delete each onecursor.first();cursor.del();cursor.next();cursor.del();cursor.next();cursor.del();cursor.next();cursor.del();// deleting removes without moving the cursor positionres=cursor.current();assert(res.key==null);assert(res.value.toString()=="");cursor.close();

• new bdb.DbCursor([db]) - Creates a new DbCursor instance.
  • param: [db] - [bdb.Db] - The database to create the cursor in.
  • returns [bdb.DbCursor] - A new DbCursor instance.
• close() - Closes a the cursor. No more data access is allowed.
  • returns [number] - 0 if successful, otherwise an error occurred.
• current([opts]) - Gets the current cursor key and value from the db. Does not move the cursor.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the current element.
• next([opts]) - Gets the next cursor key and value from the db. Moves the cursor to the next element.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the next element.
• prev([opts]) - Gets the previous cursor key and value from the db. Moves the cursor to the previous element.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the previous element.
• first([opts]) - Gets the first cursor key and value from the db. Moves the cursor to the first element.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the first element.
• last([opts]) - Gets the last cursor key and value from the db. Moves the cursor to the last element.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the last element.
• set(key, [opts]) - Moves the element to the key specified and returns the key and value from that position.
  • param: [opts] - [Object] - An options object.
  • returns [Object] {key: [String], value: [Buffer|String|Object]} - The key and value for the specified element.
• put(val, [opts]) - Stores or updates a value at the current cursor key.
  • param: val - [Buffer|String|Object] - The value to store.
  • param: [opts] - [Object] - An options object.
  • returns [number] - 0 if successful, otherwise an error occurred.
• del([opts]) - Deletes a key.
  • param: [opts] - [Object] - An options object.
  • returns [number] - 0 if successful, otherwise an error occurred.

Tests

npm test

Todo

• Implement Bulk search operations
• Implement DB_SEQUENCE
• Implement DB_LOGC

Licence

node-berkeleydb is licensed under an MIT license. All rights not explicitly granted in the MIT license are reserved. See the included LICENSE file for more details.