Home

Awesome

leveldown

:pushpin: This module will soon be deprecated, because it is superseded by classic-level.

level badge npm Node version Test Coverage Standard Common Changelog Donate

Table of Contents

<details><summary>Click to expand</summary> </details>

Introduction

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.

Supported Platforms

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-source

If you are working on leveldown itself and want to re-compile the C++ code, run npm run rebuild.

Notes

API

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.

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.

... 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.

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.

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).

options

The optional options object may contain:

The callback function will be called with a single error if the operation failed for any reason, including if the key was not found. 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.

db.getMany(keys[, options][, callback])

Get multiple values from the store by an array of keys. The optional options object may contain asBuffer and fillCache, as described in get().

The callback function will be called with an Error if the operation failed for any reason. If successful the first argument will be null and the second argument will be an array of values with the same order as keys. If a key was not found, the relevant value will be undefined.

If no callback is provided, a promise is returned.

db.del(key[, options], callback)

Delete an entry. 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.

options

The only property currently available on the options object is sync (boolean, default: false). See db.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.

db.batch(operations[, options], callback) (array form)

Perform multiple put and/or del operations in bulk. The operations argument must be an Array containing a list of operations to be executed sequentially, although as a whole they are performed as an atomic operation.

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 where the key or value (in the case of 'put') is 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 [], '' or Buffer.alloc(0) will be stored as a zero-length character array and therefore be fetched during reads as either '' or Buffer.alloc(0) depending on how they are requested. See levelup for full documentation on how this works in practice.

The optional options argument may contain:

The callback function will be called with no arguments if the batch is successful or with an Error if the batch failed for any reason.

db.batch() (chained form)

Returns a new chainedBatch instance.

db.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 strings or Buffers representing keys in the LevelDB store.

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 approximate size as a Number.

db.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 strings or Buffers 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.

db.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:

db.iterator([options])

Returns a new iterator instance. Accepts the following range options:

In addition to range options, iterator() takes the following options:

<sup>1</sup> leveldown returns an empty string rather than undefined at the moment.

db.clear([options, ]callback)

Delete all entries or a range. Not guaranteed to be atomic. Accepts the following range options (with the same rules as on iterators):

If no options are provided, all entries will be deleted. The callback function will be called with no arguments if the operation was successful or with an Error if it failed for any reason.

chainedBatch

chainedBatch.put(key, value)

Queue a put operation on this batch. This may throw if key or value is invalid, following the same rules as the array form of db.batch().

chainedBatch.del(key)

Queue a del operation on this batch. This may throw if key is invalid.

chainedBatch.clear()

Clear all queued operations on this batch.

chainedBatch.write([options, ]callback)

Commit the queued operations for this batch. All operations will be written atomically, that is, they will either all succeed or fail with no partial commits.

The optional options argument may contain:

The callback function will be called with no arguments if the batch is successful or with an Error if the batch failed for any reason. After write has been called, no further operations are allowed.

chainedBatch.db

A reference to the db that created this chained batch.

iterator

An iterator allows you to iterate the entire store or a range. It operates on a snapshot of the store, created at the time db.iterator() was called. This means reads on the iterator are unaffected by simultaneous writes.

Iterators can be consumed with for await...of or by manually calling iterator.next() in succession. In the latter mode, iterator.end() must always be called. In contrast, finishing, throwing or breaking from a for await...of loop automatically calls iterator.end().

An iterator reaches its natural end in the following situations:

An iterator keeps track of when a next() is in progress and when an end() has been called so it doesn't allow concurrent next() calls, it does allow end() while a next() is in progress and it doesn't allow either next() or end() after end() has been called.

for await...of iterator

Yields arrays containing a key and value. The type of key and value depends on the options passed to db.iterator().

try {
  for await (const [key, value] of db.iterator()) {
    console.log(key)
  }
} catch (err) {
  console.error(err)
}

iterator.next([callback])

Advance the iterator and yield the entry at that key. If an error occurs, the callback function will be called with an Error. Otherwise, the callback receives null, a key and a value. The type of key and value depends on the options passed to db.iterator(). If the iterator has reached its natural end, both key and value will be undefined.

If no callback is provided, a promise is returned for either an array (containing a key and value) or undefined if the iterator reached its natural end.

Note: Always call iterator.end(), even if you received an error and even if the iterator reached its natural end.

iterator.seek(key)

Seek the iterator to a given key or the closest key. Subsequent calls to iterator.next() will yield entries with keys equal to or larger than target, or equal to or smaller than target if the reverse option passed to db.iterator() was true. The same applies to implicit iterator.next() calls in a for await...of loop.

If range options like gt were passed to db.iterator() and target does not fall within that range, the iterator will reach its natural end.

iterator.end([callback])

End iteration and free up underlying resources. The callback function will be called with no arguments on success or with an Error if ending failed for any reason.

If no callback is provided, a promise is returned.

iterator.db

A reference to the db that created this iterator.

leveldown.destroy(location, callback)

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)

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

Database State

Currently leveldown does not track the state of the underlying LevelDB instance. This means that calling open() on an already open database may result in an error. Likewise, calling any other operation on a non-open database may result in an error.

levelup currently tracks and manages state and will prevent out-of-state operations from being send to leveldown. If you use leveldown directly then you must track and manage state for yourself.

Snapshots

leveldown exposes a feature of LevelDB called snapshots. This means that when you do e.g. createReadStream and createWriteStream at the same time, any data modified by the write stream will not affect data emitted from the read stream. In other words, a LevelDB Snapshot captures the latest state at the time the snapshot was created, enabling the snapshot to iterate or read the data without seeing any subsequent writes. Any read not performed on a snapshot will implicitly use the latest state.

Getting Support

You're welcome to open an issue on the GitHub repository if you have a question.

Past and no longer active support channels include the ##leveldb IRC channel on Freenode and the Node.js LevelDB Google Group.

Contributing

Level/leveldown is an OPEN Open Source Project. This means that:

Individuals making significant and valuable contributions are given commit-access to the project to contribute as they see fit. This project is more like an open wiki than a standard guarded open source project.

See the Contribution Guide for more details.

Git Submodules

This project uses Git Submodules. This means that you should clone it recursively if you're planning on working on it:

$ git clone --recurse-submodules https://github.com/Level/leveldown.git

Alternatively, you can initialize submodules inside the cloned folder:

$ git submodule update --init --recursive

Publishing

  1. Increment the version: npm version ..
  2. Push to GitHub: git push --follow-tags
  3. Wait for CI to complete
  4. Download prebuilds into ./prebuilds: npm run download-prebuilds
  5. Optionally verify loading a prebuild: npm run test-prebuild
  6. Optionally verify which files npm will include: canadian-pub
  7. Finally: npm publish

Donate

Support us with a monthly donation on Open Collective and help us continue our work.

License

MIT

leveldown builds on the excellent work of the LevelDB and Snappy teams from Google and additional contributors. LevelDB and Snappy are both issued under the New BSD License. A large portion of leveldown Windows support comes from the Windows LevelDB port (archived) by Krzysztof Kowalczyk (@kjk). If you're using leveldown on Windows, you should give him your thanks!