ExBitcask

Elixir wrapper of Basho's Bitcask. Bitcask is a Log-Structured Hash Table for Fast Key/Value Data.

Notes on Bitcask

Instead of the usual method of requiring the wrapped library as a dependency I have chosen to include the Bitcask source code in the library. This will vastly simplify getting and compiling the library. On the minus side it will mean that updating to a new release of Bitcask will take a few days. But I'll try to be quick about it.

ExBitcask currently users version 2.0.0 of bitcask.

Setup

First, add ExBitcask to your mix.exs dependencies:

def deps do
  [{:ex_bitcask, "~> VERSION"}]
end

and run $ mix deps.get. Now, list the :ex_bitcask application as your application dependency:

def application do
  [applications: [:ex_bitcask]]
end

Usage

For full API docs please view the projects Hexdocs.

db = ExBitcask.open("my.db", [:read_write])
ExBitcask.put(db, "Foo", "bar")
ExBitcask.put(db, "Hello", "world")
ExBitcask.get(db, "Hello")
# {:ok, "world"}

Streams

Lazy Streams can be generated for both the keys and the {key, val} of the database.

ExBitcask.stream_keys(db) |> Stream.map(&(String.upcase(&1))) |> Enum.to_list
# ["FOO", "HELLO"]
ExBitcask.stream_keyvals(db) |> Enum.to_list
# [{"Foo", "bar"}, {"Hello", "world"}]

Serialization

If a value is in binary or String format it will be put in as is. Other terms will be serialized into binary using :erlang.term_to_binary/1 with a prefix so ExBitcask knows when to de-serialize a value.

This means a value can be any complex Elixir object. Like the database connection itself.

ExBitcask.put(db, "myown_db", db)
db_from_db = ExBitcask.get!(db, "myown_db")
ExBitcask.get(db_from_db, "Hello")
# {:ok, "world"}

What is Bitcask

(From Wikipedia)

Bitcask is an Erlang application that provides an API for storing and retrieving key/value data into a log-structured hash table that provides very fast access. The design owes a lot to the principles found in log-structured file systems and draws inspiration from a number of designs that involve log file merging.

Strengths

Low latency per item read or written

This is due to the write-once, append-only nature of the Bitcask database files. High throughput, especially when writing an incoming stream of random items Because the data being written doesn't need to be ordered on disk and because the log structured design allows for minimal disk head movement during writes these operations generally saturate the I/O and disk bandwidth.

Ability to handle datasets larger than RAM w/o degradation

Because access to data in Bitcask is direct lookup from an in-memory hash table finding data on disk is very efficient, even when data sets are very large.

Single Seek to Retrieve Any Value

Bitcask's in-memory hash-table of keys point directly to locations on disk where the data lives. Bitcask never uses more than one disk seek to read a value and sometimes, due to file-system caching done by the operating system, even that isn't necessary.

Predictable Lookup and Insert Performance

As you might expect from the description above, read operations have a fixed, predictable behavior. What you might not expect is that this is also true for writes. Write operations are at most a seek to the end of the current file open writing and an append to that file.

Fast, bounded Crash Recovery

Due to the append-only write once nature of Bitcask files, recovery is easy and fast. The only items that might be lost are partially written records at the tail of the file last opened for writes. Recovery need only review the last record or two written and verify CRC data to ensure that the data is consistent.

Easy Backup

In most systems backup can be very complicated but here again Bitcask simplifies this process due to its append-only write once disk format. Any utility that archives or copies files in disk-block order will properly backup or copy a Bitcask database.

Weakness

Keys Must Fit In Memory

Bitcask keeps all keys in memory at all times, this means that your system must have enough memory to contain your entire keyspace with room for other operational components and operating system resident filesystem buffer space.

Licence

Licenced under the Apache License 2.0