مكتبات الجهات الخارجية

صفحة تصف استخدام ClickHouse لمكتبات الجهات الخارجية وكيفية إضافة مكتبات الجهات الخارجية وصيانتها.

يستخدم ClickHouse مكتبات الجهات الخارجية لأغراض مختلفة، مثل الاتصال بقواعد بيانات أخرى، أو فك ترميز البيانات وترميزها أثناء تحميلها من القرص أو حفظها إليه، أو تنفيذ بعض دوال SQL المتخصصة. ولضمان عدم الاعتماد على المكتبات المتوفرة في النظام المستهدف، تُستورد كل مكتبة من مكتبات الجهات الخارجية كوحدة Git فرعية ضمن الشجرة المصدرية لـ ClickHouse، ثم تُجمَّع وتُربط مع ClickHouse. يمكن الحصول على قائمة بمكتبات الجهات الخارجية وتراخيصها باستخدام الاستعلام التالي:

SELECT library_name, license_type, license_path FROM system.licenses ORDER BY library_name COLLATE 'en';

لاحظ أن المكتبات المدرجة هي الموجودة في الدليل contrib/ ضمن مستودع ClickHouse. واستنادًا إلى خيارات البناء، قد لا تكون بعض هذه المكتبات قد جرى تجميعها، وبالتالي قد لا تتوفر وظائفها في وقت التشغيل.

مثال

​

إضافة وصيانة مكتبات الجهات الخارجية

يجب أن تكون كل مكتبة من مكتبات الجهات الخارجية موجودة في دليل مخصّص ضمن الدليل contrib/ في مستودع ClickHouse. تجنّب وضع نسخ من الشيفرة الخارجية مباشرةً داخل دليل المكتبة. وبدلًا من ذلك، أنشئ وحدة Git فرعية لسحب الشيفرة الخارجية من مستودع upstream خارجي.

جميع الوحدات الفرعية التي يستخدمها ClickHouse مُدرجة في الملف .gitmodule.

• إذا كان يمكن استخدام المكتبة كما هي (وهذه هي الحالة الافتراضية)، فيمكنك الإشارة مباشرةً إلى مستودع upstream.
• إذا كانت المكتبة تحتاج إلى ترقيعات، فأنشئ fork من مستودع upstream ضمن منظمة ClickHouse على GitHub.

في الحالة الثانية، نهدف إلى عزل الترقيعات المخصّصة قدر الإمكان عن commits الخاصة بـ upstream. ولهذا الغرض، أنشئ فرعًا ببادئة ClickHouse/ انطلاقًا من الفرع أو tag الذي تريد دمجه، مثل ClickHouse/2024_2 (للفرع 2024_2) أو ClickHouse/release/vX.Y.Z (للـ tag release/vX.Y.Z). تجنّب تتبّع فروع التطوير في upstream مثل master/ main / dev (أي الفروع ذات البادئة ClickHouse/master / ClickHouse/main / ClickHouse/dev في مستودع fork). فهذه الفروع أهداف متحرّكة، مما يجعل ضبط الإصدارات على نحو صحيح أكثر صعوبة. وتضمن “الفروع ذات البادئة” أن عمليات السحب من مستودع upstream إلى fork ستترك فروع ClickHouse/ المخصّصة دون تأثر. يجب أن تتتبّع الوحدات الفرعية في contrib/ فقط فروع ClickHouse/ في مستودعات الجهات الخارجية المتفرعة.

لا تُطبَّق الترقيعات إلا على فروع ClickHouse/ الخاصة بالمكتبات الخارجية.

هناك طريقتان للقيام بذلك:

• قد ترغب في إنشاء إصلاح جديد على فرع ذي بادئة ClickHouse/ في المستودع المتفرّع، مثل إصلاح sanitizer. في هذه الحالة، ادفع الإصلاح كفرع ذي بادئة ClickHouse/، مثل ClickHouse/fix-sanitizer-disaster. ثم أنشئ PR من الفرع الجديد إلى فرع التتبع المخصّص، مثل ClickHouse/2024_2 <-- ClickHouse/fix-sanitizer-disaster، ثم ادمج PR.
• قد تقوم بتحديث الوحدة الفرعية وتحتاج إلى إعادة تطبيق ترقيعات سابقة. في هذه الحالة، تكون إعادة إنشاء PRs القديمة مبالغة. وبدلًا من ذلك، ما عليك سوى تنفيذ cherry-pick للـ commits الأقدم إلى فرع ClickHouse/ الجديد (المقابل للإصدار الجديد). ولا تتردد في Squash commits الخاصة بالـ PRs التي كانت تحتوي على عدة commits. وفي أفضل الحالات، نكون قد ساهمنا بالترقيعات المخصّصة مرة أخرى في upstream، ويمكننا عندها الاستغناء عن الترقيعات في الإصدار الجديد.

بمجرد تحديث الوحدة الفرعية، حدّث مرجع الوحدة الفرعية في ClickHouse ليشير إلى hash الجديد في fork.

أنشئ ترقيعات لمكتبات الجهات الخارجية مع وضع المستودع الرسمي في الاعتبار، وفكّر في المساهمة بالترقيع مرة أخرى في مستودع upstream. يضمن ذلك أن يستفيد الآخرون أيضًا من الترقيع، وألا يشكّل عبئًا صيانياً على فريق ClickHouse.