Çfarë është UPSERT (INSERT ON CONFLICT)?

Question

Accepted Answer

**UPSERT** nënkupton "insert, ose update nëse ekziston tashmë." PostgreSQL e zbaton këtë me **`INSERT ... ON CONFLICT`** — fut një rresht, por nëse do të shkelte një constraint unik, në vend të kësaj përditëso rreshtin ekzistues (ose mos bëj asgjë). Ai zgjidh nevojën e zakonshme "insert-ose-update" atomikisht.

## Problemi që UPSERT zgjidh

```text
You want to insert a row, but it might already exist (by a unique key):
  ❌ a plain INSERT fails with a unique-violation error if it exists
  ❌ check-then-insert (SELECT, then INSERT or UPDATE) has a RACE CONDITION
     (another transaction could insert between your check and insert)
→ ON CONFLICT does it atomically in ONE statement (no race condition)
```

## ON CONFLICT DO UPDATE — insert ose update

```sql
INSERT INTO users (email, name, login_count)
VALUES ('ann@x.com', 'Ann', 1)
ON CONFLICT (email)                  -- if a row with this email already exists...
DO UPDATE SET                        -- ...UPDATE it instead
  name = EXCLUDED.name,              -- EXCLUDED = the values you tried to insert
  login_count = users.login_count + 1;  -- can reference the existing row too
```

Nëse futja do të konfliktonte në constraint-in unik `email`, Postgres përditëson rreshtin ekzistues në vend të kësaj. **`EXCLUDED`** i referohet vlerave që përpiqje të futesh, dhe mund të referencosh edhe rreshtin ekzistues (`users.login_count`) — duke mundësuar logjikën si rritja e një numëruesi.

## ON CONFLICT DO NOTHING — insert ose hiq

```sql
INSERT INTO users (email, name) VALUES ('ann@x.com', 'Ann')
ON CONFLICT (email) DO NOTHING;      -- if it exists, just skip (no error)
```

`DO NOTHING` heq në heshtje rreshtat konfliktues — i dobishëm për "fut nëse nuk është i pranishëm" pa gabime.

## Një përdorim i zakonshëm në praktikë: numëruesit dhe futjet idempotente

```sql
-- track page views — insert on first view, increment on subsequent
INSERT INTO page_views (page_id, views) VALUES (5, 1)
ON CONFLICT (page_id) DO UPDATE SET views = page_views.views + 1;
```

## Pse ka rëndësi

UPSERT (`INSERT ... ON CONFLICT`) është një veçori e rëndësishme dhe praktikisht e vlefshme e PostgreSQL-it që zgjidh shumë mirë nevojën e zakonshme "insert-ose-update" në mënyrë të **sigurt**, prandaj ta kuptohesh atë është i dobishëm për operacione të dhënash në botën reale.

Nevoja — futja e një rreshti që mund të ekzistojë tashmë (sipas një çelësi unik) — lind vazhdimisht (upsert i rekordeve, numëruesit, futjet idempotente, sinkronizimi i të dhënave), dhe alternativat naïve janë problematike: një INSERT i thjeshtë dështon me një gabim nëse rreshti ekziston, dhe qasja check-then-insert (SELECT pastaj INSERT-ose-UPDATE) ka një **condition garash** (një transaksion tjetër konkurent mund të futë mes kontrollit tuaj dhe futjes tuaj, duke shkaktuar gabime ose humbje përditësimesh). `ON CONFLICT` zgjidh këtë **atomikisht në një deklaratë të vetme** — duke eliminuar condition-in e garash, që është përfitimi i tij kryesor i saktësisë për aplikacionet konkurente.

Kuptimi i të dy formave — **`DO UPDATE`** (insert ose update, me `EXCLUDED` që referon vlerat e përpiqur dhe aftësia për të referencuar rreshtin ekzistues për logjikën si rritja e numëruesve) dhe **`DO NOTHING`** (insert ose hiq në heshtje) — mbulojnë modelet e zakonshme (upsert të rekordeve, futjet idempotente, mirëmbajtja e numëruesve/agreguese).

Meqë insert-ose-update është një operacion i shpeshtë dhe ta bësh atë saktësisht dhe me siguri (atomikisht, pa condition garash) ka rëndësi për integritetin e të dhënave në aplikacionet konkurente, kuptimi i UPSERT — çfarë zgjidh, përfitimi i atomicitetit/condition-it të garash, dhe format DO UPDATE/DO NOTHING — është njohuri e vlefshme, të shpesh-aplikuar PostgreSQL që ofron një zgjidhje të pastër dhe të sigurt për një nevojë të zakonshme që përndryshe është e diskreciopare për gabime, duke e bërë atë një veçori praktike dhe të rëndësishme për aplikacionet reale.