# Ecto Constraint Debug

Debug Ecto constraint violations - trace triggers, check migrations, find duplicate data.

- Repository: https://github.com/oliver-kriska/claude-elixir-phoenix (572 stars)
- Category: Testing
- License: MIT
- Last updated: 2026-10-30
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add oliver-kriska/claude-elixir-phoenix --skill ecto-constraint-debug -g -a claude-code -y`
Codex: `npx skills add oliver-kriska/claude-elixir-phoenix --skill ecto-constraint-debug -g -a codex -y`
Cursor: `npx skills add oliver-kriska/claude-elixir-phoenix --skill ecto-constraint-debug -g -a cursor -y`
Gemini CLI: `npx skills add oliver-kriska/claude-elixir-phoenix --skill ecto-constraint-debug -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add oliver-kriska/claude-elixir-phoenix`

## Description

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# 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

The rest: https://github.com/oliver-kriska/claude-elixir-phoenix/blob/HEAD/plugins/elixir-phoenix/skills/ecto-constraint-debug/SKILL.md