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

ecto_option()

(since 0.1.0)
@type ecto_option() ::
  {:prefix, binary()}
  | {:timeout, integer() | :infinity}
  | {:log, Logger.level() | false}
  | {:telemetry_event, any()}
  | {:telemetry_options, any()}

fetch_option()

(since 0.1.0)
@type fetch_option() ::
  {:lock, lock_mode() | false}
  | {:preload, atom() | list()}
  | {:error_tag, false | any()}
  | {:raise_cast_error, boolean()}
  | ecto_option()

fetch_result()

(since 0.1.0)
@type fetch_result() ::
  {:ok, Ecto.Schema.t()}
  | {:error, {:not_found, Ecto.Queryable.t() | any()}}
  | {:error, :not_found}

lock_mode()

(since 0.1.0)
@type lock_mode() ::
  :key_share
  | :share
  | :no_key_update
  | :update
  | (Ecto.Queryable.t() -> Ecto.Queryable.t())

Callbacks

advisory_xact_lock(arg1)

(since 0.1.0)
@callback advisory_xact_lock(atom() | binary()) :: :ok

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.

count(queryable)

(since 0.1.0)
@callback count(queryable :: Ecto.Queryable.t()) :: non_neg_integer()

Allows to conveniently count a queryable.

See count/2 for options.

count(queryable, list)

(since 0.15.0)
@callback count(queryable :: Ecto.Queryable.t(), [ecto_option()]) :: non_neg_integer()

Allows to conveniently count a queryable.

Ecto options

fetch(schema, id)

(since 0.1.0)
@callback fetch(schema :: module(), id :: any()) :: fetch_result()

Fetches a record by primary key or returns an error tuple.

See fetch_by/3.

fetch(schema, id, list)

(since 0.1.0)
@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.

fetch_by(queryable, clauses)

(since 0.1.0)
@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.

fetch_by(queryable, clauses, list)

(since 0.1.0)
@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 :ok tuple.
  • 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: false

Automatic 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

  • lock any of [:key_share, :share, :no_key_update, :update] or a function (defaults to false)
  • preload allows to preload associations
  • error_tag allows to specify a custom "tag" value (instead of the queryable)
                     or `false` to disabled tagged error tuples
  • raise_cast_error raise CastError instead of converting to :not_found (defaults to false)

Ecto options