An Erlang Binding to FoundationDB

An Erlang library that wraps the FoundationDB C API with a NIF.

We also provide a conforming implementation of the Tuple and Directory layers.

This project originated as apache/couchdb-erlfdb. This fork was created in early 2024 to continue development.

Dependencies

Refer to FoundationDB's Getting Started on Linux or Getting Started on macOS.

Install the foundationdb-clients package to run erlfdb as a client to an existing FoundationDB database.

Install the foundationdb-server package for running a test fdbserver on your local device. This package is required to run the unit tests.

Usage

Erlang's rebar3

Add erlfdb as a dependency in your Erlang project's rebar.config:

% rebar.config
{deps, [
    {erlfdb, "1.0.0"}
]}.

Elixir's Mix

Add erlfdb as a dependency in your Elixir project's mix.exs:

# mix.exs
defp deps do
  [
    {:erlfdb, "~> 1.0"}
  ]
end

Example

A simple example showing how to open a database and read and write keys.

See the erlfdb Documentation for more.

Erlang

1> Db = erlfdb:open(<<"/usr/local/etc/foundationdb/fdb.cluster">>).
{erlfdb_database,#Ref<0.2859661758.3941466120.85406>}
2> ok = erlfdb:set(Db, <<"foo">>, <<"bar">>).
ok
3> erlfdb:get(Db, <<"foo">>).
<<"bar">>
4> erlfdb:get(Db, <<"bar">>).
not_found

Elixir

iex> db = :erlfdb.open("/usr/local/etc/foundationdb/fdb.cluster")
{:erlfdb_database, #Reference<0.2859661758.3941466120.85406>}
iex> :ok = :erlfdb.set(db, "foo", "bar")
:ok
iex> :erlfdb.get(db, "foo")
"bar"
iex> :erlfdb.get(db, "bar")
:not_found

Binding Tester

FoundationDB has a custom binding tester that can be used to test whether changes have broken compatibility. The GitHub Action runs the Binding Tester against the most recent supported version of FoundationDB.

Developing erlfdb

Building

$ rebar3 compile

Testing

# rebar3 eunit

Bypassing dependency checks

When you execute a rebar command, erlfdb attempts to detect the FDB API version via fdbcli. If it cannot be determined, the rebar command is aborted.

To disable the abort, use ERLFDB_ASSERT_API_VERSION=0. For example, you can safely use this for the fmt command, which does not do a compile action.

ERLFDB_ASSERT_API_VERSION=0 rebar3 fmt