Nebulex.Adapters.Cachex (nebulex_adapters_cachex v3.0.0-rc.2)

Nebulex adapter for Cachex.

This adapter provides a Nebulex interface on top of Cachex, a powerful in-memory caching library for Elixir. It combines Nebulex's unified caching API with Cachex's rich feature set including transactions, hooks, expiration, and statistics. Use this adapter when you need a feature-rich local cache or as a building block for distributed caching topologies.

Options

This adapter supports all Cachex configuration options. The options are passed directly to Cachex.start_link/2, allowing you to leverage Cachex's full feature set including expiration, hooks, limits, and warmers.

Example

You can define a cache using Cachex as follows:

defmodule MyApp.Cache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Cachex
end

Where the configuration for the cache must be in your application environment, usually defined in your config/config.exs:

config :my_app, MyApp.Cache,
  stats: true,
  ...

If your application was generated with a supervisor (by passing --sup to mix new) you will have a lib/my_app/application.ex file containing the application start callback that defines and starts your supervisor. You just need to edit the start/2 function to start the cache as a supervisor on your application's supervisor:

def start(_type, _args) do
  children = [
    {MyApp.Cache, []},
  ]

  ...
end

Since Cachex uses macros for some configuration options, you could also pass the options in runtime when the cache is started, either by calling MyApp.Cache.start_link/1 directly, or in your app supervision tree:

def start(_type, _args) do
  children = [
    {MyApp.Cache, cachex_opts()},
  ]

  ...
end

defp cachex_opts do
  import Cachex.Spec

  [
    expiration: expiration(
      # how often cleanup should occur
      interval: :timer.seconds(30),

      # default record expiration
      default: :timer.seconds(60),

      # whether to enable lazy checking
      lazy: true
    ),

    # hooks
    hooks: [
      hook(module: MyHook, name: :my_hook, args: { })
    ],

    ...
  ]
end

See Cachex.start_link/2 for more information.

Distributed caching topologies

Using the distributed adapters with Cachex as a primary storage is possible. For example, let's define a multi-level cache (near cache topology), where the L1 is a local cache using Cachex and the L2 is a partitioned cache.

defmodule MyApp.NearCache do
  use Nebulex.Cache,
    otp_app: :nebulex,
    adapter: Nebulex.Adapters.Multilevel

  defmodule L1 do
    use Nebulex.Cache,
      otp_app: :nebulex,
      adapter: Nebulex.Adapters.Cachex
  end

  defmodule L2 do
    use Nebulex.Cache,
      otp_app: :nebulex,
      adapter: Nebulex.Adapters.Partitioned,
      primary_storage_adapter: Nebulex.Adapters.Cachex
  end
end

And the configuration may look like:

config :my_app, MyApp.NearCache,
  model: :inclusive,
  levels: [
    {MyApp.NearCache.L1, []},
    {MyApp.NearCache.L2, primary: [transactions: true]}
  ]

NOTE: You could also use Nebulex.Adapters.Redis for L2, it would be a matter of changing the adapter for the L2 and the configuration to set up the Redis adapter.

See Nebulex examples. You will find examples for all different topologies, even using other adapters like Redis; for all examples using the Nebulex.Adapters.Local adapter, you can replace it by Nebulex.Adapters.Cachex.

Query API

The adapter supports querying cached entries using Cachex's query syntax or explicit key lists.

Pattern-based queries

Use Cachex query syntax for pattern matching:

# Get all entries
MyApp.Cache.get_all!()

# Count all entries
MyApp.Cache.count_all!()

# Delete all entries
MyApp.Cache.delete_all!()

# Delete expired entries
MyApp.Cache.delete_all!(:expired)

# Stream entries for large datasets
MyApp.Cache.stream!() |> Enum.take(100)

Explicit key queries

Query specific keys using the in: keys syntax:

# Get multiple keys
MyApp.Cache.get_all!(in: ["key1", "key2", "key3"])

# Count specific keys
MyApp.Cache.count_all!(in: ["key1", "key2"])

# Delete specific keys
MyApp.Cache.delete_all!(in: ["key1", "key2"])

Transactions

The adapter provides full transaction support through Cachex's locking mechanism, ensuring atomic operations across multiple keys.

MyApp.Cache.transaction(
  fn ->
    value = MyApp.Cache.get!("counter")
    MyApp.Cache.put!("counter", value + 1)
    MyApp.Cache.put!("last_updated", DateTime.utc_now())
  end,
  keys: ["counter", "last_updated"]
)

Transactions automatically handle locking and isolation for the specified keys.

Stats and Monitoring

Enable statistics collection by setting stats: true in your configuration (enabled by default):

config :my_app, MyApp.Cache,
  stats: true

Retrieve statistics:

# Get all stats
iex> MyApp.Cache.info!(:stats)
%{
  calls: %{get: 10, put: 5, delete: 2},
  evictions: 0,
  expirations: 1,
  hit_rate: 80.0,
  hits: 8,
  misses: 2,
  ...
}

See Cachex.Stats for detailed statistics information.