BitcrowdEcto. Repo behaviour
(bitcrowd_ecto v1.2.0)
View Source
Extensions for Ecto repos.
Usage
defmodule MyApp.Repo do
use Ecto.Repo, otp_app: :my_app, adapter: Ecto.Adapters.Postgres
use BitcrowdEcto.Repo
end
Summary
Callbacks
Acquires an advisory lock for a named resource.
Allows to conveniently count a queryable.
Allows to conveniently count a queryable.
Fetches a record by primary key or returns an error tuple.
Fetches a record by given clauses or returns an error tuple.
Fetches a record by given clauses or returns an error tuple.
Fetches a record by given clauses or returns an error tuple.
Types
@type ecto_option() :: {:prefix, binary()} | {:timeout, integer() | :infinity} | {:log, Logger.level() | false} | {:telemetry_event, any()} | {:telemetry_options, any()}
@type fetch_result() :: {:ok, Ecto.Schema.t()} | {:error, {:not_found, Ecto.Queryable.t() | any()}} | {:error, :not_found}
@type lock_mode() :: :key_share | :share | :no_key_update | :update | (Ecto.Queryable.t() -> Ecto.Queryable.t())
Callbacks
Acquires an advisory lock for a named resource.
Advisory locks are helpful when you don't have a specific row to lock, but also don't want to lock an entire table.
See https://www.postgresql.org/docs/9.4/explicit-locking.html#ADVISORY-LOCKS
Example
MyApp.Repo.transaction(fn ->
MyApp.Repo.advisory_lock(:foo)
# Advisory lock is held until end of transaction
end)A note on the advisory lock key
pg_advisory_xact_lock() has two versions: One which you pass a 64-bit signed integer as
the lock key, and one which you pass two 32-bit integers as the keys (e.g., one
"application" key and one specific lock key), in which case PostgreSQL concatenates them
into a 64-bit value. In any case you need to pass integers.
We decided that we wanted to have atom or string keys for better readability. Hence, in order to make PostgreSQL happy, we hash these strings into 64 bits signed ints.
64 bits make a pretty big number already, so it is quite unlikely that two of our keys (or keys of other libraries that use advisory locks, e.g. Oban) collide. But for an extra false sense of safety we use a crypto hash algorithm to ensure that keys spread out over the domain uniformly. Luckily, taking a prefix of a cryptographic hash does not break its uniformity.
@callback count(queryable :: Ecto.Queryable.t()) :: non_neg_integer()
Allows to conveniently count a queryable.
See count/2 for options.
@callback count(queryable :: Ecto.Queryable.t(), [ecto_option()]) :: non_neg_integer()
Allows to conveniently count a queryable.
Ecto options
prefixSee https://hexdocs.pm/ecto/Ecto.Repo.html#c:one/2-optionstimeoutSee Ecto's Shared OptionslogSee Ecto's Shared Optionstelemetry_eventSee Ecto's Shared Optionstelemetry_optionsSee Ecto's Shared Options
@callback fetch(schema :: module(), id :: any()) :: fetch_result()
Fetches a record by primary key or returns an error tuple.
See fetch_by/3.
@callback fetch(schema :: module(), id :: any(), [fetch_option()]) :: fetch_result()
Fetches a record by given clauses or returns an error tuple.
See fetch_by/3 for options.
@callback fetch_by(queryable :: Ecto.Queryable.t(), clauses :: map() | keyword()) :: fetch_result()
Fetches a record by given clauses or returns an error tuple.
See fetch_by/3 for options.
@callback fetch_by(queryable :: Ecto.Queryable.t(), clauses :: map() | keyword(), [ fetch_option() ]) :: fetch_result()
Fetches a record by given clauses or returns an error tuple.
- On success, the record is wrapped in a
:oktuple. - On error, an error tuple is returned
Tagged error tuples
By default, the error tuple will be a "tagged" :not_found tuple, e.g.
{:error, {:not_found, Account}} for a fetch_by(Account, id: 1) call, where the "tag" is
the unmodified queryable parameter. The idea behind this is to avoid mix-ups of
naked :not_found errors, particularly in with clauses.
Tagging behaviour may be disabled by passing the error_tag: false option to return
naked {:error, :not_found} tuples instead. For existing applications where untagged errors
are the norm, one may set the tagged_not_found_errors: false option when using this module.
use BitcrowdEcto.Repo, tagged_not_found_errors: falseAutomatic conversion of CastError
Passing invalid values that would normally result in an Ecto.Query.CastError will result in
a :not_found error tuple. This is useful for low-level handling of invalid UUIDs passed
from a hand-edited URL to the domain layer.
This behaviour can be disabled by passing raise_cast_error: false.
Options
lockany of[:key_share, :share, :no_key_update, :update]or a function (defaults tofalse)preloadallows to preload associationserror_tagallows to specify a custom "tag" value (instead of the queryable)or `false` to disabled tagged error tuplesraise_cast_errorraiseCastErrorinstead of converting to:not_found(defaults tofalse)
Ecto options
prefixSee https://hexdocs.pm/ecto/Ecto.Repo.html#c:one/2-optionstimeoutSee Ecto's Shared OptionslogSee Ecto's Shared Optionstelemetry_eventSee Ecto's Shared Optionstelemetry_optionsSee Ecto's Shared Options