ecto-changesets

name	ecto-changesets
user-invocable	false
description	Use when validating and casting data with Ecto changesets including field validation, constraints, nested changesets, and data transformation. Use for ensuring data integrity before database operations.
allowed-tools	["Bash","Read"]

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: "[e-mail]"})

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: "[e-mail]",
  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