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

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

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

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

عند نشر خدمة SQL Connect باستخدام واجهة سطر الأوامر، عليك نقل مخطط SQL، ثم تعديل مخطط SQL Connect، ثم تعديل كل موصل من موصلاتك.

مفاهيم مهمة متعلقة بالنشر

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

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

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

تتضمّن عمليات نقل بيانات مخطط SQL Connect وضعَين مختلفَين للتحقّق من صحة المخطط: صارم ومتوافق.

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

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

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

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

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

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

تدمج SQL Connect تحليل التغييرات غير المتوافقة في تحديثات الموصلات في واجهة سطر الأوامر Firebase.

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

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

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

تتوفّر قائمة أكثر شمولاً بالسيناريوهات التي تتضمّن أخطاء تحذيرية وأخطاء فادحة في دليل مرجع واجهة سطر الأوامر.

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

يمكنك العمل على مشروع 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

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

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

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

--force نشر العلامة

firebase deploy --only dataconnect --force

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

لا يزال الأمر --force deploy يتحقّق مما إذا كان مخطط 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 التي سيتم تنفيذها لإصلاح هذا الاختلاف.

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

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

firebase dataconnect:sql:migrate [serviceId]

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

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

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

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

schemaValidation: "COMPATIBLE"

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

schemaValidation: "STRICT"

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

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

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

إدارة تحديثات الموصل باستخدام واجهة سطر الأوامر

يختلف سلوك واجهة سطر الأوامر قليلاً في وضع التفاعل ووضع عدم التفاعل.

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

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

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

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

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

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