Claude-elixir-phoenix ecto-constraint-debug

Debug Ecto constraint violations - trace triggers, check migrations, find duplicate data. Use when seeing unique_constraint, foreign_key_constraint, or check_constraint errors.

install

source · Clone the upstream repo

git clone https://github.com/oliver-kriska/claude-elixir-phoenix

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/oliver-kriska/claude-elixir-phoenix "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/elixir-phoenix/skills/ecto-constraint-debug" ~/.claude/skills/oliver-kriska-claude-elixir-phoenix-ecto-constraint-debug && rm -rf "$T"

manifest: plugins/elixir-phoenix/skills/ecto-constraint-debug/SKILL.md

Ecto Constraint Debugging

Systematic approach to diagnosing constraint violations. Load when you see

Ecto.ConstraintError

unique_constraint

foreign_key_constraint

, or constraint-related changeset errors.

Iron Laws

READ THE CONSTRAINT NAME — The constraint name (e.g.,
```
links_url_index
```
) tells you exactly which index/constraint failed. Parse it from the error message first
CHECK MIGRATION BEFORE CODE — Verify the constraint definition in
```
priv/repo/migrations/
```
matches what the schema expects
TRACE ALL INSERT PATHS — Find every code path that inserts into the constrained table. The bug is often in a path you didn't consider
RACE CONDITION UNTIL PROVEN OTHERWISE — If validation passes but constraint fails, assume concurrent inserts until you prove a single-request cause

Step-by-Step Debugging

Step 1: Parse the Error

Extract from the error message:

Constraint name (e.g.,
```
users_email_index
```
)
Table name (e.g.,
```
users
```
)
Operation (insert, update, or delete)
Conflicting values (if available in logs)

Step 2: Find the Migration

Use Grep to search for the constraint name in

priv/repo/migrations/

. Also check for

create unique_index

create index

add constraint

Verify: Does the migration constraint match the schema's

unique_constraint/3

foreign_key_constraint/3

call?

Step 3: Find the Schema

Use Grep to find constraint handling in changesets (

unique_constraint

foreign_key_constraint

check_constraint

) in

lib/

Step 4: Trace Insert Paths

Find ALL callers that insert/update this schema:

Use Grep to find all insert/update paths (

Repo.insert

Repo.update

Repo.insert_all

cast_assoc

) in

lib/

Step 5: Identify the Cause

Symptom	Likely Cause	Fix Pattern
Same user triggers twice	Race condition (double-click, retry)	Upsert with `on_conflict`
Multiple parents share child	`cast_assoc` doesn't dedup across changesets	Dedup before building changesets
Concurrent API requests	Missing transaction isolation	Wrap in `Repo.transaction` or use upsert
Migration added constraint to existing data	Data violates new constraint	Backfill or clean data first

Step 6: Apply Fix

See

${CLAUDE_SKILL_DIR}/references/constraint-patterns.md

for detailed fix patterns.

Quick Fixes by Constraint Type

Unique violation → Upsert:

Repo.insert(changeset, on_conflict: :replace_all, conflict_target: [:field])

Foreign key violation → Check: Does the referenced record exist? Was it deleted concurrently?

Check constraint → Validate: Does the value satisfy the constraint condition?

References

${CLAUDE_SKILL_DIR}/references/constraint-patterns.md

- Detailed patterns for each constraint type