Ecto Changesets

Master Ecto changesets to validate, cast, and transform data before database operations. This skill covers changeset creation, validation, constraints, handling associations, and advanced patterns for maintaining data integrity.

Basic Changeset

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :name, :string field :email, :string field :age, :integer

timestamps()

end

def changeset(user, params \ %{}) do user |> cast(params, [:name, :email, :age]) |> validate_required([:name, :email]) end end

Usage

changeset = MyApp.User.changeset(%MyApp.User{}, %{name: "John", email: "john@example.com"})

Changesets filter and validate parameters before they're applied to a struct. The cast/3 function specifies which fields can be changed, and validate_required/2

ensures specific fields are present.

Creating and Validating Changesets

defmodule MyApp.Person do use Ecto.Schema import Ecto.Changeset

schema "people" do field :first_name, :string field :last_name, :string field :age, :integer

timestamps()

end

def changeset(person, params \ %{}) do person |> cast(params, [:first_name, :last_name, :age]) |> validate_required([:first_name, :last_name]) |> validate_number(:age, greater_than_or_equal_to: 0) end end

Create changeset

changeset = MyApp.Person.changeset(%MyApp.Person{}, %{first_name: "Jane"})

Check validity

changeset.valid? # false, last_name is missing

Access errors

changeset.errors

[first_name: {"can't be blank", [validation: :required]},

last_name: {"can't be blank", [validation: :required]}]

The valid? field indicates whether the changeset has any errors. The errors

field contains a keyword list of validation failures with error messages and metadata.

Inserting with Changesets

person = %MyApp.Person{} changeset = MyApp.Person.changeset(person, %{ first_name: "John", last_name: "Doe", age: 30 })

case MyApp.Repo.insert(changeset) do {:ok, person} -> # Successfully inserted IO.puts("Created person with ID: #{person.id}")

{:error, changeset} -> # Validation or constraint errors IO.inspect(changeset.errors) end

The Repo.insert/1 function accepts a changeset and returns {:ok, struct} on success or {:error, changeset} on failure. Pattern matching makes error handling straightforward.

Updating with Changesets

person = MyApp.Repo.get!(MyApp.Person, 1) changeset = MyApp.Person.changeset(person, %{age: 31})

case MyApp.Repo.update(changeset) do {:ok, updated_person} -> # Successfully updated IO.puts("Updated person age to: #{updated_person.age}")

{:error, changeset} -> # Validation or constraint errors IO.inspect(changeset.errors) end

Updates work similarly to inserts, but start with an existing struct from the database. The changeset tracks which fields have changed.

Type Casting

changeset = Ecto.Changeset.cast(%MyApp.User{}, %{"age" => "25"}, [:age]) user = MyApp.Repo.insert!(changeset) user.age # 25 (integer, not string)

The cast/3 function automatically converts parameter values to their schema-defined types. Strings like "25" are converted to integers when the field type is :integer .

Field Validations

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :email, :string field :username, :string field :age, :integer field :bio, :string field :website, :string

timestamps()

end

def changeset(user, params \ %{}) do user |> cast(params, [:email, :username, :age, :bio, :website]) |> validate_required([:email, :username]) |> validate_format(:email, ~r/@/) |> validate_length(:username, min: 3, max: 20) |> validate_length(:bio, max: 500) |> validate_number(:age, greater_than: 0, less_than: 150) |> validate_inclusion(:age, 18..100) |> validate_format(:website, ~r/^https?:///) end end

Ecto provides many built-in validators including validate_format/3 for regex patterns, validate_length/3 for string lengths, validate_number/3 for numeric constraints, and validate_inclusion/3 for allowed values.

Custom Validation Functions

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :email, :string field :password, :string, virtual: true field :password_hash, :string

timestamps()

end

def changeset(user, params \ %{}) do user |> cast(params, [:email, :password]) |> validate_required([:email, :password]) |> validate_email_format() |> validate_password_strength() |> hash_password() end

defp validate_email_format(changeset) do changeset |> validate_format(:email, ~r/@/, message: "must be a valid email") |> validate_length(:email, max: 255) end

defp validate_password_strength(changeset) do validate_change(changeset, :password, fn :password, password -> cond do String.length(password) < 8 -> [password: "must be at least 8 characters"]

    not String.match?(password, ~r/[A-Z]/) ->
      [password: "must contain at least one uppercase letter"]

    not String.match?(password, ~r/[0-9]/) ->
      [password: "must contain at least one number"]

    true ->
      []
  end
end)

end

defp hash_password(changeset) do case changeset do %Ecto.Changeset{valid?: true, changes: %{password: password}} -> put_change(changeset, :password_hash, hash_password_value(password))

  _ ->
    changeset
end

end

defp hash_password_value(password) do # Use a real hashing library like Argon2 or Bcrypt :crypto.hash(:sha256, password) |> Base.encode64() end end

Custom validation functions use validate_change/3 to add custom logic. The put_change/3 function modifies changeset values, useful for transformations like password hashing.

Constraint Validations

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :email, :string field :username, :string

timestamps()

end

def changeset(user, params \ %{}) do user |> cast(params, [:email, :username]) |> validate_required([:email, :username]) |> unique_constraint(:email) |> unique_constraint(:username) end end

Usage

case MyApp.Repo.insert(changeset) do {:ok, user} -> # Success

{:error, changeset} -> # Will contain unique constraint error if email/username exists changeset.errors end

Constraint validations check database-level constraints like unique indexes. They only run when the changeset is inserted or updated, not during validation.

Unique Constraint with Custom Error Message

def changeset(user, params \ %{}) do user |> cast(params, [:email]) |> validate_required([:email]) |> unique_constraint(:email, name: :users_email_index, message: "has already been taken") end

The unique_constraint/3 function accepts options to specify the constraint name and customize the error message. This maps database constraint violations to user-friendly errors.

Foreign Key Constraints

defmodule MyApp.Comment do use Ecto.Schema import Ecto.Changeset

schema "comments" do field :body, :string belongs_to :post, MyApp.Post

timestamps()

end

def changeset(comment, params \ %{}) do comment |> cast(params, [:body, :post_id]) |> validate_required([:body, :post_id]) |> foreign_key_constraint(:post_id) end end

The foreign_key_constraint/3 function validates that foreign key relationships are valid. If you try to create a comment with a non-existent post_id, the constraint will catch it.

Check Constraints

def changeset(product, params \ %{}) do product |> cast(params, [:price, :discount_price]) |> validate_required([:price]) |> check_constraint(:discount_price, name: :discount_price_must_be_less_than_price, message: "must be less than the regular price") end

Check constraints validate arbitrary database-level rules. The constraint must be defined in your migration with the same name.

Changeset Composition

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :email, :string field :password, :string, virtual: true field :password_hash, :string field :role, :string

timestamps()

end

def registration_changeset(user, params \ %{}) do user |> cast(params, [:email, :password]) |> validate_required([:email, :password]) |> validate_email() |> validate_password() |> hash_password() |> put_change(:role, "user") end

def admin_changeset(user, params \ %{}) do user |> cast(params, [:email, :password, :role]) |> validate_required([:email, :role]) |> validate_email() |> validate_inclusion(:role, ["user", "admin", "moderator"]) |> maybe_hash_password() end

defp validate_email(changeset) do changeset |> validate_format(:email, ~r/@/) |> unique_constraint(:email) end

defp validate_password(changeset) do validate_length(changeset, :password, min: 8) end

defp hash_password(changeset) do case get_change(changeset, :password) do nil -> changeset password -> put_change(changeset, :password_hash, hash(password)) end end

defp maybe_hash_password(changeset) do case get_change(changeset, :password) do nil -> changeset password -> hash_password(changeset) end end

defp hash(password), do: :crypto.hash(:sha256, password) end

Different changesets can be used for different contexts (registration vs. admin updates). This keeps validation logic focused and prevents unintended changes.

Embedded Changeset Validation

defmodule MyApp.UserProfile do use Ecto.Schema import Ecto.Changeset

embedded_schema do field :online, :boolean field :dark_mode, :boolean field :visibility, Ecto.Enum, values: [:public, :private, :friends_only] end

def changeset(profile, attrs \ %{}) do profile |> cast(attrs, [:online, :dark_mode, :visibility]) |> validate_required([:online, :visibility]) end end

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :full_name, :string field :email, :string

embeds_one :profile, MyApp.UserProfile

timestamps()

end

def changeset(user, attrs \ %{}) do user |> cast(attrs, [:full_name, :email]) |> cast_embed(:profile, required: true) end end

Usage

changeset = MyApp.User.changeset(%MyApp.User{}, %{ full_name: "John Doe", email: "john@example.com", profile: %{online: true, visibility: :public} })

changeset.valid? # true

The cast_embed/3 function validates embedded schemas using their own changeset functions. Validation errors in embedded data propagate to the parent changeset.

Custom Embedded Changeset Function

defmodule MyApp.User do use Ecto.Schema import Ecto.Changeset

schema "users" do field :full_name, :string field :email, :string

embeds_one :profile, Profile do
  field :online, :boolean
  field :dark_mode, :boolean
  field :visibility, Ecto.Enum, values: [:public, :private, :friends_only]
end

timestamps()

end

def changeset(user, attrs \ %{}) do user |> cast(attrs, [:full_name, :email]) |> cast_embed(:profile, required: true, with: &profile_changeset/2) end

def profile_changeset(profile, attrs \ %{}) do profile |> cast(attrs, [:online, :dark_mode, :visibility]) |> validate_required([:online, :visibility]) end end

The :with option in cast_embed/3 specifies a custom changeset function for the embedded data, allowing specific validation logic.

Embedded Many Validation

defmodule MyApp.Order do use Ecto.Schema import Ecto.Changeset

schema "orders" do field :customer_name, :string

embeds_many :items, OrderItem do
  field :product_name, :string
  field :quantity, :integer
  field :price, :decimal
end

timestamps()

end

def changeset(order, attrs \ %{}) do order |> cast(attrs, [:customer_name]) |> cast_embed(:items, with: &item_changeset/2) |> validate_required([:customer_name]) |> validate_length(:items, min: 1, message: "must have at least one item") end

defp item_changeset(item, attrs) do item |> cast(attrs, [:product_name, :quantity, :price]) |> validate_required([:product_name, :quantity, :price]) |> validate_number(:quantity, greater_than: 0) |> validate_number(:price, greater_than: 0) end end

Collections of embedded schemas are validated using cast_embed/3 with embeds_many . Each item in the collection is validated independently using its changeset function.

Association Changesets with put_assoc

defmodule MyApp.Post do use Ecto.Schema import Ecto.Changeset

schema "posts" do field :title, :string field :body, :string

many_to_many :tags, MyApp.Tag,
  join_through: "posts_tags",
  on_replace: :delete

timestamps()

end

def changeset(post, params \ %{}) do post |> cast(params, [:title, :body]) |> validate_required([:title, :body]) |> put_assoc(:tags, parse_tags(params)) end

defp parse_tags(params) do (params["tags"] || "") |> String.split(",") |> Enum.map(&String.trim/1) |> Enum.reject(&(&1 == "")) |> Enum.map(&get_or_insert_tag/1) end

defp get_or_insert_tag(name) do MyApp.Repo.get_by(MyApp.Tag, name: name) || MyApp.Repo.insert!(%MyApp.Tag{name: name}) end end

The put_assoc/3 function sets association data on a changeset. When combined with on_replace: :delete , it properly handles adding and removing associations.

Upsert Pattern with Unique Constraints

defmodule MyApp.Tag do use Ecto.Schema import Ecto.Changeset

schema "tags" do field :name, :string

timestamps()

end

def changeset(tag, params \ %{}) do tag |> cast(params, [:name]) |> validate_required([:name]) |> unique_constraint(:name) end end

defp get_or_insert_tag(name) do %MyApp.Tag{} |> MyApp.Tag.changeset(%{name: name}) |> MyApp.Repo.insert() |> case do {:ok, tag} -> tag {:error, _} -> MyApp.Repo.get_by!(MyApp.Tag, name: name) end end

This pattern handles race conditions when inserting records with unique constraints. If the insert fails due to a duplicate, it fetches the existing record.

Batch Upsert with insert_all

defmodule MyApp.Post do use Ecto.Schema import Ecto.Changeset import Ecto.Query

schema "posts" do field :title, :string field :body, :string

many_to_many :tags, MyApp.Tag,
  join_through: "posts_tags",
  on_replace: :delete

timestamps()

end

def changeset(struct, params \ %{}) do struct |> cast(params, [:title, :body]) |> put_assoc(:tags, parse_tags(params)) end

defp parse_tags(params) do (params["tags"] || "") |> String.split(",") |> Enum.map(&String.trim/1) |> Enum.reject(&(&1 == "")) |> insert_and_get_all() end

defp insert_and_get_all([]), do: []

defp insert_and_get_all(names) do timestamp = NaiveDateTime.utc_now() |> NaiveDateTime.truncate(:second) placeholders = %{timestamp: timestamp}

maps = Enum.map(names, fn name ->
  %{
    name: name,
    inserted_at: {:placeholder, :timestamp},
    updated_at: {:placeholder, :timestamp}
  }
end)

MyApp.Repo.insert_all(
  MyApp.Tag,
  maps,
  placeholders: placeholders,
  on_conflict: :nothing
)

MyApp.Repo.all(from t in MyApp.Tag, where: t.name in ^names)

end end

The insert_all/3 function with on_conflict: :nothing performs bulk upserts efficiently, minimizing database round trips when handling multiple associations.

Traversing Changeset Errors

defmodule MyApp.ErrorHelpers do def error_messages(changeset) do Ecto.Changeset.traverse_errors(changeset, fn {msg, opts} -> Enum.reduce(opts, msg, fn {key, value}, acc -> String.replace(acc, "%{#{key}}", to_string(value)) end) end) end end

Usage

changeset = MyApp.User.changeset(%MyApp.User{}, %{}) errors = MyApp.ErrorHelpers.error_messages(changeset)

%{

email: ["can't be blank"],

username: ["can't be blank"]

}

The traverse_errors/2 function walks through all errors in a changeset, including nested changesets, allowing you to format error messages for display.

Conditional Validations

defmodule MyApp.Product do use Ecto.Schema import Ecto.Changeset

schema "products" do field :name, :string field :price, :decimal field :discount_price, :decimal field :is_on_sale, :boolean

timestamps()

end

def changeset(product, params \ %{}) do product |> cast(params, [:name, :price, :discount_price, :is_on_sale]) |> validate_required([:name, :price]) |> validate_discount_price() end

defp validate_discount_price(changeset) do case get_field(changeset, :is_on_sale) do true -> changeset |> validate_required([:discount_price]) |> validate_number(:discount_price, less_than: get_field(changeset, :price))

  _ ->
    changeset
end

end end

Conditional validations apply different rules based on changeset data. Use get_field/2 to access current field values including changes and existing data.

Optimistic Locking with Version Fields

defmodule MyApp.Document do use Ecto.Schema import Ecto.Changeset

schema "documents" do field :title, :string field :content, :string field :version, :integer, default: 1

timestamps()

end

def changeset(document, params \ %{}) do document |> cast(params, [:title, :content]) |> validate_required([:title, :content]) |> optimistic_lock(:version) end end

Update with version check

document = MyApp.Repo.get!(MyApp.Document, 1) changeset = MyApp.Document.changeset(document, %{title: "Updated Title"})

case MyApp.Repo.update(changeset) do {:ok, updated_document} -> # Success, version incremented

{:error, changeset} -> # Stale object error if version doesn't match IO.puts("Document was modified by another process") end

The optimistic_lock/3 function adds version checking to prevent lost updates in concurrent scenarios. The update fails if the version has changed since reading.

Changeset Pipelines for Complex Workflows

defmodule MyApp.UserRegistration do import Ecto.Changeset

def changeset(params) do %MyApp.User{} |> MyApp.User.changeset(params) |> validate_terms_accepted() |> validate_email_verification() |> set_initial_role() |> send_welcome_email() end

defp validate_terms_accepted(changeset) do if get_change(changeset, :terms_accepted) == true do changeset else add_error(changeset, :terms_accepted, "must be accepted") end end

defp validate_email_verification(changeset) do # Custom email verification logic changeset end

defp set_initial_role(changeset) do put_change(changeset, :role, "user") end

defp send_welcome_email(changeset) do if changeset.valid? do # Send email in a separate process email = get_change(changeset, :email) Task.start(fn -> MyApp.Mailer.send_welcome(email) end) end

changeset

end end

Complex workflows can be built as changeset pipelines. Each step validates or transforms data, and the pipeline short-circuits if validation fails.

When to Use This Skill

Use ecto-changesets when you need to:

• Validate user input before database operations

• Cast external data to appropriate types

• Enforce database constraints at the application level

• Transform data before persistence (e.g., hashing passwords)

• Handle nested or embedded data validation

• Manage associations when creating or updating records

• Provide user-friendly error messages for validation failures

• Implement different validation rules for different contexts

• Prevent race conditions with unique constraints

• Track changes to records for audit purposes

• Implement optimistic locking for concurrent updates

• Build complex multi-step data validation workflows

Best Practices

• Always use changesets for external data, never directly create structs

• Define multiple changeset functions for different contexts (create, update, admin)

• Keep changesets focused on validation and casting, not business logic

• Use validate_required/2 before other validations to provide clear errors

• Leverage database constraints and map them with constraint functions

• Use virtual fields for data that shouldn't be persisted

• Compose changesets using private helper functions

• Return changesets from failed operations for better error handling

• Use traverse_errors/2 to format errors for API responses

• Document why specific validations exist, especially complex custom ones

• Test changesets independently from database operations

• Use get_change/2 for conditional logic on modified fields

• Use get_field/2 when you need current value (changed or existing)

• Keep embedded changeset functions close to the parent schema

• Use on_replace option appropriately for association changesets

Common Pitfalls

• Forgetting to include fields in the cast/3 allowed list

• Not checking changeset.valid? before calling Repo functions

• Mixing validation logic with business logic in changeset functions

• Using put_change/3 instead of validations for constraints

• Forgetting to add constraint validations for database constraints

• Not handling race conditions with unique constraints properly

• Overusing custom validations when built-in validators suffice

• Mutating changesets instead of returning new ones

• Not using virtual fields for temporary data like passwords

• Calling Repo functions inside changeset functions

• Using change/2 when you need validation with cast/3

• Forgetting on_replace: :delete for many_to_many associations

• Not validating embedded schemas separately

• Hardcoding error messages instead of using metadata

• Not testing edge cases in custom validations

• Using get_change/2 when you need get_field/2 (or vice versa)

• Not setting appropriate constraint names in migrations

• Ignoring changeset errors in insert/update pipelines

• Performing side effects in validation functions

• Not documenting expected params shape for changesets

Resources

Official Ecto Documentation

• Ecto.Changeset Module

• Changeset API Reference

• Data Validation Guide

• Constraints and Upserts

Validation Functions

• validate_required/3

• validate_format/4

• validate_length/3

• validate_number/3

• validate_inclusion/4

• validate_change/3

Constraint Functions

• unique_constraint/3

• foreign_key_constraint/3

• check_constraint/3

• optimistic_lock/3

Association and Embedded Functions

• cast_assoc/3

• cast_embed/3

• put_assoc/4

Community Resources

• Elixir School - Changesets

• Programming Ecto Book

• Ecto Changeset Best Practices

• Error Handling in Ecto