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

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