Skip to content
<awesome-gh-repos>
vic

elixir-nebulex/nebulex

In-memory and distributed caching toolkit for Elixir.
Source code at GitHub https://hexdocs.pm/nebulex
elixir-nebulex/nebulex.json
{
  "createdAt": "2017-02-14T10:48:00Z",
  "defaultBranch": "main",
  "description": "In-memory and distributed caching toolkit for Elixir.",
  "fullName": "elixir-nebulex/nebulex",
  "homepage": "https://hexdocs.pm/nebulex",
  "language": "Elixir",
  "name": "nebulex",
  "pushedAt": "2025-11-11T17:29:46Z",
  "stargazersCount": 1364,
  "topics": [
    "cache",
    "caching",
    "distributed",
    "ecto",
    "elixir",
    "framework"
  ],
  "updatedAt": "2025-11-25T02:31:27Z",
  "url": "https://github.com/elixir-nebulex/nebulex"
}
Nebulex logo

In-memory and distributed caching toolkit for Elixir

CI Codecov Hex.pm Documentation

🚀 About

Section titled “🚀 About”

Nebulex provides support for transparently adding caching to existing Elixir applications. Like [Ecto][ecto], the caching abstraction allows consistent use of various caching solutions with minimal impact on your code.

Nebulex’s cache abstraction shields developers from directly interacting with underlying caching implementations, such as [Redis][redis], [Memcached][memcached], or other Elixir cache implementations like [Cachex][cachex]. It also provides out-of-the-box features including [declarative decorator-based caching][nbx_caching], [cache usage patterns][cache_patterns], and [distributed cache topologies][cache_topologies], among others.

[ecto] !: https://github.com/elixir-ecto/ecto [cachex] !: https://github.com/whitfin/cachex [redis] !: https://redis.io/ [memcached] !: https://memcached.org/ [nbx_caching] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/Nebulex.Caching.Decorators.html [info_api] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/info-api.html [cache_patterns] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/cache-usage-patterns.html [cache_topologies] !: https://docs.oracle.com/en/middleware/fusion-middleware/coherence/14.1.2/develop-applications/introduction-coherence-caches.html

[!NOTE]

This README refers to the main branch of Nebulex, not the latest released version on Hex. Please refer to the [getting started guide][getting_started] and the [official documentation][docs] for the latest stable release.

[getting_started] !: http://hexdocs.pm/nebulex/getting-started.html [docs] !: http://hexdocs.pm/nebulex/Nebulex.html

📖 Usage

Section titled “📖 Usage”

To use Nebulex, add both :nebulex and your chosen cache adapter as dependencies in your mix.exs file.

For more information about available adapters, check out the [Nebulex adapters][nbx_adapters] guide.

[nbx_adapters] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/nbx-adapters.html

For example, to use the Generational Local Cache (Nebulex.Adapters.Local adapter), add the following to your mix.exs:

def deps do
  [
    {:nebulex, "~> 3.0.0-rc.2"},
    {:nebulex_local, "~> 3.0.0-rc.2"}, # Generational local cache adapter
    {:decorator, "~> 1.4"},            # Required for caching decorators
    {:telemetry, "~> 1.2"}             # Required for telemetry events
  ]
end

To provide more flexibility and load only the needed dependencies, Nebulex makes all dependencies optional, including the adapters. For example:

  • For enabling [declarative decorator-based caching][nbx_caching]: Add :decorator to the dependency list (recommended).

  • For enabling Telemetry events: Add :telemetry to the dependency list (recommended). See the [Info API guide][info_api] for monitoring cache stats and metrics.

Then run mix deps.get in your shell to fetch the dependencies. If you want to use another cache adapter, just choose the appropriate dependency from the table above.

Finally, in your cache definition, you’ll need to specify the adapter: corresponding to the chosen dependency. For the local cache, it would be:

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

Don’t forget to add MyApp.Cache to your application’s supervision tree:

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


  # ... rest of your supervision tree

You’re now ready to use the cache:

iex> MyApp.Cache.put("foo", "bar")
:ok
iex> MyApp.Cache.fetch("foo")
{:ok, "bar"}

For more detailed information, see the [getting started guide][getting_started-rc1] and [online documentation][docs-rc1].

[getting_started-rc1] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/getting-started.html [docs-rc1] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/Nebulex.html

⚡ Quick Start Example with Caching Decorators

Section titled “⚡ Quick Start Example with Caching Decorators”

This example demonstrates how to use Nebulex with Ecto and declarative caching:

# In config/config.exs
config :my_app, MyApp.Cache,
  # Create new generation every 12 hours
  gc_interval: :timer.hours(12),
  # Max 1M entries
  max_size: 1_000_000,
  # Max 2GB of memory
  allocated_memory: 2_000_000_000,
  # Run size and memory checks every 10 seconds
  gc_memory_check_interval: :timer.seconds(10)


# Cache definition
defmodule MyApp.Cache do
  use Nebulex.Cache,
    otp_app: :my_app,
    adapter: Nebulex.Adapters.Local
end


# Ecto schema
defmodule MyApp.Accounts.User do
  use Ecto.Schema


  schema "users" do
    field :username, :string
    field :password, :string
    field :role, :string
  end


  def changeset(user, attrs) do
    user
    |> cast(attrs, [:username, :password, :role])
    |> validate_required([:username, :password, :role])
  end
end


# Accounts context with caching
defmodule MyApp.Accounts do
  use Nebulex.Caching, cache: MyApp.Cache


  alias MyApp.Accounts.User
  alias MyApp.Repo


  # Cache entries expire after 1 hour
  @ttl :timer.hours(1)


  @decorate cacheable(key: {User, id}, opts: [ttl: @ttl])
  def get_user!(id) do
    Repo.get!(User, id)
  end


  @decorate cacheable(key: {User, username}, references: & &1.id)
  def get_user_by_username(username) do
    Repo.get_by(User, [username: username])
  end


  @decorate cache_put(
              key: {User, user.id},
              match: &__MODULE__.match_update/1,
              opts: [ttl: @ttl]
            )
  def update_user(%User{} = user, attrs) do
    user
    |> User.changeset(attrs)
    |> Repo.update()
  end


  @decorate cache_evict(key: {User, user.id})
  def delete_user(%User{} = user) do
    Repo.delete(user)
  end


  def create_user(attrs \\ %{}) do
    %User{}
    |> User.changeset(attrs)
    |> Repo.insert()
  end


  def match_update({:ok, value}), do: {true, value}
  def match_update({:error, _}), do: false
end

🔗 Important Links

Section titled “🔗 Important Links”
  • [Getting Started][getting_started] - Learn how to set up and use Nebulex.
  • [Documentation][docs] - Complete API reference.
  • [Upgrading to v3.0][upgrading_to_v3] - Migration guide for v3.0.
  • [Declarative caching][declarative_caching] - Declarative Caching: Patterns and Best Practices.
  • [Nebulex Streams][nebulex_streams] - Real-time event streaming for Nebulex caches via Phoenix.PubSub.
  • [Examples][examples] - Example applications.

[examples] !: https://github.com/elixir-nebulex/nebulex_examples [upgrading_to_v3] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/v3-0.html [nebulex_streams] !: https://github.com/elixir-nebulex/nebulex_streams [declarative_caching] !: http://hexdocs.pm/nebulex/3.0.0-rc.2/declarative-caching.html

🧪 Testing

Section titled “🧪 Testing”

To run only the tests:

Terminal window
$ mix test

Additionally, to run all Nebulex checks:

Terminal window
$ mix test.ci

The mix test.ci command will run the tests, coverage, credo, dialyzer, and more. This is the recommended way to test Nebulex.

📊 Benchmarks

Section titled “📊 Benchmarks”

Nebulex provides a set of basic benchmark tests using the library benchee, located in the [benchmarks]!(./benchmarks) directory.

To run a benchmark test:

Terminal window
$ mix bench

The benchmark uses the Nebulex.Adapters.Nil adapter; it is more focused on measuring the Nebulex abstraction layer performance rather than a specific adapter.

🤝 Contributing

Section titled “🤝 Contributing”

Contributions to Nebulex are very welcome and appreciated!

Use the issue tracker for bug reports or feature requests. Open a pull request when you’re ready to contribute.

When submitting a pull request:

  • Do not update the [CHANGELOG.md]!(CHANGELOG.md)
  • Ensure you test your changes thoroughly
  • Include unit tests alongside new or changed code

Before submitting a PR, it is highly recommended to run mix test.ci and ensure all checks run successfully.

📄 Copyright and License

Section titled “📄 Copyright and License”

Copyright (c) 2017, Carlos Bolaños.

Nebulex source code is licensed under the [MIT License]!(LICENSE.md).