菜单
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.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/TheBushidoCollective/han --skill ecto-changesets命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
Review current branch changes against REVIEW.md guidelines
Use when kotlin coroutines for structured concurrency including suspend functions, coroutine builders, Flow, channels, and patterns for building efficient asynchronous code with cancellation and exception handling.
Use when building modular Angular applications requiring dependency injection with providers, injectors, and services.
基于 SOC 职业分类
| 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"] |
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Use ecto-changesets when you need to:
validate_required/2 before other validations to provide clear errorstraverse_errors/2 to format errors for API responsesget_change/2 for conditional logic on modified fieldsget_field/2 when you need current value (changed or existing)on_replace option appropriately for association changesetscast/3 allowed listchangeset.valid? before calling Repo functionsput_change/3 instead of validations for constraintschange/2 when you need validation with cast/3on_replace: :delete for many_to_many associationsget_change/2 when you need get_field/2 (or vice versa)