Skip to content

Use a LevelDB database from multiple processes with seamless failover.

License

Notifications You must be signed in to change notification settings

Level/rave-level

Repository files navigation

rave-level

Use a LevelDB database from multiple processes with seamless failover. Normally with classic-level opening the same location more than once would result in a LEVEL_LOCKED error. With rave-level the first process that succeeds in taking the LevelDB lock becomes the "leader" and creates a many-level host to which other processes connect over a unix socket (Linux and Mac) or named pipe (Windows), transparently electing a new leader when it goes down. Pending database operations are then retried and iterators resumed at the last visited key as if nothing happened.

📌 Which module should I use? What happened to level-party? Head over to the FAQ.

level badge npm Node version Test Coverage Standard Common Changelog Donate

Usage

const { RaveLevel } = require('rave-level')
const db = new RaveLevel('./db')

API

db = new RaveLevel(location[, options])

The location argument is the same as in classic-level, making rave-level a drop-in replacement for when you need to read and write to the given location from multiple processes simultaneously. However, the options are different and limited because not every RaveLevel instance has direct access to the underlying LevelDB database. The options object may contain:

  • keyEncoding (string or object, default 'utf8'): encoding to use for keys
  • valueEncoding (string or object, default 'utf8'): encoding to use for values
  • retry (boolean, default true): if true, operations are retried upon connecting to a new leader. This disables snapshot guarantees because retries may implicitly use new snapshots. If false, operations are aborted upon disconnect, which means to yield an error on e.g. db.get().

The RaveLevel class extends AbstractLevel and thus follows the public API of abstract-level. As such, the rest of the API is documented in abstract-level. The database opens itself but (unlike other abstract-level implementations) cannot be re-opened once db.close() has been called. Calling db.open() would then yield a LEVEL_NOT_SUPPORTED error.

Events

A RaveLevel instance will only emit events that are the result of its own operations (rather than other processes or instances). There's one additional event, emitted when db has been elected as the leader:

db.on('leader', function () {
  console.log('I am the leader now')
})

Install

With npm do:

npm install rave-level

Contributing

Level/rave-level 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.

Donate

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

License

MIT