ecto-constraint-debug
# ecto-constraint-debug This skill provides systematic debugging methods for Ecto constraint violations in Elixir Phoenix applications. Use it when encountering `Ecto.ConstraintError` or changeset errors related to unique constraints, foreign key constraints, or check constraints by parsing error messages, locating constraint definitions in migrations, tracing all insert/update code paths, and identifying root causes like race conditions, data validation gaps, or concurrent request issues.
git clone --depth 1 https://github.com/oliver-kriska/claude-elixir-phoenix /tmp/ecto-constraint-debug && cp -r /tmp/ecto-constraint-debug/targets/amp/skills/ecto-constraint-debug ~/.claude/skills/ecto-constraint-debugSKILL.md
# Ecto Constraint Debugging > **Ash projects**: Ash surfaces DB constraints through its own error DSL. Use the `ash-framework` skill — `mix usage_rules.search_docs "constraint" -p ash_postgres`. Systematic approach to diagnosing constraint violations. Load when you see `Ecto.ConstraintError`, `unique_constraint`, `foreign_key_constraint`, or constraint-related changeset errors. ## Iron Laws 1. **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 2. **CHECK MIGRATION BEFORE CODE** — Verify the constraint definition in `priv/repo/migrations/` matches what the schema expects 3. **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 4. **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` or `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 `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 - `references/constraint-patterns.md` - Detailed patterns for each constraint type
Ash Framework — resources, actions, policies, aggregates, calculations,
Compatibility alias for the Elixir/Phoenix plugin's LiveView assigns audit. Invoke explicitly with /lv:assigns.
Inspect LiveView socket assigns for memory bloat — missing temporary_assigns, unused assigns, unbounded lists needing streams, memory estimates. Use when LiveView memory grows or you need to add temporary_assigns.
Project health audit and health check — architecture, performance, tests, dependencies, code quality. Use when assessing overall project health, before releases, or after refactors.
Analyze Phoenix context boundaries and module coupling via mix xref. Use when checking cross-context calls, validating dependencies, before splitting modules, or reviewing architecture.
Brainstorm Elixir/Phoenix features — explore ideas, compare approaches, gather requirements. Use when vague idea, not sure how to approach, or want to discuss before plan.
Interactive briefing of a plan file — explains reasoning, schema decisions, component choices. Use when developers need to understand a plan before approving.
Summarize and review what changed while you were away. Use after a weekend, vacation, or flight to check missed PRs, git commits, Linear tickets, and meetings — one prioritized brief, not a firehose.