Enumex.Static.Adapter behaviour (Enumex v1.0.0)

A behaviour defining callbacks for a database migrations, providing a standardised interface for creating, modifying and removing enumerated types across different database systems.

Example

defmodule MyAdapter do
  @behaviour Enumex.Static.Adapter

  # implementation
end

Summary

Types

opts()

Options for various database operations.

query_prefix()

The type representing a query prefix.

result()

The type representing a result of the database query.

t()

The type representing an adapter module.

Callbacks

add_value(t, t, opts)

Adds the enum value to a database enumerated type.

create_enum(t, list, opts)

Creates the database enumerated type with a specific values.

drop_enum(t, enum_name, opts)

Drops the database enumerated type.

drop_value(t, t, t, opts)

Drops the enum value from a database enumerated type.

get_default_prefix(t, opts)

Fetches a default database prefix.

get_index_function_name(t, enum_name, opts)

Returns index function name.

get_values_with_index(t, enum_name, opts)

Fetches the enumerated type values and their indexes using the index function.

rename_enum(t, enum_name, enum_name, opts)

Renames the database enumerated type.

rename_value(t, t, t, opts)

Renames the enum value in a database enumerated type.

Types

opts()

@type opts() :: [
  in_transaction: boolean(),
  log:
    false
    | :debug
    | :info
    | :notice
    | :warning
    | :error
    | :critical
    | :alert
    | :emergency,
  query_prefix: query_prefix(),
  timeout: timeout()
]

Options for various database operations.

These options customize how queries are executed and logged:

Options

The supported options are:

:in_transaction - Instructs adapter that specific operation runs within a transaction. This option is also determined automatically within a Enumex.Static.Migration wrapper module.
:log - Configures logging level for query execution. Use false to disable logging or levels from :debug to :emergency for a different severity levels.
:query_prefix - A query prefix
:timeout - Query timeout duration

All options are optional and can be combined in any order.

query_prefix()

@type query_prefix() :: String.t() | nil

The type representing a query prefix.

result()

@type result() :: {:ok, Postgrex.Result.t()} | {:error, Postgrex.Error.t()} | any()

The type representing a result of the database query.

t()

@type t() :: module()

The type representing an adapter module.

Callbacks

add_value(t, t, opts)

@callback add_value(Ecto.Repo.t(), Enumex.Value.t(), opts()) :: result()

Adds the enum value to a database enumerated type.

iex> new_value = Enumex.Value.new(ExampleEnum, :example, :new, 3)
iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.add_value(Ecto.Migration.repo(), new_value, log: true)
%Postgrex.Result{}

create_enum(t, list, opts)

@callback create_enum(Ecto.Repo.t(), [Enumex.Value.t()], opts()) :: result()

Creates the database enumerated type with a specific values.

iex> first_value = Enumex.Value.new(ExampleEnum, :example, :first, 1)
iex> second_value = Enumex.Value.new(ExampleEnum, :example, :second, 2)
iex> values = [first_value, second_value]
iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.create_enum(Ecto.Migration.repo(), values, log: true)
%Postgrex.Result{}

drop_enum(t, enum_name, opts)

@callback drop_enum(Ecto.Repo.t(), Enumex.Value.enum_name(), opts()) :: result()

Drops the database enumerated type.

iex> first_value = Enumex.Value.new(ExampleEnum, :example, :first, 1)
iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.create_enum(Ecto.Migration.repo(), first_value.enum_name, log: true)
%Postgrex.Result{}

drop_value(t, t, t, opts)

@callback drop_value(Ecto.Repo.t(), Enumex.Value.t(), Enumex.Value.t(), opts()) ::
  result()

Drops the enum value from a database enumerated type.

iex> existing_value = Enumex.Value.new(ExampleEnum, :example, :existing, 3)
iex> default_value = Enumex.Value.new(ExampleEnum, :example, :another_existing, 1)
iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.drop_value(Ecto.Migration.repo(), existing_value, default_value, log: true)
%Postgrex.Result{}

get_default_prefix(t, opts)

@callback get_default_prefix(Ecto.Repo.t(), opts()) :: result()

Fetches a default database prefix.

iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.get_default_prefix(Ecto.Migration.repo(), [])
"public"

get_index_function_name(t, enum_name, opts)

@callback get_index_function_name(Ecto.Repo.t(), Enumex.Value.enum_name(), opts()) ::
  String.t() | nil

Returns index function name.

iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.get_index_function_name(Ecto.Migration.repo(), :example, [])
"enumex_get_index_example"
iex> adapter_impl.get_index_function_name(Ecto.Migration.repo(), :example, [query_prefix: "public"])
"public.enumex_get_index_example"

get_values_with_index(t, enum_name, opts)

@callback get_values_with_index(Ecto.Repo.t(), Enumex.Value.enum_name(), opts()) ::
  result()

Fetches the enumerated type values and their indexes using the index function.

iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.get_values_with_index(Ecto.Migration.repo(), :example, [])
%Postgrex.Result{}

rename_enum(t, enum_name, enum_name, opts)

@callback rename_enum(
  Ecto.Repo.t(),
  Enumex.Value.enum_name(),
  Enumex.Value.enum_name(),
  opts()
) :: result()

Renames the database enumerated type.

iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.rename_enum(Ecto.Migration.repo(), :old_enum_name, :new_enum_name, log: true)
%Postgrex.Result{}

rename_value(t, t, t, opts)

@callback rename_value(Ecto.Repo.t(), Enumex.Value.t(), Enumex.Value.t(), opts()) ::
  result()

Renames the enum value in a database enumerated type.

iex> old_value = Enumex.Value.new(ExampleEnum, :example, :old, 1)
iex> new_value = %{old_value | id: :new}
iex> adapter_impl = Enumex.Static.Adapters.Postgres
iex> adapter_impl.rename_value(Ecto.Migration.repo(), old_value, new_value, log: true)
%Postgrex.Result{}