How I design a CRUD module in Elixir

Sun, 25 Oct 2026 15:21:12 +0100

How I design a CRUD module in Elixir

Most resources need the same operations: get, list, count, create, update, delete. The pattern I use:

a behaviour that every CRUD module implements;
a set of macros with the default implementation of each operation;
one standalone CRUD module per resource, mixing default and custom functions;
application errors only, never a nil or a raw changeset;
an event for every operation that changes the data.

The behaviour

defmodule MyApp.Crud do
 alias MyApp.Errors.Error

 @callback get(id :: term(), opts :: keyword()) ::
 {:ok, struct()} | {:error, Error.t()}

 @callback list(params :: map(), opts :: keyword()) ::
 {:ok, [struct()]} | {:error, Error.t()}

 @callback list_query(query :: struct()) :: Ecto.Query.t()

 @callback count(params :: map()) ::
 {:ok, non_neg_integer()} | {:error, Error.t()}

 @callback count_query(query :: struct()) :: Ecto.Query.t()

 @callback create(attrs :: map()) ::
 {:ok, struct()} | {:error, Error.t()}

 @callback update(entity_or_id :: struct() | term(), attrs :: map()) ::
 {:ok, struct()} | {:error, Error.t()}

 @callback delete(entity_or_id :: struct() | term()) ::
 {:ok, struct()} | {:error, Error.t()}

 @callback topic(query :: map()) :: String.t()

 @callback topics(entity :: struct()) :: [String.t()]

 @callback publish_event(result, action :: atom(), opts :: keyword()) :: result
 when result: {:ok, struct()} | {:error, Error.t()} | struct()
end

Every CRUD module has the same API, whatever its implementation.
update/2 and delete/1 take the entity or its id.
count_query/1 turns a validated query into an Ecto.Query with the filters, used by count/1. list_query/1 adds what only the list needs (e.g. the order), used by list/2.
topic/1, topics/1 and publish_event/3 are for the events.

The default implementation: one macro per operation

use MyApp.Crud stores the options in a @crud_config map. Then each macro defines one function of the behaviour, as a call to a plain do_* function with the config:

Phoenix-Pubsub on Buro notes

How I design a CRUD module in Elixir

How I design a CRUD module in Elixir

The behaviour

The default implementation: one macro per operation