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"}
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 |
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
Specs:
- close(ExBitcask.Database.t) :: :ok
Closes the access to a given database.
Specs:
- close_write_file(ExBitcask.Database.t) :: :ok
Closes the write lock a connection has to the database.
Specs:
- delete(ExBitcask.Database.t, String.t) :: :ok
Delete the key. Bet you weren’t expecting that.
Specs:
- fold(ExBitcask.Database.t, function, List.t) :: :ok
Fold over the keys and values.
Consider using ExBitcask.stream_keys/3
instead.
Specs:
- fold_keys(ExBitcask.Database.t, function, List.t) :: :ok
Fold over the keys in the database.
Consider using ExBitcask.stream_keys/3
instead.
Specs:
- get(ExBitcask.Database.t, String.t) :: {:ok, binary} | :not_found
Retreives a value by key.
If the value was a serialized term it will be de-serialized before returning.
Specs:
- get!(ExBitcask.Database.t, String.t) :: binary
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.
Specs:
- is_frozen?(ExBitcask.Database.t) :: boolean
Is the DB frozen?
Specs:
- list_keys(ExBitcask.Database.t) :: [binary]
List all keys in the database.
Consider using ExBitcask.stream_keys/3
instead.
Specs:
- merge(String.t | ExBitcask.Database.t, List.t) :: :ok
Merge the data files of the database.
Specs:
- needs_merge?(ExBitcask.Database.t, List.t) :: :ok
Does the db need to be merged?
Specs:
Opens up a Bitcask database in the given folder.
To open up the database for writing into use options [:read_write]
Specs:
- put(ExBitcask.Database.t, String.t, binary) :: :ok
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.
Callback implementation of :application.start/2
.
Specs:
- status(ExBitcask.Database.t) :: any
Gets the status of a database.
Specs:
- stream_keys(ExBitcask.Database.t) :: Stream.t
Creates a Stream object with all the keys in the database.
Same as calling ExBitcask.stream_keys(db, -1, -1)
.
Specs:
- stream_keys(ExBitcask.Database.t, Integer.t, Integer.t) :: Stream.t
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.
Specs:
- stream_keyvals(ExBitcask.Database.t) :: Stream.t
Creates a Stream object with all the {key, val} objects in the database.
Same as calling ExBitcask.stream_keyvals(db, -1, -1)
.
Specs:
- stream_keyvals(ExBitcask.Database.t, Integer.t, Integer.t) :: Stream.t
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.
Specs:
- sync(ExBitcask.Database.t) :: :ok
Forces a sync of the database.