Nebulex.Distributed (Nebulex.Distributed v3.0.0)

Distributed caching adapters for Nebulex.

This package provides adapters for building distributed cache topologies on top of Nebulex. Each adapter wraps a local cache adapter (e.g., Nebulex.Adapters.Local) and adds a distributed layer on top of it.

Adapters

Nebulex.Adapters.Partitioned - Partitioned cache topology where data is sharded across cluster nodes using consistent hashing. Each node owns a subset of the keyspace, providing linear scalability and single-hop point-to-point operations.
Nebulex.Adapters.Multilevel - Multi-level (near) cache topology with a hierarchy of cache layers (e.g., L1 local + L2 distributed). Reads check levels in order for fast local hits with fallback to slower shared layers. Writes use a write-through policy.
Nebulex.Adapters.Coherent - Local cache with distributed invalidation via Nebulex.Streams. Each node maintains its own independent local cache for maximum read performance; entries are only present on nodes that have fetched them. Writes broadcast invalidation events across the cluster so other nodes delete stale entries and fetch fresh data on the next read.
🚧 Nebulex.Adapters.Replicated - Replicated cache topology where every node holds an identical copy of the entire cache. Writes are broadcast to all nodes so data is immediately available locally on every member of the cluster. Planned for a future release.

Choosing an Adapter

Aspect	Partitioned	Multilevel	Coherent
Data location	Sharded across nodes	L1 local + L2 shared	Independent per node
Read performance	Network hop required	L1 fast, L2 slower	Fastest (pure local)
Write behavior	Remote write to owner	Write through levels	Local + invalidation
Consistency	Strong (single owner)	Varies by config	Eventual
Network overhead	Medium	Medium to high	Low (invalidations)
Best for	Large datasets	Tiered access patterns	Read-heavy workloads

Installation

Add :nebulex_distributed to your dependencies in mix.exs:

def deps do
  [
    {:nebulex, "~> 3.0"},
    {:nebulex_distributed, "~> 3.0"},
    {:telemetry, "~> 0.4 or ~> 1.0"}, # For observability and monitoring
    {:decorator, "~> 1.4"},           # For declarative caching
  ]
end

The :telemetry (observability and monitoring cache operations) and :decorator (declarative caching) dependencies are optional but highly recommended.

See each adapter's documentation for configuration and usage details.