Elixir bindings for FeOxDB, an embedded key-value store written in Rust.
A FeoxDB store can run purely in memory, or persist to disk in the
background. See the project PRD (docs/PRD.md) for the full design
rationale, including which operations run as plain, dirty, or (eventually)
chunked NIFs.
Example
{:ok, store} = FeoxDB.open()
:ok = FeoxDB.insert(store, "key", "value")
{:ok, "value"} = FeoxDB.get(store, "key")
:ok = FeoxDB.close(store)A store's native resources are released when the resource reference is
garbage collected, but for disk-backed stores this can leave background
writer / TTL sweeper threads (and open file handles) alive for longer than
expected. Call close/1 once you are done with a store to release those
resources deterministically instead of waiting on the GC.
Summary
Functions
Closes a store, releasing its native resources (background writer / TTL sweeper threads, and any open file handles for disk-backed stores) deterministically instead of waiting for the resource reference to be garbage collected.
Atomically replaces key's value with new_value if it currently equals
expected.
Deletes key.
Flushes all buffered writes to disk.
Retrieves the value for key.
Same as get/2 but raises FeoxDB.Error on failure.
Atomically adds delta to the integer stored at key and returns the new
value.
Inserts or updates key with value.
Same as insert/4 but raises FeoxDB.Error on failure.
Applies an RFC 6902 JSON patch to the JSON document stored at key.
Returns the largest key, in bytes, the store accepts.
Returns the largest value, in bytes, a single record accepts. Use
FeoxDB.Term to store larger values in chunks.
Returns whether key exists in the store.
Returns the store's memory usage, in bytes.
Opens a FeoxDB store.
Same as open/1 but raises FeoxDB.Error on failure.
Removes key's TTL, making it permanent.
Returns up to limit key-value pairs with keys in [start_key, end_key]
(both bounds inclusive), ordered by key.
Returns the number of records in the store.
Returns a snapshot of the store's internal statistics as a map.
Returns the remaining TTL in seconds for key, or nil if it has none.
Sets key's TTL to seconds from now.
Types
@type error_reason() ::
:not_found
| :out_of_memory
| :out_of_space
| :older_timestamp
| :invalid_json
| :invalid_key_size
| :invalid_value_size
| :key_too_large
| :value_too_large
| :database_full
| :invalid_range
| :ttl_not_enabled
| :invalid_argument
| :corrupted_data
| :duplicate_key
| :size_mismatch
| :stale_extent
| :io_error
| :timeout
| :not_implemented
| :unsupported
| :unknown_error
| :limit_too_large
| :closed
@type key() :: binary()
@type store() :: reference()
@type value() :: binary()
Functions
@spec close(store()) :: :ok
Closes a store, releasing its native resources (background writer / TTL sweeper threads, and any open file handles for disk-backed stores) deterministically instead of waiting for the resource reference to be garbage collected.
Idempotent: calling close/1 again on an already-closed store is a
no-op and returns :ok. Any other operation on a closed store returns
{:error, :closed} rather than raising or crashing.
@spec compare_and_swap(store(), key(), value(), value()) :: {:ok, boolean()} | {:error, error_reason()}
Atomically replaces key's value with new_value if it currently equals
expected.
Returns {:error, :key_too_large} if key is larger than
102400 bytes, or {:error, :value_too_large} if expected or
new_value is larger than 4194304 bytes, without calling into
native code.
@spec delete(store(), key()) :: :ok | {:error, error_reason()}
Deletes key.
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.
@spec flush(store()) :: :ok | {:error, error_reason()}
Flushes all buffered writes to disk.
Runs as a dirty I/O NIF (PRD section 5) because it waits for fsync.
No-op for memory-only stores.
@spec get(store(), key()) :: {:ok, value()} | {:error, error_reason()}
Retrieves the value for key.
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.
Same as get/2 but raises FeoxDB.Error on failure.
@spec increment(store(), key(), integer()) :: {:ok, integer()} | {:error, error_reason()}
Atomically adds delta to the integer stored at key and returns the new
value.
The value is stored internally as an 8-byte little-endian i64; this
function takes and returns a plain Elixir integer; the little-endian
conversion happens on the Rust side; there is no <<n::signed-little-64>>
to get wrong (PRD section 7).
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.
@spec insert(store(), key(), value(), keyword()) :: :ok | {:error, error_reason()}
Inserts or updates key with value.
Pass ttl: seconds to set an expiry (requires enable_ttl: true at
open/1 time).
Returns {:error, :key_too_large} if key is larger than
102400 bytes, or {:error, :value_too_large} if value is
larger than 4194304 bytes, without calling into native code.
Same as insert/4 but raises FeoxDB.Error on failure.
@spec json_patch(store(), key(), binary()) :: :ok | {:error, error_reason()}
Applies an RFC 6902 JSON patch to the JSON document stored at key.
Returns {:error, :key_too_large} if key is larger than
102400 bytes, or {:error, :value_too_large} if patch is
larger than 4194304 bytes, without calling into native code.
@spec max_key_size() :: pos_integer()
Returns the largest key, in bytes, the store accepts.
@spec max_value_size() :: pos_integer()
Returns the largest value, in bytes, a single record accepts. Use
FeoxDB.Term to store larger values in chunks.
@spec member?(store(), key()) :: boolean() | {:error, error_reason()}
Returns whether key exists in the store.
A key larger than 102400 bytes can never have been inserted
(see insert/4), so this returns false for it directly, without calling
into native code.
@spec memory_usage(store()) :: non_neg_integer() | {:error, error_reason()}
Returns the store's memory usage, in bytes.
@spec open(keyword()) :: {:ok, store()} | {:error, error_reason()}
Opens a FeoxDB store.
With no options, the store is memory-only. Pass path: to persist to
disk.
Options
:path- device path for persistent storage. When omitted, the store is memory-only.:file_size- initial file size in bytes for a new persistent store.:max_memory- maximum memory usage in bytes. Defaults to the upstream FeOxDB default (1GB) when a persistent path is given, or unlimited for memory-only stores unless set explicitly.:hash_bits- number of hash table bits (bucket count is2^bits).:enable_ttl- enables TTL support (ttl/2,update_ttl/3,persist/2, and TTL-bearing inserts). Defaults tofalse.
Same as open/1 but raises FeoxDB.Error on failure.
@spec persist(store(), key()) :: :ok | {:error, error_reason()}
Removes key's TTL, making it permanent.
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.
@spec range(store(), key(), key(), pos_integer()) :: {:ok, [{key(), value()}]} | {:error, error_reason()}
Returns up to limit key-value pairs with keys in [start_key, end_key]
(both bounds inclusive), ordered by key.
limit is required: an unbounded range query could run for an unknown
time on the scheduler and build an unbounded term (PRD section 7). limit
must also not exceed 10000; larger values return
{:error, :limit_too_large} without reaching the native code, since the
native side allocates a Vec sized to limit.
Runs as a dirty I/O NIF, since the cost of a scan depends on limit.
Returns {:error, :key_too_large} if start_key or end_key is larger
than 102400 bytes, without calling into native code.
@spec size(store()) :: non_neg_integer() | {:error, error_reason()}
Returns the number of records in the store.
@spec stats(store()) :: map() | {:error, error_reason()}
Returns a snapshot of the store's internal statistics as a map.
@spec ttl(store(), key()) :: {:ok, non_neg_integer() | nil} | {:error, error_reason()}
Returns the remaining TTL in seconds for key, or nil if it has none.
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.
@spec update_ttl(store(), key(), pos_integer()) :: :ok | {:error, error_reason()}
Sets key's TTL to seconds from now.
Returns {:error, :key_too_large} if key is larger than 102400
bytes, without calling into native code.