نشر مخطّطات وأدوات ربط 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 اختيارية ولن يتم إنشاؤها لخطتك، حتى إذا كان مخطّط قاعدة البيانات يحتوي على مخطّطات أو جداول أو أعمدة غير محدّدة في مخطّط تطبيقك.
  • إذا كان جدول قاعدة البيانات يحتوي على عمود غير فارغ لم يتم تضمينه في مخطط التطبيق، ستتم إزالة قيد NOT NULL كي تستمر إضافة البيانات إلى الجدول باستخدام الموصِّلات المحددة.

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