Skip to content
Skills Library
Programming · Analysis

ecto-constraint-debug

/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.

Licence
MIT
Last repository change
22.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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

Original author description

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

How it works

  1. Iron Laws
  2. Step-by-Step Debugging
  3. Quick Fixes by Constraint Type
  4. References
Original SKILL.md headings · 66 lines, 399 words
SKILL.md preview
---
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
Files in this package (2)
  • SKILL.md 3 KB
  • references/constraint-patterns.md 5 KB

Versions

RepositoryScoreLicence
This page · oliver-kriska/claude-elixir-phoenix90MIT
oliver-kriska/claude-elixir-phoenix90MIT

Database snapshot: 13.11.2026 · package version 2587102bcc47 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100ecto
    Guide for Ecto schemas, changesets, queries, migrations, and Multi. Use when writing Ecto migrations, querying or mutating Ecto schemas, designing changesets, working with Ecto.Multi, or choosing between Ecto query DSL and raw SQL.
  • 100ecto-nested-associations
    Use when one form or operation manages parent and child records together — cast_assoc/cast_embed, inputs_for with sort/drop params, on_replace, Ecto.Multi across tables, FK cascade design.
  • 100ecto
    Design and debug Elixir persistence with Ecto. Use for schemas, changesets, queries, preloads, transactions, migrations, multi-tenancy, and data access through application contexts. Covers database query performance and connection pools.
  • 100estack-ecto
    Implement Ecto data access, ownership, changesets, transactions, and safe migrations. Use when editing schemas, queries, tenant-scoped contexts, or database writes.
  • 100ecto-patterns
    Use when a task touches Ecto, even a how-to question: schemas, changesets, validations, queries, preloads, Multi, migrations, constraints, money fields. Load it before writing Ecto code. Skip for Ash.
  • 100ecto-patterns
    Use when a task touches Ecto, even a how-to question: schemas, changesets, validations, queries, preloads, Multi…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.