<picture>
<source media="(prefers-color-scheme: dark)" srcset="./guides/images/nbx-logo-white.png" />
<source media="(prefers-color-scheme: light)" srcset="./guides/images/nbx-logo.png" />
<img src="./guides/images/nbx-logo.png" alt="Nebulex logo" />
</picture>
> In-memory and distributed caching toolkit for Elixir.
---
[](http://codecov.io/gh/elixir-nebulex/nebulex/graph/badge.svg)
[](http://hex.pm/packages/nebulex)
[](http://hexdocs.pm/nebulex)
## About
Nebulex provides support for transparently adding caching into an existing
Elixir application. Like [Ecto][ecto], the caching abstraction allows consistent
use of various caching solutions with minimal impact on the 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.1/Nebulex.Caching.Decorators.html
[cache_patterns]: http://hexdocs.pm/nebulex/3.0.0-rc.1/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 reference 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
To use Nebulex, add both `:nebulex` and your chosen cache adapter as
dependencies in your `mix.exs` file. For example, to use the
Generational Local Cache (`Nebulex.Adapters.Local` adapter),
add the following to your `mix.exs`:
```elixir
def deps do
[
{:nebulex, "~> 3.0.0-rc.1"},
{:nebulex_local, "~> 3.0"}, # Generational local cache adapter
{:decorator, "~> 1.4"}, # Required for caching decorators
{:telemetry, "~> 1.2"} # Required for telemetry events
]
end
```
> For more information about available adapters, check out the
> [Nebulex adapters][nbx_adapters] guide.
[nbx_adapters]: http://hexdocs.pm/nebulex/3.0.0-rc.1/nbx-adapters.html
To give more flexibility and load only needed dependencies, Nebulex makes all
dependencies optional. For example:
* For enabling [declarative decorator-based caching][nbx_caching], you
have to add `:decorator` to the dependency list (recommended adding it).
* For enabling Telemetry events dispatched by Nebulex, you have to add
`:telemetry` to the dependency list (recommended adding it).
See [telemetry guide][telemetry].
[telemetry]: http://hexdocs.pm/nebulex/3.0.0-rc.1/telemetry.html
Then run `mix deps.get` in your shell to fetch the dependencies. If you want to
use another cache adapter, just choose the proper dependency from the table
above.
Finally, in the cache definition, you will need to specify the `adapter:`
respective to the chosen dependency. For the local cache would be:
```elixir
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:
```elixir
def start(_type, _args) do
children = [
MyApp.Cache
]
...
```
You're now ready to use the cache:
```elixir
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.1/getting-started.html
[docs-rc1]: http://hexdocs.pm/nebulex/3.0.0-rc.1/Nebulex.html
## A quickstart example using caching decorators
This example demonstrates how to use Nebulex with Ecto and declarative caching:
```elixir
# 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
* [Getting Started][getting_started] - Learn how to set up and use Nebulex
* [Documentation][docs] - Complete API reference
* [Examples][examples] - Example applications
* [Upgrading to v3.0](http://hexdocs.pm/nebulex/3.0.0-rc.1/v3-0.html) - Migration guide for v3.0
[examples]: https://github.com/elixir-nebulex/nebulex_examples
## Testing
To run only the tests:
```
$ mix test
```
Additionally, to run all Nebulex checks run:
```
$ mix test.ci
```
The `mix check` will run the tests, coverage, credo, dialyzer, etc. This is the
recommended way to test Nebulex.
## Benchmarks
Nebulex provides a set of basic benchmark tests using the library
[benchee](https://github.com/PragTob/benchee), and they are located within
the directory [benchmarks](./benchmarks).
To run a benchmark test you have to run:
```
$ 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
Contributions to Nebulex are very welcome and appreciated!
Use the [issue tracker](https://github.com/elixir-nebulex/nebulex/issues)
for bug reports or feature requests. Open a
[pull request](https://github.com/elixir-nebulex/nebulex/pulls)
when you are ready to contribute.
When submitting a pull request you should not update the
[CHANGELOG.md](CHANGELOG.md), and also make sure you test your changes
thoroughly, include unit tests alongside new or changed code.
Before to submit a PR it is highly recommended to run `mix test.ci` and ensure
all checks run successfully.
## Copyright and License
Copyright (c) 2017, Carlos Bolaños.
Nebulex source code is licensed under the [MIT License](LICENSE).
