ما هو UPSERT (INSERT ON CONFLICT)؟

Question

Accepted Answer

**UPSERT** تعني "إدراج، أو تحديث إذا كانت موجودة بالفعل." تطبق PostgreSQL هذا باستخدام **`INSERT ... ON CONFLICT`** — إدراج صف، لكن إذا كان سينتهك قيد فريد، قم بتحديث الصف الموجود بدلاً من ذلك (أو لا تفعل شيئاً). يتعامل مع الحاجة الشائعة "إدراج-أو-تحديث" بشكل ذري.

## المشكلة التي يحلها UPSERT

```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 — إدراج أو تحديث

```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
```

إذا كان الإدراج سيتعارض على قيد فريد `email`، يقوم Postgres بتحديث الصف الموجود بدلاً من ذلك. **`EXCLUDED`** يشير إلى القيم التي حاولت إدراجها، ويمكنك أيضاً الإشارة إلى الصف الموجود (`users.login_count`) — مما يتيح منطق مثل زيادة عداد.

## ON CONFLICT DO NOTHING — إدراج أو تخطي

```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` يتخطى بصمت الصفوف المتعارضة — مفيد لـ "إدراج إذا لم تكن موجودة" دون أخطاء.

## حالة استخدام شائعة جداً: العدادات والإدراجات المعاد

```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;
```

## لماذا يهم

UPSERT (`INSERT ... ON CONFLICT`) هو ميزة PostgreSQL مهمة وقيمة عملياً تحل الحاجة الشائعة جداً "إدراج-أو-تحديث" بشكل نظيف و**آمن**، لذا فهم هذا مفيد للعمليات على البيانات في الحياة الواقعية.

الحاجة — إدراج صف قد يكون موجوداً بالفعل (حسب مفتاح فريد) — تظهر باستمرار (تحديث السجلات، العدادات، الإدراجات المعاد، مزامنة البيانات)، والبدائل الساذجة إشكالية: INSERT عادي يفشل مع خطأ إذا كان الصف موجوداً، والنهج الفحص-ثم-إدراج (SELECT ثم INSERT-أو-UPDATE) له **حالة تسابق** (معاملة متزامنة أخرى قد تدرج بين الفحص والإدراج لديك، مما يسبب أخطاء أو فقدان التحديثات). `ON CONFLICT` يحل هذا **بشكل ذري في بيان واحد** — مما يلغي حالة التسابق، وهي فائدة الصحة الرئيسية للتطبيقات المتزامنة.

فهم كلا النموذجين — **`DO UPDATE`** (إدراج أو تحديث، مع `EXCLUDED` يشير إلى القيم المحاولة والقدرة على الإشارة إلى الصف الموجود لمنطق مثل زيادة العدادات) و**`DO NOTHING`** (إدراج أو تخطي بصمت) — يغطي الأنماط الشائعة (تحديث السجلات، الإدراجات المعاد، الحفاظ على العدادات/التجميعات).

بما أن إدراج-أو-تحديث عملية متكررة وتنفيذها بشكل صحيح وآمن (بشكل ذري، بدون حالات تسابق) مهم لتكامل البيانات في التطبيقات المتزامنة، فهم UPSERT — ما الذي يحله، فائدة الذرية/حالة التسابق، ونماذج DO UPDATE/DO NOTHING — هو معرفة PostgreSQL قيمة وكثيرة التطبيق توفر حلاً نظيفاً وآمناً لحاجة شائعة تكون معرضة للأخطاء بخلاف ذلك، مما يجعلها ميزة عملية ومهمة للتطبيقات الحقيقية.