Defines functions and the Ecto.Type behaviour for implementing basic custom types.

Ecto provides two types of custom types: basic types and parameterized types. Basic types are simple, requiring only four callbacks to be implemented, and are enough for most occasions. Parameterized types can be customized on the field definition and provide a wide variety of callbacks.

The definition of basic custom types and all of their callbacks are available in this module. You can learn more about parameterized types in Ecto.ParameterizedType. If in doubt, prefer to use basic custom types and rely on parameterized types if you need the extra functionality.

External vs internal vs database representation

The core functionality of a custom type is the mapping between external, internal and database representations of a value belonging to the type.

For a definition of external and internal data take a look at the related section in the changeset documentation.

stateDiagram-v2
  external: External Data
  internal: Internal Data
  database: Database Data
  external --> internal: cast/1
  external --> database: dump/1
  internal --> database: dump/1
  database --> internal: load/1

Example

Imagine you want to store a URI struct as part of a schema in a url-shortening service. There isn't an Ecto field type to support that value at runtime therefore a custom one is needed.

You also want to query not only by the full url, but for example by specific ports used. This is possible by putting the URI data into a map field instead of just storing the plain string representation.

from s in ShortUrl,
  where: fragment("?->>? ILIKE ?", s.original_url, "port", "443")

So the custom type does need to handle the conversion from external data to runtime data (cast/1) as well as transforming that runtime data into the :map Ecto native type and back (dump/1 and load/1).

defmodule EctoURI do
  use Ecto.Type
  def type, do: :map

  # Provide custom casting rules.
  # Cast strings into the URI struct to be used at runtime
  def cast(uri) when is_binary(uri) do
    {:ok, URI.parse(uri)}
  end

  # Accept casting of URI structs as well
  def cast(%URI{} = uri), do: {:ok, uri}

  # Everything else is a failure though
  def cast(_), do: :error

  # When loading data from the database, as long as it's a map,
  # we just put the data back into a URI struct to be stored in
  # the loaded schema struct.
  def load(data) when is_map(data) do
    data =
      for {key, val} <- data do
        {String.to_existing_atom(key), val}
      end
    {:ok, struct!(URI, data)}
  end

  # When dumping data to the database, we *expect* a URI struct
  # but any value could be inserted into the schema struct at runtime,
  # so we need to guard against them.
  def dump(%URI{} = uri), do: {:ok, Map.from_struct(uri)}
  def dump(_), do: :error
end

Now we can use our new field type above in our schemas:

defmodule ShortUrl do
  use Ecto.Schema

  schema "posts" do
    field :original_url, EctoURI
  end
end

Note: nil values are always bypassed and cannot be handled by custom types.

Custom types and primary keys

Remember that, if you change the type of your primary keys, you will also need to change the type of all associations that point to said primary key.

Imagine you want to encode the ID so they cannot enumerate the content in your application. An Ecto type could handle the conversion between the encoded version of the id and its representation in the database. For the sake of simplicity, we'll use base64 encoding in this example:

defmodule EncodedId do
  use Ecto.Type

  def type, do: :id

  def cast(id) when is_integer(id) do
    {:ok, encode_id(id)}
  end
  def cast(_), do: :error

  def dump(id) when is_binary(id) do
    {:ok, id_decoded} = Base.decode64(id)
    {:ok, String.to_integer(id_decoded)}
  end

  def load(id) when is_integer(id) do
    {:ok, encode_id(id)}
  end

  defp encode_id(id) do
    id
    |> Integer.to_string()
    |> Base.encode64()
  end
end

To use it as the type for the id in our schema, we can use the @primary_key module attribute:

defmodule BlogPost do
  use Ecto.Schema

  @primary_key {:id, EncodedId, autogenerate: true}
  schema "posts" do
    belongs_to :author, Author, type: EncodedId
    field :content, :string
  end
end

defmodule Author do
  use Ecto.Schema

  @primary_key {:id, EncodedId, autogenerate: true}
  schema "authors" do
    field :name, :string
    has_many :posts, BlogPost
  end
end

The @primary_key attribute will tell ecto which type to use for the id.

Note the type: EncodedId option given to belongs_to in the BlogPost schema. By default, Ecto will treat associations as if their keys were :integers. Our primary keys are a custom type, so when Ecto tries to cast those ids, it will fail.

Alternatively, you can set @foreign_key_type EncodedId after @primary_key to automatically configure the type of all belongs_to fields.