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
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/ecto-constraint-debug
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Ecto Constraint Debugging
Ash projects: Ash surfaces DB constraints through its own error DSL. Use the
ash-frameworkskill —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
- 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 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 ${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
Files (claude-elixir-phoenix)
-
references
-
constraint-patterns.md 5.1 KB
Loading…
-
-
SKILL.md 3.2 KB
--- name: ecto-constraint-debug description: Debug Ecto constraint violations - trace triggers, check migrations, find duplicate data. Use when seeing unique_constraint, foreign_key_constraint, or check_constraint errors. effort: medium --- # 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 `${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
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.