Superseded by classic-level. Pure C++ Node.js LevelDB binding. An abstract-leveldown compliant store.
Superseded by classic-level. Pure C++ Node.js LevelDB binding. An abstract-leveldown compliant store.
Superseded by classic-level. Please see Frequently Asked Questions.
Click to expand
db = leveldown(location)db.open([options, ]callback)
db.close(callback)db.put(key, value[, options], callback)
db.get(key[, options], callback)
db.getMany(keys[, options][, callback])db.del(key[, options], callback)
db.batch(operations[, options], callback) (array form)db.batch() (chained form)db.approximateSize(start, end, callback)db.compactRange(start, end, callback)db.getProperty(property)db.iterator([options])db.clear([options, ]callback)chainedBatch
iterator
leveldown.destroy(location, callback)leveldown.repair(location, callback)This module was originally part of levelup but was later extracted 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.
We aim to support at least Active LTS and Current Node.js releases, Electron 5.0.0, as well as any future Node.js and Electron releases thanks to N-API. The minimum node version for leveldown is 10.12.0. Conversely, for node >= 12, the minimum leveldown version is 5.0.0.
The leveldown npm package ships with prebuilt binaries for popular 64-bit platforms as well as ARM, M1, Android and Alpine (musl) and is known to work on:
When installing leveldown, node-gyp-build will check if a compatible binary exists and fallback to a compile step if it doesn't. In that case you'll need a valid node-gyp installation.
If you don't want to use the prebuilt binary for the platform you are installing on, specify the --build-from-source flag when you install. One of:
npm install --build-from-source
npm install leveldown --build-from-sourceIf you are working on leveldown itself and want to re-compile the C++ code, run npm run rebuild.
leveldown >= 5. This can be checked by running npm ls leveldown.leveldown to >= 5.3.0 or use --build-from-source.--build-from-source. This is no longer the case.nodejs-mobile fork.If you are upgrading: please see UPGRADING.md.
db = leveldown(location)Returns a new leveldown instance. location is a String pointing to the LevelDB location to be opened.
db.open([options, ]callback)Open the store. 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.
optionsThe optional options argument may contain:
createIfMissing (boolean, default: true): If true, will initialise an empty database at the specified location if one doesn't already exist. If false and a database doesn't exist you will receive an error in your open() callback and your database won't open.
errorIfExists (boolean, default: false): If true, you will receive an error in your open() callback if the database exists at the specified location.
compression (boolean, default: true): If true, all compressible data will be run through the Snappy compression algorithm before being stored. Snappy is very fast and shouldn't gain much speed by disabling so leave this on unless you have good reason to turn it off.
cacheSize (number, default: 8 * 1024 * 1024 = 8MB): The size (in bytes) of the in-memory LRU cache with frequently used uncompressed block contents.
Advanced options
The following options are for advanced performance tuning. Modify them only if you can prove actual benefit for your particular application.
writeBufferSize (number, default: 4 * 1024 * 1024 = 4MB): The maximum size (in bytes) of the log (in memory and stored in the .log file on disk). Beyond this size, LevelDB will convert the log data to the first level of sorted table files. From the LevelDB documentation: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.
blockSize (number, default 4096 = 4K): The approximate size of the blocks that make up the table files. The size related to uncompressed data (hence "approximate"). Blocks are indexed in the table file and entry-lookups involve reading an entire block and parsing to discover the required entry.
maxOpenFiles (number, default: 1000): The maximum number of files that LevelDB is allowed to have open at a time. If your data store is likely to have a large working set, you may increase this value to prevent file descriptor churn. To calculate the number of files required for your working set, divide your total data by 'maxFileSize'.
blockRestartInterval (number, default: 16): The number of entries before restarting the "delta encoding" of keys within blocks. Each "restart" point stores the full key for the entry, between restarts, the common prefix of the keys for those entries is omitted. Restarts are similar to the concept of keyframes in video encoding and are used to minimise the amount of space required to store keys. This is particularly helpful when using deep namespacing / prefixing in your keys.
maxFileSize (number, default: 2* 1024 * 1024 = 2MB): The maximum amount of bytes to write to a file before switching to a new one. From the LevelDB documentation:
... if your filesystem is more efficient with larger files, you could consider increasing the value. The downside will be longer compactions and hence longer latency/performance hiccups. Another reason to increase this parameter might be when you are initially populating a large database.
db.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 waits for any pending operations to finish before closing. For example:
db.put('key', 'value', function (err) {
// This happens first
})
db.close(function (err) {
// This happens second
})db.put(key, value[, options], callback)Store a new entry or overwrite an existing entry.
The key and value objects may either be strings or Buffers. Other object types are converted to 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 may not be null or undefined. Values of '', [] and Buffer.alloc(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 Buffer.alloc(0) depending on the type requested.
A richer set of data-types is catered for in levelup.
optionsThe 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.
db.get(key[, options], callback)Get a value from the LevelDB store by key.
The key object may either be a string or a Buffer and cannot be undefined or null. Other object types are converted to strings with the toString() method and the resulting string may not be a zero-length. A richer set of data-types is catered for in levelup.
Values fetched via get() that are stored as zero-length character arrays (null, undefined, '', [], Buffer.alloc(0)) will return as empty-String ('') or Buffer.alloc(0) when fetched with asBuffer: true (see below).
optionsThe optional options object may contain:
asBuffer (boolean, default: true): Used to determine whether to return the value of the entry as a string or a Buffer. Note that converting from a Buffer to a string incurs a cost so if you need a string (and the value can legitimately become a UTF8 string) then you should fetch it as one with { asBuffer: false } and you'll avoid this conversion cost.fillCache (boolean, default: true): LevelDB will by default fill the in-memory LRU Cache with data from a call toNo open issues yet, or sync has not completed.