shelf

v1.1.2 on Hex

The pattern

shelf combines ETS tables with DETS files through a type-safe Gleam API. Reads use ETS. By default, writes stay in memory until you call save() or close the table. When you reopen it, your decoders validate the saved entries before loading them into ETS.

With /app/data created, you can open, update, and save a table:

import gleam/dynamic/decode
import shelf/set

let assert Ok(table) =
  set.open(
    name: "users",
    path: "users.dets",
    base_directory: "/app/data",
    key: decode.string,
    value: decode.int,
  )

let assert Ok(Nil) = set.insert(into: table, key: "alice", value: 42)
let assert Ok(42) = set.lookup(from: table, key: "alice")
let assert Ok(Nil) = set.save(table)
let assert Ok(Nil) = set.close(table)

The quick start takes you through saving a table and reading it in a separate application run.

Choose when to persist

Use WriteBack, the default, to save batches of changes. Unsaved changes are lost if the owner exits. Use WriteThrough to send each change to DETS before updating ETS, without taking a full snapshot.

DETS can buffer writes in memory. sync() flushes that buffer to the file; shelf does not provide fsync(2)-level guarantees against OS crashes or power loss. Read write modes before choosing a save schedule.

Does shelf fit?

Use shelf when you need local persistence with in-memory reads, your data fits in memory, and each DETS file stays below 2 GB. Choose a set for unique keys, a bag for distinct values per key, or a duplicate bag to keep repeated pairs. One owner process handles writes; other processes can read the table.

For integer counters, update_counter performs an atomic increment. It is owner-only, like other writes; producers in other processes must send their requests to the owner.

If you only need ETS, bravo wraps it without disk persistence. If you only need DETS, slate wraps it without an ETS read cache. For transactions or multi-node persistence, consider Mnesia, which ships with OTP.

Check the limitations before using shelf as your application's persistent store.