نشر وإدارة مخططات وموصلات SQL Connect

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

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

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

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

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

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

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

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

تتضمّن عمليات ترحيل مخطط SQL Connect وضعَين مختلفَين للتحقّق من صحة المخطط ، هما الوضع المتشدد والوضع المتوافق.

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

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

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

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

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

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

SQL Connect تدمج تحليل التغييرات التي قد تؤدي إلى حدوث مشاكل في تحديثات الموصِّلات في واجهة سطر الأوامر (CLI) Firebase.

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

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

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

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

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

يمكنكم العمل على مشروع SQL Connect في دليل مشروع على جهاز المستخدم وفي وحدة تحكّم Firebase

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

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

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

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

firebase dataconnect:services:list

عند العمل في دليل مشروع على جهاز المستخدم، ستستخدمون بشكلٍ عام الأمر firebase deploy لتفعيل المخطط والموصِّلات في مرحلة الإصدار العلني، مع تلقّي ملاحظات تفاعلية.

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

عملية النشر العادية

firebase deploy --only dataconnect

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

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

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

عملية النشر باستخدام العلامة --force

firebase deploy --only dataconnect --force

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

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

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

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

firebase deploy --only dataconnect:serviceId:schema

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

firebase deploy --only dataconnect:serviceId:connectorId

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

firebase deploy --only dataconnect:serviceId

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

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

ترحيل مخططات قاعدة البيانات

إذا كنتم تنشئون نماذج أولية بسرعة وتجرّبون المخططات وتعرفون أنّ تغييرات المخطط ستؤدي إلى حدوث مشاكل، يمكنكم التخطيط لاستخدام أدوات SQL 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"

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

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

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

إدارة تعديلات الموصِّلات باستخدام واجهة سطر الأوامر (CLI)

تختلف واجهة سطر الأوامر (CLI) قليلاً في الوضع التفاعلي والوضع غير التفاعلي.

كما هو متوقّع، في الوضع التفاعلي، تطلب منكم واجهة سطر الأوامر (CLI) قبول جميع الرسائل. يمكنكم إلغاء عملية نشر الموصِّل وفرضها باستخدام العلامة --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

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

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

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

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

الحدّ من التغييرات التي قد تؤدي إلى حدوث مشاكل

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

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

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

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

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

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

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

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

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

  • يتم تناول عملية نشر وإدارة رمز العميل الذي تطوّرونه باستخدام حِزم تطوير البرامج (SDK) التي تم إنشاؤها في الأدلة الخاصة بأنظمة Android وiOS والويب وFlutter.
  • لمزيد من المعلومات عن أدوات النشر، يمكنكم مراجعة مرجع واجهة سطر الأوامر (CLI) من SQL Connect و مرجع ملف إعداد SQL Connect.