نشر وإدارة مخططات وموصلات 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 تدمج تحليل التغييرات التي قد تؤثر في المستخدمين في تحديثات الموصِّلات ضمن Firebase CLI.

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

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

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

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

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

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

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

  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

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

تطبيق التغييرات

عندما تكونون راضين ومستعدين لنشر التغييرات على مثيل المخطط Cloud SQL ، نفِّذوا الأمر firebase dataconnect:sql:migrate سيُطلب منكم الموافقة على التغييرات.

firebase dataconnect:sql:migrate [serviceId]

في البيئات التفاعلية، يتم عرض عبارات نقل بيانات SQL وطلبات اتّخاذ الإجراءات.

نقل البيانات في الوضع المتشدد أو الوضع المتوافق

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

يمكنكم تعديل هذا السلوك من خلال تعديل ملف dataconnect.yaml. أزيلوا التعليق عن المفتاح schemaValidation، وأعلنوا عن COMPATIBLE بحيث لا يتم تطبيق سوى التغييرات المطلوبة في عمليات النقل.

schemaValidation: "COMPATIBLE"

أو اضبطوا السلوك على STRICT بحيث يتم تطبيق جميع تغييرات المخطط وإجبار مخطط قاعدة البيانات على التطابق مع مخطط التطبيق.

schemaValidation: "STRICT"

يمكنكم الاطّلاع على مرجع SQL Connect CLI لمزيد من المعلومات.

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

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

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