leveldown中文手册

LevelDOWN

LevelDB Logo

A Low-level Node.js LevelDB binding

build|passing build|passing dependencies

leveldown-npm

LevelDOWN was extracted from LevelUP and now serves as a stand-alone binding for LevelDB.

It is strongly recommended that you use LevelUP in preference to LevelDOWN unless you have measurable performance reasons to do so. LevelUP is optimised for usability and safety. Although we are working to improve the safety of the LevelDOWN interface it is still easy to crash your Node process if you don't do things in just the right way.

See the section on safety below for details of known unsafe operations with LevelDOWN.

Tested & supported platforms

API


leveldown(location)

leveldown() returns a new LevelDOWN instance. location is a String pointing to the LevelDB location to be opened.


leveldown#open([options, ]callback)

open() is an instance method on an existing database object.

The callback function will be called with no arguments when the database has been successfully opened, or with a single error argument if the open operation failed for any reason.

options

The optional options argument may contain:

Advanced options

The following options are for advanced performance tuning. Modify them only if you can prove actual benefit for your particular application.

Larger values increase performance, especially during bulk loads. Up to two write buffers may be held in memory at the same time, so you may wish to adjust this parameter to control memory usage. Also, a larger write buffer will result in a longer recovery time the next time the database is opened.


leveldown#close(callback)

close() is an instance method on an existing database object. The underlying LevelDB database will be closed and the callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#put(key, value[, options], callback)

put() is an instance method on an existing database object, used to store new entries, or overwrite existing entries in the LevelDB store.

The key and value objects may either be Strings or Node.js Buffer objects. Other object types are converted to JavaScript Strings with the toString() method. Keys may not be null or undefined and objects converted with toString() should not result in an empty-string. Values of null, undefined, '', [] and new Buffer(0) (and any object resulting in a toString() of one of these) will be stored as a zero-length character array and will therefore be retrieved as either '' or new Buffer(0) depending on the type requested.

A richer set of data-types are catered for in LevelUP.

options

The only property currently available on the options object is 'sync' (boolean, default: false). If you provide a 'sync' value of true in your options object, LevelDB will perform a synchronous write of the data; although the operation will be asynchronous as far as Node is concerned. Normally, LevelDB passes the data to the operating system for writing and returns immediately, however a synchronous write will use fsync() or equivalent so your callback won't be triggered until the data is actually on disk. Synchronous filesystem writes are significantly slower than asynchronous writes but if you want to be absolutely sure that the data is flushed then you can use 'sync': true.

The callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#get(key[, options], callback)

get() is an instance method on an existing database object, used to fetch individual entries from the LevelDB store.

The key object may either be a String or a Node.js Buffer object and cannot be undefined or null. Other object types are converted to JavaScript Strings with the toString() method and the resulting String may not be a zero-length. A richer set of data-types are catered for in LevelUP.

Values fetched via get() that are stored as zero-length character arrays (null, undefined, '', [], new Buffer(0)) will return as empty-String ('') or new Buffer(0) when fetched with asBuffer: true (see below).

options

The optional options object may contain:

The callback function will be called with a single error if the operation failed for any reason. If successful the first argument will be null and the second argument will be the value as a String or Buffer depending on the asBuffer option.


leveldown#del(key[, options], callback)

del() is an instance method on an existing database object, used to delete entries from the LevelDB store.

The key object may either be a String or a Node.js Buffer object and cannot be undefined or null. Other object types are converted to JavaScript Strings with the toString() method and the resulting String may not be a zero-length. A richer set of data-types are catered for in LevelUP.

options

The only property currently available on the options object is 'sync' (boolean, default: false). See leveldown#put() for details about this option.

The callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#batch(operations[, options], callback)

batch() is an instance method on an existing database object. Used for very fast bulk-write operations (both put and delete). The operations argument should be an Array containing a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation inside LevelDB.

Each operation is contained in an object having the following properties: type, key, value, where the type is either 'put' or 'del'. In the case of 'del' the 'value' property is ignored. Any entries with a 'key' of null or undefined will cause an error to be returned on the callback. Any entries where the type is 'put' that have a 'value' of undefined, null, [], '' or new Buffer(0) will be stored as a zero-length character array and therefore be fetched during reads as either '' or new Buffer(0) depending on how they are requested.

See LevelUP for full documentation on how this works in practice.

options

The only property currently available on the options object is 'sync' (boolean, default: false). See leveldown#put() for details about this option.

The callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#approximateSize(start, end, callback)

approximateSize() is an instance method on an existing database object. Used to get the approximate number of bytes of file system space used by the range [start..end). The result may not include recently written data.

The start and end parameters may be either String or Node.js Buffer objects representing keys in the LevelDB store.

The callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#compactRange(start, end, callback)

compactRange() is an instance method on an existing database object. Used to manually trigger a database compaction in the range [start..end).

The start and end parameters may be either String or Node.js Buffer objects representing keys in the LevelDB store.

The callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown#getProperty(property)

getProperty can be used to get internal details from LevelDB. When issued with a valid property string, a readable string will be returned (this method is synchronous).

Currently, the only valid properties are:


leveldown#iterator([options])

iterator() is an instance method on an existing database object. It returns a new Iterator instance.

options

The optional options object may contain:


iterator#next(callback)

next() is an instance method on an existing iterator object, used to increment the underlying LevelDB iterator and return the entry at that location.

the callback function will be called with no arguments in any of the following situations:

Otherwise, the callback function will be called with the following 3 arguments:


iterator#seek(key)

seek() is an instance method on an existing iterator object, used to seek the underlying LevelDB iterator to a given key.

By calling seek(key), subsequent calls to next(cb) will return key/values larger or smaller than key, based on your reverse setting in the iterator constructor.


iterator#end(callback)

end() is an instance method on an existing iterator object. The underlying LevelDB iterator will be deleted and the callback function will be called with no arguments if the operation is successful or with a single error argument if the operation failed for any reason.


leveldown.destroy(location, callback)

destroy() is used to completely remove an existing LevelDB database directory. You can use this function in place of a full directory rm if you want to be sure to only remove LevelDB-related files. If the directory only contains LevelDB files, the directory itself will be removed as well. If there are additional, non-LevelDB files in the directory, those files, and the directory, will be left alone.

The callback will be called when the destroy operation is complete, with a possible error argument.


leveldown.repair(location, callback)

repair() can be used to attempt a restoration of a damaged LevelDB store. From the LevelDB documentation:

If a DB cannot be opened, you may attempt to call this method to resurrect as much of the contents of the database as possible. Some data may be lost, so be careful when calling this function on a database that contains important information.

You will find information on the repair operation in the LOG file inside the store directory.

A repair() can also be used to perform a compaction of the LevelDB log into table files.

The callback will be called when the repair operation is complete, with a possible error argument.

Safety