ExBitcask v0.1.0 → Overview → ExBitcask

ExBitcask

Elixir wrapper of Basho’s Bitcask Key/Value store.

ExBitcask currently uses version 2.0.0 of bitcask.

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.

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

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"}
Source

Summary↑

close(db)

Closes the access to a given database
close_write_file(db)

Closes the write lock a connection has to the database
delete(db, key)

Delete the key. Bet you weren’t expecting that
fold(db, func, options \\ [])

Fold over the keys and values
fold_keys(db, func, options \\ [])

Fold over the keys in the database
get!(db, key)

Retreives a value by key. Throws if key is not found
get(db, key)

Retreives a value by key
is_frozen?(db)

Is the DB frozen?
list_keys(db)

List all keys in the database
merge(folder_or_db, options \\ [])

Merge the data files of the database
needs_merge?(db, options \\ [])

Does the db need to be merged?
open(folder, options \\ [])

Opens up a Bitcask database in the given folder
put(db, key, val)

Puts a given value into the key
start(type, args)

Callback implementation of :application.start/2
status(db)

Gets the status of a database
stream_keys(db)

Creates a Stream object with all the keys in the database
stream_keys(db, max_age, max_puts)

Creates a Stream object with all the keys in the database
stream_keyvals(db)

Creates a Stream object with all the {key, val} objects in the database
stream_keyvals(db, max_age, max_puts)

Creates a Stream object with all the {key, val} objects in the database
sync(db)

Forces a sync of the database

Functions

close(db)
(function) # ↑

Specs:

Closes the access to a given database.

Source
close_write_file(db)
(function) # ↑

Specs:

Closes the write lock a connection has to the database.

Source
delete(db, key)
(function) # ↑

Specs:

Delete the key. Bet you weren’t expecting that.

Source
fold(db, func, options \\ [])
(function) # ↑

Specs:

Fold over the keys and values.

Consider using ExBitcask.stream_keys/3 instead.

Source
fold_keys(db, func, options \\ [])
(function) # ↑

Specs:

Fold over the keys in the database.

Consider using ExBitcask.stream_keys/3 instead.

Source
get(db, key)
(function) # ↑

Specs:

Retreives a value by key.

If the value was a serialized term it will be de-serialized before returning.

Source
get!(db, key)
(function) # ↑

Specs:

Retreives a value by key. Throws if key is not found.

If the value was a serialized term it will be de-serialized before returning.

Source
is_frozen?(db)
(function) # ↑

Specs:

Is the DB frozen?

Source
list_keys(db)
(function) # ↑

Specs:

List all keys in the database.

Consider using ExBitcask.stream_keys/3 instead.

Source
merge(folder_or_db, options \\ [])
(function) # ↑

Specs:

Merge the data files of the database.

Source
needs_merge?(db, options \\ [])
(function) # ↑

Specs:

Does the db need to be merged?

Source
open(folder, options \\ [])
(function) # ↑

Specs:

Opens up a Bitcask database in the given folder.

To open up the database for writing into use options [:read_write]

Source
put(db, key, val)
(function) # ↑

Specs:

Puts a given value into the key.

If a value is in binary or String format it will be put in as is. Other terms will be serialized into binary.

Source
start(type, args)
(function) # ↑

Callback implementation of :application.start/2.

Source
status(db)
(function) # ↑

Specs:

Gets the status of a database.

Source
stream_keys(db)
(function) # ↑

Specs:

Creates a Stream object with all the keys in the database.

Same as calling ExBitcask.stream_keys(db, -1, -1).

Source
stream_keys(db, max_age, max_puts)
(function) # ↑

Specs:

Creates a Stream object with all the keys in the database.

Check the number of updates since pending was created is less than the maximum and that the current view is not too old. Call with ts set to zero to force a wait on any pending keydir. Set maxage or maxputs negative to ignore them. Set both negative to force using the keydir - useful when a process has waited once and needs to run next time.

Source
stream_keyvals(db)
(function) # ↑

Specs:

Creates a Stream object with all the {key, val} objects in the database.

Same as calling ExBitcask.stream_keyvals(db, -1, -1).

Source
stream_keyvals(db, max_age, max_puts)
(function) # ↑

Specs:

Creates a Stream object with all the {key, val} objects in the database.

Check the number of updates since pending was created is less than the maximum and that the current view is not too old. Call with ts set to zero to force a wait on any pending keydir. Set maxage or maxputs negative to ignore them. Set both negative to force using the keydir - useful when a process has waited once and needs to run next time.

Source
sync(db)
(function) # ↑

Specs:

Forces a sync of the database.

Source