الوثائق المرجعية لـ pg_clickhouse

يُشغِّل [pg_clickhouse]، وهو إضافة open-source لـ PostgreSQL، استعلامات تحليلية على ClickHouse مباشرةً من PostgreSQL من دون إعادة كتابة أي SQL. وهو يدعم PostgreSQL 13 والإصدارات الأحدث وClickHouse v23 والإصدارات الأحدث.

بمجرد أن يبدأ ClickPipes في مزامنة البيانات إلى ClickHouse، استخدم pg_clickhouse لاستيراد import foreign tables بسرعة وسهولة إلى مخطط في PostgreSQL. ثم شغّل استعلامات PostgreSQL الحالية لديك على تلك الجداول، مع الحفاظ على قاعدة الشيفرة الحالية لديك مع تمرير التنفيذ إلى ClickHouse.

أسهل طريقة لتجربة pg_clickhouse هي استخدام [صورة Docker]، المبنية على صورة PostgreSQL القياسية لـ Docker والمرفقة بامتدادي pg_clickhouse وre2:

docker run --name pg_clickhouse -e POSTGRES_PASSWORD=my_pass \
       -d ghcr.io/clickhouse/pg_clickhouse:19
docker exec -it pg_clickhouse psql -U postgres -c 'CREATE EXTENSION pg_clickhouse'

راجع [الدليل التعليمي] لبدء استيراد جداول ClickHouse وتمرير الاستعلامات إلى المصدر.

يقارن هذا الجدول أداء استعلامات TPC-H بين جداول PostgreSQL العادية و pg_clickhouse المتصل بـ ClickHouse، وقد جرى تحميل كليهما بعامل scaling يساوي 1؛ وتشير العلامة ✔︎ إلى pushdown كامل ضمن فحص خارجي واحد، بينما تشير ✼ إلى pushdown كامل ضمن عدة فحوصات خارجية. أُجريت جميع الاختبارات على جهاز MacBook Pro M4 Max بذاكرة 36 غيغابايت.

تتضمن حزم التطوير الخاصة بـ PostgreSQL و curl كلاً من pg_config و curl-config ضمن المسار، لذا يُفترض أن تتمكن ببساطة من تشغيل make (أو gmake)، ثم make install، ثم تنفيذ CREATE EXTENSION pg_clickhouse في قاعدة البيانات.

راجع PostgreSQL Apt للاطّلاع على تفاصيل جلب الحزم من مستودع PostgreSQL Apt.

sudo apt install \
  postgresql-server-19 \
  libcurl4-openssl-dev \
  uuid-dev \
  libssl-dev \
  make \
  cmake \
  g++

sudo yum install \
  postgresql-server \
  libcurl-devel \
  libuuid-devel \
  openssl-libs \
  automake \
  cmake \
  gcc

راجع PostgreSQL Yum للاطلاع على تفاصيل الجلب من مستودع PostgreSQL Yum.

بعد استيفاء التبعيات المذكورة أعلاه، استخدم [عميل PGXN] (المتوفّر عبر Homebrew وApt وحزم Yum باسم pgxnclient) لتنزيل pg_clickhouse وتجميعه وتثبيته:

pgxn install pg_clickhouse

لتجميع مكتبة ClickHouse وتثبيتها وإضافة pg_clickhouse، شغّل:

make
sudo make install

إذا كانت على مضيفك عدة عمليات تثبيت لـ PostgreSQL، فقد تحتاج إلى تحديد الإصدار المناسب من pg_config:

export PG_CONFIG=/usr/lib/postgresql/18/bin/pg_config
make
sudo make install

إذا لم يكن curl-config موجودًا في المسار على الجهاز المضيف، يمكنك تحديد المسار بشكل صريح:

export CURL_CONFIG=/opt/homebrew/opt/curl/bin/curl-config
make
sudo make install

إذا واجهت خطأً مثل:

"Makefile", line 8: Need an operator

تحتاج إلى استخدام GNU make، وقد يكون مثبّتًا على نظامك باسم gmake:

gmake
gmake install
gmake installcheck

إذا واجهت خطأً مثل:

make: pg_config: Command not found

تأكد من أن pg_config مثبّت وموجود في متغير PATH. إذا كنت قد استخدمت نظام إدارة حزم مثل RPM لتثبيت PostgreSQL، فتأكد أيضًا من تثبيت حزمة -devel. وإذا لزم الأمر، فأخبر عملية البناء بمكان العثور عليه:

export PG_CONFIG=/path/to/pg_config
make
sudo make install

لتثبيت الإضافة ضمن بادئة مخصّصة على PostgreSQL 18 أو الإصدارات الأحدث، مرّر الوسيطة prefix إلى install (ولكن ليس إلى أي أهداف make أخرى):

sudo make install prefix=/usr/local/extras

ثم تأكد من تضمين البادئة في [معلمات postgresql.conf ] التالية:

extension_control_path = '/usr/local/extras/postgresql/share:$system'
dynamic_library_path   = '/usr/local/extras/postgresql/lib:$libdir'

لتشغيل مجموعة الاختبارات، بعد تثبيت الإضافة، نفِّذ

make installcheck

إذا صادفت خطأً مثل:

ERROR:  must be owner of database regression

عليك تشغيل مجموعة الاختبارات باستخدام مستخدم فائق الصلاحيات، مثل المستخدم فائق الصلاحيات الافتراضي "postgres":

make installcheck PGUSER=postgres

بمجرد تثبيت pg_clickhouse، يمكنك إضافته إلى إحدى قواعد البيانات عبر الاتصال كمستخدم فائق الصلاحيات ثم تنفيذ:

CREATE EXTENSION pg_clickhouse;

إذا كنت تريد تثبيت pg_clickhouse وجميع الكائنات الداعمة له ضمن مخطط محدد، فاستخدم عبارة SCHEMA لتحديد المخطط، كما يلي:

CREATE SCHEMA env;
CREATE EXTENSION pg_clickhouse SCHEMA env;

تتطلب إضافة pg_clickhouse PostgreSQL 13 أو إصدارًا أحدث، وlibcurl، وlibuuid. كما يتطلب بناء الإضافة مُصرّفًا للغتَي C وC++، وlibSSL، وGNU make، وCMake.

ينصبّ تركيزنا الأول حاليًا على استكمال تغطية pushdown لأعباء العمل التحليلية قبل إضافة ميزات DML. خريطة الطريق لدينا:

• الوصول إلى تخطيط أمثل للاستعلامات العشرة المتبقية من TPC-H التي لم يُطبَّق عليها pushdown
• اختبار pushdown لاستعلامات ClickBench وإصلاح مشكلاته
• دعم pushdown الشفاف لجميع الدوال التجميعية في PostgreSQL
• دعم pushdown الشفاف لجميع دوال PostgreSQL
• إتاحة إعدادات ClickHouse على مستوى الخادم وعلى مستوى الجلسة عبر CREATE SERVER وGUCs
• دعم جميع أنواع بيانات ClickHouse
• دعم عمليات DELETE وUPDATE خفيفة الوزن
• دعم الإدراج على دفعات عبر COPY
• إضافة دالة لتنفيذ أي استعلام ClickHouse وإرجاع نتائجه على شكل جداول
• إضافة دعم pushdown لاستعلامات UNION عندما تستعلم جميعها من قاعدة البيانات البعيدة

• David E. Wheeler
• serprex
• Josh Ventura
• Ildus Kurbangaliev
• Ibrar Ahmed

• حقوق النشر (c) 2025-2026، ClickHouse
• أجزاء من حقوق النشر (c) 2023-2025، Ildus Kurbangaliev
• أجزاء من حقوق النشر (c) 2019-2023، Adjust GmbH
• أجزاء من حقوق النشر (c) 2012-2019، PostgreSQL Global Development Group

[الاستعلام 1] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/1.sql [الاستعلام 2] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/2.sql [الاستعلام 3] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/3.sql [الاستعلام 4] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/4.sql [الاستعلام 5] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/5.sql [الاستعلام 6] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/6.sql [الاستعلام 7] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/7.sql [الاستعلام 8] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/8.sql [الاستعلام 9] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/9.sql [الاستعلام 10] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/10.sql [الاستعلام 11] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/11.sql [الاستعلام 12] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/12.sql [الاستعلام 13] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/13.sql [الاستعلام 14] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/14.sql [الاستعلام 15] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/15.sql [الاستعلام 16] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/16.sql [الاستعلام 17] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/17.sql [الاستعلام 18] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/18.sql [الاستعلام 19] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/19.sql [الاستعلام 20] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/20.sql [الاستعلام 21] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/21.sql [الاستعلام 22] https://github.com/ClickHouse/pg_clickhouse/blob/main/dev/tpch/queries/22.sql