oliver-kriska/claude-elixir-phoenix / targets/codex/skills/ecto-constraint-debug
ecto-constraint-debug
VerifiedDebug Ecto constraint violations - trace triggers, check migrations; Use when seeing unique_constraint…
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 3.1 KB |
| references/constraint-patterns.md | markdown | 5.1 KB |
SKILL.md
View on GitHub---
name: ecto-constraint-debug
description: Debug Ecto constraint violations - trace triggers, check migrations;
Use when seeing unique_constraint…
---
# 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |