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

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

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

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

  • تشمل تغييرات الموصّل التي قد تغيّر سلوك العميل إزالة حقل nullable من طلب بحث بدون تعليق توضيحي @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 CLI نشر المخطّط والموصّلات.

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

ويتحقّق أيضًا من أنّه سبق نقل مخطّط 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، بحيث يمكن مواصلة إضافة البيانات إلى الجدول باستخدام الموصّلات المحدّدة.

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