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

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

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

يُعدّ مخطّط 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.

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

  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 باتّباع بعض الممارسات في Data Connect مشاريعك.

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

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

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

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

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

استخدام الوضع المتوافق عندما تكون لديك بيانات علنية في قاعدة بياناتك

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

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

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

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