ExRocket

About

ExRocket is an Elixir NIF backed by RocksDB through Rust. It provides a safe, fast API while keeping keys and values as binaries, so applications can choose their own storage format.

ExRocket is a continuation of Rocker, a RocksDB NIF for Erlang.

Looking for the complete API reference? See the ExRocket Cheatsheet for examples covering key/value operations, column families, batches, iterators, snapshots, backups, and merge operators.

Installation

Add ex_rocket to the dependencies in mix.exs:

def deps do
  [
    {:ex_rocket, "~> 0.4"}
  ]
end

Quick start

Open a database, write binary keys and values, and read them back:

db_path = Path.join(System.tmp_dir!(), "my_ex_rocket_db")

{:ok, db} = ExRocket.open(db_path, %{create_if_missing: true})

:ok = ExRocket.put(db, "greeting", "hello")
{:ok, "hello"} = ExRocket.get(db, "greeting")
:undefined = ExRocket.get(db, "missing")

:ok = ExRocket.delete(db, "greeting")

Write several changes atomically:

{:ok, 3} =
  ExRocket.write_batch(db, [
    {:put, "user:1", "alice"},
    {:put, "user:2", "bob"},
    {:delete, "obsolete"}
  ])

{:ok, [{:ok, "alice"}, {:ok, "bob"}, :undefined]} =
  ExRocket.multi_get(db, ["user:1", "user:2", "missing"])

Use a column family to keep related data separate:

:ok = ExRocket.create_cf(db, "sessions")
:ok = ExRocket.put_cf(db, "sessions", "token", "active")
{:ok, "active"} = ExRocket.get_cf(db, "sessions", "token")

See the full cheatsheet for iterators, merge operators, snapshots, checkpoints, backups, options, and error-handling patterns.

Technology

Elixir module	Native crate	Rust package	Bundled RocksDB
`ExRocket`	`native/rocker`	`rust-rocksdb 0.51`	11.1.2

Supported OS

Precompiled NIFs are published for:

Apple Silicon and Intel macOS
ARM64 and x86-64 Linux with glibc
ARM64 and x86-64 Linux with musl, including Alpine Linux
x86-64 Windows

Other targets can build from source with FORCE_BUILD=1 and the build requirements below.

Features

Key/value operations
Column families
Atomic batch writes
Flexible database options
Range and prefix iterators
Range deletion
Multi-get
Snapshots
Checkpoints
Backup API
Counter, Erlang term, and bitset merge operators

Performance

ExRocket's hot-key microbenchmark on an Apple M3 Ultra measured approximately 2.46 million reads/second and 470,000 writes/second. Real workloads will vary with key/value size, cache hit rate, durability settings, compaction, and storage hardware.

Source build requirements

Erlang 24 or newer
Rust 1.91 or newer; the version is pinned in rust-toolchain.toml
Clang 15 or newer

Validation

Run scripts/roadmap001_check.sh to format, source-build, and test ExRocket.

Release

Bump the version in mix.exs and native/rocker/Cargo.toml.
Tag the release, for example: git tag v0.4.1.
Push the tag: git push origin v0.4.1.
Wait for all precompiled NIFs to be uploaded.
Run mix rustler_precompiled.download ExRocket --all.
Verify the checksum file and NIF artifact set.
Build and publish with mix hex.publish.

Status

Passed all functional and performance tests.

License

ExRocket is licensed under the Apache License 2.0.