A custom type that maps atoms to strings or integers.

Ecto.Enum must be used whenever you want to keep atom values in a field. Since atoms cannot be persisted to the database, Ecto.Enum converts them to a string or an integer when writing to the database and converts them back to atoms when loading data. It can be used in your schemas as follows:

# Stored as strings
field :status, Ecto.Enum, values: [:foo, :bar, :baz]

or

# Stored as integers
field :status, Ecto.Enum, values: [foo: 1, bar: 2, baz: 5]

Therefore, the type to be used in your migrations for enum fields depend on the choice above. For the cases above, one would do, respectively:

add :status, :string

or

add :status, :integer

Some databases also support enum types, which you could use in combination with the above.

Composite types, such as :array, are also supported which allow selecting multiple values per record:

field :roles, {:array, Ecto.Enum}, values: [:author, :editor, :admin]

Overall, :values must be a list of atoms or a keyword list. Values will be cast to atoms safely and only if the atom exists in the list (otherwise an error will be raised). Attempting to load any string/integer not represented by an atom in the list will be invalid.

The helper function mappings/2 returns the mappings for a given schema and field, which can be used in places like form drop-downs. For example, given the following schema:

defmodule EnumSchema do
  use Ecto.Schema

  schema "my_schema" do
    field :my_enum, Ecto.Enum, values: [:foo, :bar, :baz]
  end
end

You can call mappings/2 like this:

Ecto.Enum.mappings(EnumSchema, :my_enum)
#=> [foo: "foo", bar: "bar", baz: "baz"]

If you want the values only, you can use Ecto.Enum.values/2, and if you want the dump values only, you can use Ecto.Enum.dump_values/2.

Embeds

Ecto.Enum allows to customize how fields are dumped within embeds through the :embed_as option. Two alternatives are supported: :values, which will save the enum keys (and not their respective mapping), and :dumped, which will save the dumped value. The default is :values. For example, assuming the following schema:

defmodule EnumSchema do
  use Ecto.Schema

  schema "my_schema" do
    embeds_one :embed, Embed do
      field :embed_as_values, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :values
      field :embed_as_dump, Ecto.Enum, values: [foo: 1, bar: 2], embed_as: :dumped
    end
  end
end

The :embed_as_values field value will save :foo or :bar, while the :embed_as_dump field value will save 1 or 2.