تتيح لك ميزة Environment Diff مقارنة schemas قواعد بيانات بيئتين جنبًا إلى جنب. هذا مفيد لفهم تغييرات schema التي تم إجراؤها في فرع قبل دمجه مرة أخرى في الأصل، أو لتدقيق الاختلافات الهيكلية بين أي بيئتين.

---

كيفية عمل Diff

تحدد محرك المقارنة الاختلافات الهيكلية بين البيئات في ثلاث مراحل:

1. تحليل Schema: يفحص النظام كلاً من البيئة المصدر والهدف لفهم بنيتهما الكاملة — بما في ذلك الجداول والأعمدة والفهارس والقيود والعلاقات.
2. المقارنة: تتم مقارنة الهيكلين وفقًا لدلالات للأمام فقط (موضحة أدناه). يحدد المحرك بالضبط التغييرات من البيئة المصدر الناقصة في الهدف.
3. توليد الترحيل: لكل تغيير مكتشف، يولد النظام تلقائيًا أوامر SQL المقابلة المطلوبة لتطبيق هذا التغيير على البيئة المستهدفة بأمان.

---

دلالات Diff للأمام فقط

يستخدم محرك diff دلالات للأمام فقط. هذا يعني:

• كائنات موجودة في المصدر وليست في الهدف → تظهر كـ CREATED (يجب إنشاؤها في الهدف)
• كائنات موجودة في كليهما → تتم مقارنتها حقلًا بحقل، وتظهر الاختلافات كتعديلات
• كائنات موجودة فقط في الهدف → لا تظهر كـ DROPPED

هذا قرار تصميم مهم. إذا كانت جدولاً موجودًا فقط في البيئة المستهدفة، فلم يكن موجودًا أبدًا في المصدر. عرضه كـ TABLE_DROPPED سيكون مضللاً لأن عملية drop لم تُنفذ أبدًا في المصدر. يركز diff حصريًا على التغييرات التي نشأت في المصدر ويجب نشرها إلى الهدف.

استثناء: بالنسبة لتغييرات مستوى العمود داخل الجداول الموجودة في كلا البيئتين، يتم اكتشاف COLUMN_DROPPED لأنها تمثل عملية إزالة عمود فعلية تم تنفيذها في المصدر.

---

أنواع التغيير

يكتشف محرك diff الفئات التالية من تغييرات schema:

نوع التغيير	الوصف	Breaking
TABLE_CREATED	جدول موجود في المصدر وليس في الهدف	لا
COLUMN_ADDED	تمت إضافة عمود جديد إلى جدول في المصدر	لا
COLUMN_DROPPED	عمود موجود في الهدف وتمت إزالته في المصدر	نعم
COLUMN_TYPE_CHANGED	تم تعديل نوع بيانات العمود	يعتمد*
COLUMN_NULLABLE_CHANGED	تم تبديل قيد nullable للعمود	يعتمد
COLUMN_DEFAULT_CHANGED	تم تعديل القيمة الافتراضية للعمود	لا
INDEX_CREATED	تمت إضافة فهرس جديد	لا
INDEX_DROPPED	تمت إزالة فهرس	لا
ENUM_CREATED	نوع enum جديد موجود في المصدر وليس في الهدف	لا
ENUM_VALUE_ADDED	تمت إضافة قيمة جديدة إلى enum	لا
ENUM_VALUE_REMOVED	تمت إزالة قيمة من enum	نعم
VIEW_CREATED	view موجود في المصدر وليس في الهدف	لا
VIEW_MODIFIED	تم تغيير تعريف SQL للـ view	لا
RELATIONSHIP_ADDED	تمت إضافة علاقة مفتاح أجنبي جديدة	لا
RELATIONSHIP_DROPPED	تمت إزالة علاقة مفتاح أجنبي	نعم

* تضييق النوع (مثل text → varchar(50) أو int8 → int4) مصنف كـ breaking لأنه قد يسبب فقدان بيانات. توسيع النوع (مثل varchar → text) مصنف كآمن.

ملاحظة: لا يتم إنشاء TABLE_DROPPED وENUM_DROPPED وVIEW_DROPPED على المستوى الأعلى بواسطة diff للأمام فقط. الكائنات الموجودة فقط في الهدف لا تُعتبر “محذوفة” من منظور المصدر.

---

اختيار Cherry-Pick

يدعم عرض diff تطبيق التغييرات الانتقائي. يمكن للمستخدمين:

• تحديد أو إلغاء تحديد التغييرات الفردية باستخدام صناديق الاختيار
• تحديد أو إلغاء تحديد جميع التغييرات داخل مجموعة (مثل جميع التغييرات لجدول معين) باستخدام صندوق اختيار المجموعة
• التغييرات Breaking (التدميرية) غير محددة مسبقًا افتراضيًا — يجب على المستخدم الموافقة صراحةً

سيتم تضمين التغييرات المحددة فقط عند تطبيق merge.

---

GraphQL API

Query: environmentDiff

query EnvironmentDiff($input: EnvironmentDiffInput!) {
  environmentDiff(input: $input) {
    success
    message
    changes {
      changeType
      objectType
      objectName
      fieldName
      oldValue
      newValue
      isBreaking
      sql
    }
    summary {
      totalChanges
      breakingChanges
      addedTables
      droppedTables
      modifiedTables
    }
  }
}

Variables:

{
  "input": {
    "projectId": "f7e4a264-d659-4719-91e8-c2d74654e529",
    "sourceEnvironment": "master",
    "targetEnvironment": "staging"
  }
}

---

فهم مخرجات Diff

يمثل كل إدخال في مصفوفة changes تغيير schema واحد بالحقول التالية:

• changeType: أحد معرفات نوع التغيير المذكورة أعلاه.
• objectType: نوع كائن قاعدة البيانات المتأثر (table أو column أو index أو enum أو view أو relationship).
• objectName: اسم الكائن المتأثر (مثل اسم الجدول).
• fieldName: لتغييرات مستوى العمود، اسم العمود المحدد.
• oldValue / newValue: القيم قبل وبعد للتعديلات (مثل "varchar(255)" → "text").
• isBreaking: قيمة boolean تشير إلى ما إذا كان هذا التغيير قد يسبب فقدان بيانات أو كسر API.
• sql: عبارة DDL المُنشأة لتطبيق هذا التغيير.