نشر مخطّطات وأدوات ربط Data Connect وإدارتها

تتضمّن Firebase Data Connect الخدمة ثلاثة مكوّنات رئيسية:

  • قاعدة بيانات أساسية في PostgreSQL مع مخطط SQL خاص بها
  • Data Connect مخطط تطبيق (يتم تعريفه في ملفات .gql)
  • عدد من الموصلات (يتم تعريفها في ملفات .gql، ويتم ضبطها في ملفات connector.yaml)

مخطط SQL هو مصدر البيانات الموثوق، والمخطط هو الطريقة التي يمكن أن ترى بها أدوات الربط هذه البيانات، وتحدّد أدوات الربط واجهات برمجة التطبيقات التي يمكن أن يستخدمها عملاؤك للوصول إلى هذه البيانات.Data Connect

عند نشر خدمة Data Connect باستخدام واجهة سطر الأوامر، عليك نقل مخطط SQL، ثم تعديل مخطط Data Connect، ثم تعديل كل موصِّلاتك.

مفاهيم مهمة حول النشر

لفهم عملية النشر بشكل كامل، من المهم التعرّف على المفاهيم الأساسية حول المخططات والموصلات.

عمليات نشر المخططات

يؤثر نشر مخطّط Data Connect في مخطّط SQL لقاعدة بيانات Cloud SQL. تساعدك Data Connect في نقل المخططات أثناء عملية النشر، سواء كنت تعمل مع قاعدة بيانات جديدة أو تحتاج إلى تعديل قاعدة بيانات حالية بدون فقدان البيانات.

تتضمّن عمليات نقل البيانات في مخطط Data Connect وضعَين مختلفَين للتحقّق من صحة المخطط، هما: الوضع الصارم والوضع المتوافق.

  • يتطلّب التحقّق من الصحة في الوضع الصارم أن يتطابق مخطّط قاعدة البيانات تمامًا مع مخطّط التطبيق قبل أن يتم تعديل مخطّط التطبيق. سيتم حذف أي جداول أو أعمدة غير مستخدَمة في مخطط Data Connect من قاعدة البيانات.

  • يتطلّب التحقّق من صحة وضع التوافق أن يكون مخطط قاعدة البيانات متوافقًا مع مخطط التطبيق قبل أن يتم تحديث مخطط التطبيق، وأي تغييرات إضافية تؤدي إلى حذف المخططات أو الجداول أو الأعمدة تكون اختيارية.

    يعني ذلك أنّ عمليات نقل البيانات في المخطط تؤثّر فقط في الجداول والأعمدة المشار إليها في مخطط تطبيقك. تبقى العناصر في قاعدة البيانات التي لا يستخدمها مخطط التطبيق بدون تعديل. لذلك، بعد النشر، قد تحتوي قاعدة البيانات على ما يلي:

    • المخططات
    • الجداول
    • الأعمدة

عمليات نشر الموصلات

لا يتم إرسال طلبات البحث والتعديلات في Data Connect من خلال رمز العميل، ويتم تنفيذها على الخادم. بدلاً من ذلك، عند نشر هذه العمليات، يتم تخزينها على الخادم، مثل Cloud Functions.Data Connect وهذا يعني أنّ عملية النشر قد تؤدي إلى حدوث مشاكل للمستخدمين الحاليين.

تدمج أداة Data Connect تحليل التغييرات غير المتوافقة في تحديثات الموصلات مع واجهة سطر الأوامر Firebase.

تحلّل واجهة سطر الأوامر التغييرات التي تطرأ على كل أداة ربط مقارنةً بالمخطط الخاص بك، وتصدر مجموعة من رسائل التقييم بشأن التغييرات التي تطرأ على أداة الربط والتي قد تغيّر سلوك العميل (الرسائل هي على مستوى التحذير) أو قد تؤدي إلى حدوث أخطاء أو ستؤدي إلى حدوث أخطاء (الرسائل هي على مستوى الخطأ) في الإصدارات السابقة من رمز العميل.

على سبيل المثال:

  • تشمل تغييرات أداة الربط التي قد تؤدي إلى تغيير سلوك العميل إزالة حقل قابل للتصغير من طلب بحث بدون إضافة تعليق توضيحي لمخطط @retired.
  • تشمل تغييرات الموصل التي قد تؤدي إلى حدوث مشاكل في العملاء أو ستؤدي إلى ذلك تغيير متغيّر عملية قابل للقيم الفارغة إلى متغيّر غير قابل للقيم الفارغة بدون قيمة تلقائية، أو تغيير نوع بيانات حقل إلى نوع غير متوافق (مثل String إلى Int).

تتوفّر قائمة أكثر شمولاً بسيناريوهات مستوى التحذير ومستوى الخطأ في دليل مرجع واجهة سطر الأوامر.

اتّباع سير عمل النشر

يمكنك العمل على مشروع Data Connect في دليل مشروع محلي وفي وحدة تحكّم Firebase.

يتضمّن مسار النشر المقترَح ما يلي:

  1. إدراج المخططات والموصلات المنشورة حاليًا باستخدام firebase dataconnect:services:list
  2. إدارة أي تعديلات على المخطط
    1. تحقَّق من اختلافات مخطط SQL بين قاعدة بيانات Cloud SQL ومخطط Data Connect المحلي باستخدام firebase dataconnect:sql:diff.
    2. إذا لزم الأمر، نفِّذ عملية نقل مخطّط SQL باستخدام dataconnect:sql:migrate.
  3. تنفيذ عمليات نشر المخطط والربط من خلال تشغيل firebase deploy، إما للمخطط فقط أو للموصلات فقط أو لمجموعات من الموارد

نشر موارد Data Connect وإدارتها

من المستحسن التحقّق من موارد الإنتاج قبل إجراء عمليات النشر.

firebase dataconnect:services:list

عند العمل في دليل مشروع محلي، ستستخدم عادةً الأمر firebase deploy لنشر المخطط والموصلات في مرحلة الإنتاج، مع تلقّي ملاحظات تفاعلية.

باستخدام أي أمر deploy، تتيح لك العلامة --only dataconnect فصل عمليات النشر Data Connect عن المنتجات الأخرى في مشروعك.

النشر العادي

firebase deploy --only dataconnect

في عملية النشر العادية هذه، تحاول واجهة سطر الأوامر Firebase نشر المخطط والموصلات.

يتحقّق من أنّ المخطط الجديد لا يؤدي إلى تعطيل أي موصّلات حالية. اتّبِع أفضل الممارسات عند إجراء تغييرات غير متوافقة مع الإصدارات السابقة.

ويتحقّق أيضًا من أنّه تم نقل مخطّط SQL قبل تعديل مخطّط Data Connect. إذا لم يكن الأمر كذلك، سيطلب منك تلقائيًا اتّباع أي خطوات ضرورية لنقل المخططات.

--force نشر العلامة

firebase deploy --only dataconnect --force

إذا لم تكن عمليات التحقّق من صحة الموصل أو مخطط SQL مهمة، يمكنك إعادة تشغيل الأمر مع --force لتجاهلها.

لا يزال أمر النشر --force يتحقّق مما إذا كان مخطط SQL يطابق مخطط Data Connect، ويحذّر من عدم التوافق، ويطلب منك اتخاذ إجراء.

نشر الموارد المحدّدة

لإجراء عملية نشر مع تحكّم أكثر دقة، استخدِم العلامة --only مع الوسيط serviceId. لنشر تغييرات المخطط فقط لخدمة معيّنة، اتّبِع الخطوات التالية:

firebase deploy --only dataconnect:serviceId:schema

يمكنك أيضًا نشر جميع الموارد لموصّل وخدمة محدّدين.

firebase deploy --only dataconnect:serviceId:connectorId

أخيرًا، يمكنك نشر المخطط وجميع أدوات الربط لخدمة واحدة.

firebase deploy --only dataconnect:serviceId

التراجع عن عملية نشر

لتنفيذ عملية التراجع يدويًا، عليك استخراج نسخة سابقة من الرمز البرمجي ونشرها. إذا تضمّن النشر الأصلي تغييرات غير متوافقة تؤدي إلى فقدان البيانات، قد لا تتمكّن من استرداد أي بيانات تم حذفها بالكامل.

نقل مخططات قواعد البيانات

إذا كنت تصمّم نماذج أولية بسرعة وتجرّب المخططات وتعرف أنّ تغييرات المخطط ستؤدي إلى فقدان البيانات، يمكنك التخطيط لاستخدام أدوات Data Connect للتحقّق من التغييرات والإشراف على طريقة تنفيذ التعديلات.

مقارنة التغييرات في مخطّط SQL

يمكنك التحقّق من التغييرات من خلال:

firebase dataconnect:sql:diff

يمكنك تمرير قائمة مفصولة بفواصل للخدمات.

يقارن الأمر المخطط المحلي لخدمة ما بالمخطط الحالي لقاعدة بيانات Cloud SQL ذات الصلة. إذا كان هناك اختلاف، سيتم عرض أوامر SQL التي سيتم تنفيذها لإصلاح هذا الاختلاف

تطبيق التغييرات

عندما تكون راضيًا عن التغييرات وجاهزًا لنشرها في مثيل Cloud SQL الخاص بالمخطط، نفِّذ الأمر firebase dataconnect:sql:migrate. سيُطلب منك الموافقة على التغييرات.

firebase dataconnect:sql:migrate [serviceId]

في البيئات التفاعلية، يتم عرض عبارات نقل بيانات SQL ومطالبات الإجراءات.

نقل البيانات في الوضع المتشدد أو وضع التوافق

في مشروع جديد تمامًا، يتم تطبيق وضع التحقّق من صحة المخطط التلقائي. يتمثل سلوك الأمر migrate في تطبيق جميع تغييرات مخطط قاعدة البيانات المطلوبة من خلال مخطط التطبيق، ثم مطالبتك بالموافقة على العمليات الاختيارية التي تسقط المخططات أو الجداول أو الأعمدة لفرض تطابق مخطط قاعدة البيانات مع مخطط التطبيق تمامًا.

يمكنك تعديل هذا السلوك من خلال تعديل ملف dataconnect.yaml. أزِل التعليق من المفتاح schemaValidation، وأضِف تعريفًا إلى COMPATIBLE حتى يتم تطبيق التغييرات المطلوبة فقط في عمليات نقل البيانات.

schemaValidation: "COMPATIBLE"

أو اضبط السلوك على STRICT ليتم تطبيق جميع تغييرات المخطط ويتم فرض تطابق مخطط قاعدة البيانات مع مخطط التطبيق.

schemaValidation: "STRICT"

يمكنك الاطّلاع على مرجع واجهة سطر الأوامر Data Connect لمزيد من المعلومات.

تعديل الموصِّلات

عند تشغيل firebase deploy، تبدأ واجهة سطر الأوامر في تحديث الموصلات السارية وإصدار رسائل التقييم السارية على مستوى التحذير (قد يؤثر ذلك في سلوك العميل) وعلى مستوى التغيير غير المتوافق (قد يؤدي ذلك إلى حدوث مشاكل أو سيؤدي بالتأكيد إلى حدوث مشاكل).

إدارة تحديثات الموصل باستخدام واجهة سطر الأوامر

يختلف سلوك واجهة سطر الأوامر قليلاً في وضع التفاعل ووضع عدم التفاعل.

وكما هو متوقّع، في الوضع التفاعلي، تطلب منك واجهة سطر الأوامر قبول جميع الرسائل. يمكنك تجاهل عملية نشر الموصل وفرضها باستخدام العلامة --force.

# Prompts for acceptance for any warning-level or breaking-level changes prior
# to deploying connectors.
firebase deploy --only dataconnect
# Will deploy connectors without prompting.
firebase deploy --only dataconnect --force

في الوضع غير التفاعلي، ستنشر واجهة سطر الأوامر الموصل طالما لم تكن هناك تقييمات على مستوى التوقف. وفي حال عدم اتّخاذ أي إجراء، سيتم إيقاف البرنامج النصي مع سجلّ بالتغييرات غير المتوافقة. يمكنك إلغاء عملية النشر وتفعيلها من خلال ضبط العلامة --force.

# Will deploy connectors with warning-level changes. If any breaking changes
# are present, the deploy will fail and output any breaking changes
firebase deploy --only dataconnect --non-interactive
# Will deploy the connectors from the previous step, if the same issues are present.
firebase deploy --only dataconnect --non-interactive --force

لمزيد من المعلومات، اطّلِع على دليل مرجع واجهة سطر الأوامر.

أفضل الممارسات لإدارة المخططات والموصلات

تنصح Firebase باتّباع بعض الممارسات في Data Connectمشاريعك.

الحدّ من التغييرات التي قد تؤدي إلى عطل

  • تنصح Firebase بالاحتفاظ بملفات مخطط Data Connect وملفات الموصل في نظام التحكّم بالمصادر.
  • تجنَّب إجراء تغييرات غير متوافقة قدر الإمكان. في ما يلي بعض الأمثلة الشائعة على التغييرات غير المتوافقة:
    • إزالة حقل من المخطط
    • تحويل حقل يقبل القيم الخالية في المخطط إلى حقل لا يقبل القيم الخالية (أي Int -> Int!)
    • إعادة تسمية حقل في المخطط
  • إذا كنت بحاجة إلى إزالة حقل من المخطط، ننصحك بتقسيمه إلى بضع عمليات نشر للحدّ من التأثير:
    • أولاً، أزِل أي إشارات إلى الحقل في الموصلات، ثم نفِّذ التغيير.
    • بعد ذلك، حدِّث تطبيقاتك لاستخدام حِزم SDK التي تم إنشاؤها حديثًا.
    • أخيرًا، أزِل الحقل في ملف مخطط .gql، وانقل مخطط SQL، ثم نفِّذ عملية النشر مرة أخرى.

استخدام الوضع الصارم عند العمل مع قواعد بيانات جديدة

إذا كنت تستخدم Data Connect مع قاعدة بيانات جديدة وتعمل بنشاط على تطوير مخطط تطبيقك، وتريد التأكّد من أنّ مخطط قاعدة البيانات يتماشى تمامًا مع مخطط تطبيقك، يمكنك تحديد schemaValidation: "STRICT" في dataconnect.yaml.

سيضمن ذلك تطبيق التغييرات الاختيارية أيضًا.

استخدام وضع التوافق عندما تتوفّر بيانات إنتاج في قاعدة البيانات

إذا كنت بصدد إجراء تغييرات على قاعدة بيانات تحتوي على بيانات إنتاج، ننصحك بتنفيذ عمليات نقل المخطط في وضع التوافق لضمان عدم حذف البيانات الحالية. يمكنك تحديد schemaValidation: "COMPATIBLE" في dataconnect.yaml.

في وضع التوافق، يتم تطبيق تغييرات نقل المخطط المطلوبة فقط على قاعدة البيانات.

  • تُعدّ DROP SCHEMA وDROP TABLE وDROP COLUMN عبارات اختيارية ولن يتم إنشاؤها لخطتك، حتى إذا كان مخطط قاعدة البيانات يحتوي على مخططات أو جداول أو أعمدة غير محدّدة في مخطط التطبيق.
  • إذا كان جدول قاعدة البيانات يحتوي على عمود غير فارغ غير مضمّن في مخطط التطبيق، ستتم إزالة قيد NOT NULL، حتى يمكن مواصلة إضافة البيانات إلى الجدول باستخدام أدوات الربط المحدّدة.

ما هي الخطوات التالية؟