barrel_keyspace (barrel_docdb v1.0.0)

View Source

Keyspace indirection for timeline branches.

Every storage key embeds a database name. A branch created by checkpointing a parent database keeps the PARENT's name inside the copied keys, so the branch carries a keyspace (the name used for key building) distinct from its logical (registered) name. Normal databases have keyspace =:= name and no entry is installed.

resolve/1 is idempotent under the v1 invariant: a keyspace value is always the name of a database whose own keyspace is itself (branching a branch is rejected, lineage is linear). This lets internals pass an already-resolved name into helpers that resolve again.

Branch identity (keyspace, parent, fork_hlc) persists in a sidecar file TIMELINE inside the database directory, NOT in db_meta: the compaction filter starts before RocksDB opens, so identity must be readable without the store. The file is written atomically at fork (temp + rename) and never rewritten.

Summary

Functions

Register the key name used for a logical database name. Only called when they differ (branches).

Read the branch identity sidecar of a database directory.

The name to build storage keys with for a logical database name. Identity for normal databases.

Write the branch identity sidecar atomically (temp + rename).

Types

meta/0

-type meta() :: #{keyspace := binary(), parent := binary(), fork_hlc := binary()}.

Functions

install(Logical, KeyName)

-spec install(binary(), binary()) -> ok.

Register the key name used for a logical database name. Only called when they differ (branches).

read_meta(DbPath)

-spec read_meta(string()) -> {ok, meta()} | not_found | {error, corrupt_timeline_meta}.

Read the branch identity sidecar of a database directory.

resolve(Name)

-spec resolve(binary()) -> binary().

The name to build storage keys with for a logical database name. Identity for normal databases.

uninstall(Logical)

-spec uninstall(binary()) -> ok.

write_meta(DbPath, Meta)

-spec write_meta(string(), meta()) -> ok | {error, term()}.

Write the branch identity sidecar atomically (temp + rename).