...
Eroare PostgreSQL · Constrângeri, chei și secvențe

ERROR: there is no unique or exclusion constraint matching the ON CONFLICT specification

Pe scurt

Coloanele din ON CONFLICT (coloana) nu au o constrângere UNIQUE, cheie primară sau index unic exact pe ele. PostgreSQL are nevoie de o asemenea constrângere ca să detecteze conflictul. Creează constrângerea sau indexul unic, ori folosește în ON CONFLICT coloanele care au deja unul.

Explicat de Tudor Andrei Dumitrescu, Senior Software Developer, fondatorul Academiei ProgramatorilorActualizat la

Ce înseamnă

INSERT ... ON CONFLICT (cols) DO ... se bazează pe un index unic care detectează conflictul. Lista de coloane (conflict target) trebuie să corespundă exact unui index unic sau unei constrângeri: aceleași coloane, în orice ordine, iar pentru indecși parțiali aceeași condiție WHERE. Dacă nu există, PostgreSQL nu poate ști ce înseamnă „conflict” și dă această eroare.

Cauze tipice: coloana are doar un index obișnuit, nu unic; unicitatea e pe (client_id, produs_id), iar ON CONFLICT folosește doar client_id; un index unic pe o expresie (lower(email)), iar ON CONFLICT (email) nu o repetă. Soluția este să adaugi constrângerea care exprimă regula reală (ALTER TABLE ... ADD UNIQUE (...)) sau să scrii exact expresia indexului: ON CONFLICT (lower(email)).

De ce apare: cauzele frecvente

1Coloana nu are constrângere unică

Greșit
SQL
INSERT INTO stoc_zilnic VALUES ('2025-03-14', 1, 5)
ON CONFLICT (zi, produs_id) DO UPDATE SET cantitate = EXCLUDED.cantitate;
Corect
SQL
ALTER TABLE stoc_zilnic ADD UNIQUE (zi, produs_id);
INSERT INTO stoc_zilnic VALUES ('2025-03-14', 1, 5)
ON CONFLICT (zi, produs_id) DO UPDATE SET cantitate = EXCLUDED.cantitate;

Constrângerea unică definește conflictul.

2Index unic pe expresie

Greșit
SQL
CREATE UNIQUE INDEX ON clienti_noi (lower(email));
INSERT ... ON CONFLICT (email) DO NOTHING;
Corect
SQL
INSERT ... ON CONFLICT (lower(email)) DO NOTHING;

Ținta conflictului trebuie să repete expresia indexului.

3Doar o parte din coloanele cheii

Greșit
SQL
ON CONFLICT (client_id) DO NOTHING  -- unicitate pe (client_id, produs_id)
Corect
SQL
ON CONFLICT (client_id, produs_id) DO NOTHING

Coloanele trebuie să fie exact cele ale constrângerii.

Repară tu

Repară eroarea, direct în pagină

Tabelul stoc_zilnic păstrează câte un rând pe zi și produs. Upsert-ul care actualizează cantitatea dă there is no unique or exclusion constraint matching the ON CONFLICT specification. Adaugă constrângerea unică pe (zi, produs_id), rulează upsert-ul și afișează rândurile.

Codul care dă eroarea
SQL
INSERT INTO stoc_zilnic VALUES ('2025-03-14', 1, 7)
ON CONFLICT (zi, produs_id) DO UPDATE SET cantitate = EXCLUDED.cantitate;
SELECT * FROM stoc_zilnic;
După reparație, programul afișează
ALTER TABLE
INSERT 0 1
     zi     | produs_id | cantitate
------------+-----------+-----------
 2025-03-14 |         1 |         7
(1 rând)
Indiciu

ALTER TABLE stoc_zilnic ADD UNIQUE (zi, produs_id)

Cum o eviți pe viitor

  • Definește constrângerile unice care exprimă regulile de business înainte să scrii upsert-uri.
  • Folosește în ON CONFLICT exact aceleași coloane sau expresii ca indexul unic.
  • Poți numi direct constrângerea: ON CONFLICT ON CONSTRAINT stoc_zilnic_zi_produs_id_key.
  • Verifică indecșii existenți cu \d tabel înainte să scrii ținta conflictului.

Întrebări frecvente

ON CONFLICT DO NOTHING fără coloane are nevoie de constrângere?

Nu: ON CONFLICT DO NOTHING fără țintă ignoră conflictul cu orice constrângere unică. DO UPDATE cere însă ținta.

MERGE e o alternativă?

Da, MERGE nu cere index unic, dar nu e sigur la inserări simultane: două sesiuni pot insera amândouă. Pentru upsert concurent, ON CONFLICT rămâne alegerea corectă.

Erori înrudite

← Toate erorile PostgreSQL

Tudor Andrei Dumitrescu
Cine a explicat eroarea

Tudor Andrei Dumitrescu

Senior Software Developer · fondatorul Academiei Programatorilor

LinkedIn
  1. 2019 Junior JavaCognizant Softvision
  2. 2021 Mid JavaCognizant Softvision
  3. 2022 Team LeaderEndava
  4. 2023 Senior Software DeveloperUniCredit
  5. Acum Senior Software DeveloperHCLTech
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu
Certificat de formator autorizatMinisterul Muncii și Ministerul Educației · 2022
Certificat de absolvire Instructor / Preparator formare, Tudor Andrei Dumitrescu

Certificat de formator autorizat · Ministerul Muncii și Ministerul Educației · 2022

Din 2020 construiește Academia Programatorilor, iar din 2026 și JoburiIT.ro. Fiecare eroare de aici a fost reprodusă în editorul nostru: codul greșit chiar dă mesajul din titlu, iar reparația chiar funcționează.

Învață PostgreSQL de la zero, cu exerciții la fiecare lecție

Curs PostgreSQL: lecții scurte, fiecare cu un exercițiu verificat automat, direct în browser. Primele 10 lecții sunt gratuite.