fjall (fjall v0.1.0)

View Source

Fjall embedded key-value database for Erlang.

This module provides a unified API that dispatches on tuple tags.

Examples

Non-transactional

{ok, Db} = fjall:open("./mydb"),
{ok, Ks} = fjall:keyspace(Db, <<"default">>),
ok = fjall:insert(Ks, <<"key">>, <<"value">>),
{ok, <<"value">>} = fjall:get(Ks, <<"key">>),
ok = fjall:remove(Ks, <<"key">>).

Optimistic Transaction

{ok, Db} = fjall:open("./mydb", [{optimistic, true}]),
{ok, Ks} = fjall:keyspace(Db, <<"default">>),
{ok, Tx} = fjall:write_tx(Db),
ok = fjall:insert(Tx, Ks, <<"key">>, <<"value">>),
{ok, <<"value">>} = fjall:get(Tx, Ks, <<"key">>),
ok = fjall:commit(Tx).

Summary

Types

batch()

Opaque handle to a write batch.

compression()

Compression type for journal entries.

config_option()

Configuration option for database creation.

db()

Opaque handle to a database (plain or optimistic transactional).

direction()

Iterator direction.

iter()

Opaque handle to an iterator.

ks()

Opaque handle to a keyspace (plain or optimistic transactional).

ks_option()

Keyspace configuration option.

persist_mode()

Persist mode for database persistence.

range()

Range boundary type.

result()

Result type for operations that don't return a value on success.

result(T)

Result type for operations that return a value on success.

result(T, S)

Result type for operations that return a value on success, an error, or a sentinal.

snapshot()

Opaque handle to a database snapshot.

tx()

Opaque handle to a write transaction.

Functions

approximate_len/1

Returns the approximate number of key-value pairs in the keyspace.

batch/1

Creates a write batch for atomic multi-keyspace writes.

clear/1

Clears the entire keyspace.

collect(Iter)

Returns a list of all remaining key-value pairs from the iterator.

collect(Iter, N)

Returns a list of up to N key-value pairs from the iterator.

collect_keys(Iter)

Returns a list of all remaining keys from the iterator.

collect_keys(Iter, N)

Returns a list of up to N keys from the iterator.

collect_values(Iter)

Returns a list of all remaining values from the iterator.

collect_values(Iter, N)

Returns a list of up to N values from the iterator.

commit/1

Commits a batch or transaction.

contains_key/2

Returns true if Key exists in the keyspace.

destroy(Iter)

Destroys the iterator. Call this to release resources without waiting for GC.

disk_space/1

Returns the approximate disk space used by the keyspace in bytes.

first_key_value/1

Returns the first key-value pair in the keyspace.

get/2

Returns the value for Key, or not_found if it doesn't exist.

get/3

Returns the value for Key within a transaction or snapshot.

insert/3

Inserts or updates Key with Value.

insert/4

Inserts or updates Key with Value within a batch or transaction.

is_empty/1

Returns true if the batch contains no operations.

iter/2

Creates an iterator over all key-value pairs in the keyspace.

iter/3

Creates an iterator over keys matching Prefix.

iter/4

Creates an iterator over keys in the range {Start, End}.

keyspace/2

Opens or creates a keyspace with Name.

keyspace/3

Opens or creates a keyspace with Name and Opts.

last_key_value/1

Returns the last key-value pair in the keyspace.

len/1

For batches, returns the number of operations. For plain keyspaces, returns the exact number of key-value pairs (O(n)).

next(Iter)

Returns the next key-value pair from the iterator, or done if exhausted.

open(Path)

Opens a database at Path with default options.

open(Path, Options)

Opens a database at Path with Options.

path/1

Returns the filesystem path to the keyspace directory.

persist/2

Persists the database journal with the given Mode.

remove/2

Removes Key from the keyspace.

remove/3

Removes Key from the keyspace within a batch or transaction.

rollback/1

Rolls back a transaction, discarding all changes.

size_of/2

Returns the size of the value for Key in bytes.

snapshot/1

Creates a point-in-time snapshot for consistent reads.

take/2

Removes and returns the value for Key. Only available on transactional keyspaces.

write_tx/1

Creates an optimistic write transaction.

Types

batch()

-opaque batch()

Opaque handle to a write batch.

compression()

-type compression() :: lz4 | none.

Compression type for journal entries.

See CompressionType in the Rust documentation.

config_option()

-type config_option() ::
          {cache_size, pos_integer()} |
          {journal_compression, compression()} |
          {manual_journal_persist, boolean()} |
          {max_cached_files, pos_integer()} |
          {max_journaling_size, pos_integer()} |
          {temporary, boolean()} |
          {worker_threads, pos_integer()}.

Configuration option for database creation.

Supported options:

  • {cache_size, pos_integer()} - Total block cache size in bytes. Higher values improve read performance but consume more memory. Default: 32MB
  • {journal_compression, compression()} - Compression type for large values written to the journal. See compression/0. Default: lz4
  • {manual_journal_persist, boolean()} - If true, journal persistence is manual and must be triggered explicitly. Default: false
  • {max_cached_files, pos_integer()} - Maximum number of cached file descriptors. Default: 150 (macOS), 900 (Linux), 400 (Windows)
  • {max_journaling_size, pos_integer()} - Maximum write-ahead log (journal) size in bytes. Older journals are cleaned up as needed. Default: 512MB
  • {temporary, boolean()} - If true, the database is temporary and will be deleted when closed. Default: false
  • {worker_threads, pos_integer()} - Number of worker threads for background maintenance (flushing and compaction). Default: min(CPU cores, 4)

See DatabaseBuilder in the Rust documentation for configuration methods.

db()

-opaque db()

Opaque handle to a database (plain or optimistic transactional).

direction()

-type direction() :: forward | reverse.

Iterator direction.

Specifies the order in which key-value pairs are returned:

  • forward - Iterate from first to last (ascending key order)
  • reverse - Iterate from last to first (descending key order)

iter()

-opaque iter()

Opaque handle to an iterator.

ks()

-opaque ks()

Opaque handle to a keyspace (plain or optimistic transactional).

ks_option()

-type ks_option() ::
          {manual_journal_persist, boolean()} |
          {max_memtable_size, pos_integer()} |
          {expect_point_read_hits, boolean()}.

Keyspace configuration option.

Supported options:

  • {manual_journal_persist, boolean()} - If true, journal persistence is manual and must be triggered explicitly. Default: false
  • {max_memtable_size, pos_integer()} - Maximum in-memory buffer size in bytes. Recommended range: 8-64 MiB. Default: 64 MiB
  • {expect_point_read_hits, boolean()} - If true, disables last-level bloom filters for ~90% size reduction. Use when point reads typically succeed. Default: false

See KeyspaceCreateOptions in the Rust documentation.

persist_mode()

-type persist_mode() :: buffer | sync_data | sync_all.

Persist mode for database persistence.

Determines the durability guarantee when persisting a database:

  • buffer - Flush to OS buffers only. Data survives application crash but not power loss or OS crash. See PersistMode::Buffer.
  • sync_data - Flush with fdatasync. Ensures data is written to disk, suitable for most file systems. See PersistMode::SyncData.
  • sync_all - Flush with fsync. Strongest guarantee, ensuring both data and metadata are written to disk. See PersistMode::SyncAll.

See PersistMode in the Rust documentation.

range()

-type range() :: inclusive | exclusive.

Range boundary type.

Specifies whether the end boundary of a range is included:

  • inclusive - End boundary is included in the range [Start, End]
  • exclusive - End boundary is excluded from the range [Start, End)

result()

-type result() :: ok | {error, Reason :: term()}.

Result type for operations that don't return a value on success.

result(T)

-type result(T) :: {ok, T} | {error, Reason :: term()}.

Result type for operations that return a value on success.

result(T, S)

-type result(T, S) :: {ok, T} | {error, Reason :: term()} | S.

Result type for operations that return a value on success, an error, or a sentinal.

snapshot()

-opaque snapshot()

Opaque handle to a database snapshot.

tx()

-opaque tx()

Opaque handle to a write transaction.

Functions

approximate_len/1

-spec approximate_len(ks()) -> non_neg_integer().

Returns the approximate number of key-value pairs in the keyspace.

batch/1

-spec batch(db()) -> result(batch()).

Creates a write batch for atomic multi-keyspace writes.

clear/1

-spec clear(ks()) -> result().

Clears the entire keyspace.

collect(Iter)

-spec collect(iter()) -> {ok, [{binary(), binary()}]} | {error, term()}.

Returns a list of all remaining key-value pairs from the iterator.

collect(Iter, N)

-spec collect(iter(), pos_integer()) -> {ok, [{binary(), binary()}]} | {error, term()}.

Returns a list of up to N key-value pairs from the iterator.

collect_keys(Iter)

-spec collect_keys(iter()) -> {ok, [binary()]} | {error, term()}.

Returns a list of all remaining keys from the iterator.

collect_keys(Iter, N)

-spec collect_keys(iter(), pos_integer()) -> {ok, [binary()]} | {error, term()}.

Returns a list of up to N keys from the iterator.

collect_values(Iter)

-spec collect_values(iter()) -> {ok, [binary()]} | {error, term()}.

Returns a list of all remaining values from the iterator.

collect_values(Iter, N)

-spec collect_values(iter(), pos_integer()) -> {ok, [binary()]} | {error, term()}.

Returns a list of up to N values from the iterator.

commit/1

-spec commit(batch() | tx()) -> result().

Commits a batch or transaction.

contains_key/2

-spec contains_key(ks(), Key :: binary()) -> result(boolean()).

Returns true if Key exists in the keyspace.

destroy(Iter)

-spec destroy(iter()) -> ok.

Destroys the iterator. Call this to release resources without waiting for GC.

disk_space/1

-spec disk_space(ks()) -> non_neg_integer().

Returns the approximate disk space used by the keyspace in bytes.

first_key_value/1

-spec first_key_value(ks()) -> result({binary(), binary()}).

Returns the first key-value pair in the keyspace.

get/2

-spec get(ks(), Key :: binary()) -> result(binary(), not_found).

Returns the value for Key, or not_found if it doesn't exist.

get/3

-spec get(tx(), ks(), Key :: binary()) -> result(binary());
         (snapshot(), ks(), Key :: binary()) -> result(binary(), not_found).

Returns the value for Key within a transaction or snapshot.

insert/3

-spec insert(ks(), Key :: binary(), Value :: binary()) -> result().

Inserts or updates Key with Value.

insert/4

-spec insert(batch(), ks(), Key :: binary(), Value :: binary()) -> result();
            (tx(), ks(), Key :: binary(), Value :: binary()) -> result().

Inserts or updates Key with Value within a batch or transaction.

is_empty/1

-spec is_empty(batch()) -> boolean().

Returns true if the batch contains no operations.

iter/2

-spec iter(ks(), direction()) -> result(iter()).

Creates an iterator over all key-value pairs in the keyspace.

iter/3

-spec iter(ks(), direction(), Prefix :: binary()) -> result(iter()).

Creates an iterator over keys matching Prefix.

iter/4

-spec iter(ks(), direction(), range(), {Start :: binary(), End :: binary()}) -> result(iter()).

Creates an iterator over keys in the range {Start, End}.

keyspace/2

-spec keyspace(db(), Name :: binary()) -> result(ks()).

Opens or creates a keyspace with Name.

keyspace/3

-spec keyspace(db(), Name :: binary(), Opts :: [ks_option()]) -> result(ks()).

Opens or creates a keyspace with Name and Opts.

last_key_value/1

-spec last_key_value(ks()) -> result({binary(), binary()}).

Returns the last key-value pair in the keyspace.

len/1

-spec len(batch() | ks()) -> non_neg_integer() | result(non_neg_integer()).

For batches, returns the number of operations. For plain keyspaces, returns the exact number of key-value pairs (O(n)).

next(Iter)

-spec next(iter()) -> {ok, {binary(), binary()}} | done | {error, term()}.

Returns the next key-value pair from the iterator, or done if exhausted.

open(Path)

-spec open(Path :: file:name_all()) -> result(db()).

Opens a database at Path with default options.

open(Path, Options)

-spec open(Path :: file:name_all(), Options :: [config_option() | {optimistic, boolean()}]) ->
              result(db()).

Opens a database at Path with Options.

path/1

-spec path(ks()) -> binary().

Returns the filesystem path to the keyspace directory.

persist/2

-spec persist(db(), Mode :: persist_mode()) -> result().

Persists the database journal with the given Mode.

remove/2

-spec remove(ks(), Key :: binary()) -> result().

Removes Key from the keyspace.

remove/3

-spec remove(batch(), ks(), Key :: binary()) -> result();
            (tx(), ks(), Key :: binary()) -> result().

Removes Key from the keyspace within a batch or transaction.

rollback/1

-spec rollback(tx()) -> result().

Rolls back a transaction, discarding all changes.

size_of/2

-spec size_of(ks(), Key :: binary()) -> result(non_neg_integer()).

Returns the size of the value for Key in bytes.

snapshot/1

-spec snapshot(db()) -> result(snapshot()).

Creates a point-in-time snapshot for consistent reads.

take/2

-spec take(ks(), Key :: binary()) -> result(binary()).

Removes and returns the value for Key. Only available on transactional keyspaces.

write_tx/1

-spec write_tx(db()) -> result(tx()).

Creates an optimistic write transaction.