الوثائق المرجعية لامتداد chdb

استيراد وتصدير البيانات من Postgres إلى مجموعة واسعة من تنسيقات البيانات ومخازن الكائنات.

​

المقدمة

توفّر هذه المكتبة امتدادات PostgreSQL لتنفيذ استعلامات chDB داخل Postgres، ولنسخ البيانات من وإلى مجموعة متنوعة من التنسيقات ومخازن الكائنات.

​

امتداد chdb

يُشغّل امتداد chdb استعلامات chDB. وتُنفّذ الدالة chdb_query() استعلامًا واحدًا. على سبيل المثال، هذا الاستعلام:

SELECT * FROM chdb_query($$
  SELECT * FROM s3('s3://datasets-documentation/my-test-bucket-768/some_prefix/some_file_1.csv')
$$) AS (id int, months int, days int);

المخرجات:

 id | months | days
----+--------+------
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
(3 rows)

راجع وثائق chdb لمزيد من التفاصيل.

​

وحدة chdb_hook

ترتبط وحدة chdb_hook بأمر COPY عبر خطاف لنسخ البيانات من أو إلى S3 أو GCS أو Azure Blob أو ملف أو عنوان URL عبر http. يحمّل هذا المثال السجلات من عدة ملفات CSV على S3 بأمر COPY واحد:

CREATE TABLE times (
    id     INT NOT NULL,
    months INT NOT NULL,
    days   INT NOT NULL
);

LOAD 'chdb_hook';
COPY times FROM 's3://datasets-documentation/my-test-bucket-768/{some,another}_prefix/some_file_{1..3}.csv';

بعد ذلك، يحتوي جدول times على السجلات الواردة من كل ملف تم تحميله:

# SELECT * FROM times;
 id | months | days
----+--------+------
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
  1 |      2 |    3
  3 |      2 |    1
  4 |      5 |    6
(18 rows)

يمكن أيضًا لعبارة CREATE TABLE أن تستمد أعمدتها وتُحمّل صفوفها من عنوان URL كهذا:

CREATE TABLE reviews () WITH (
    copy_from = 'https://datasets-documentation.s3.eu-west-3.amazonaws.com/amazon_reviews/amazon_reviews_2015.snappy.parquet'
);

راجع توثيق chdb_hook لمزيد من التفاصيل.

​

قياس أداء التنسيقات

يقارن benchmark أداء COPY في [chdb_hook] بأداء [aws_s3] و[pg_duckdb] و[pg_lake] لنحو مليون صف من NYC Taxi dataset بمجموعة متنوعة من التنسيقات.

من بين الامتدادات الأربعة، يقدّم chdb الأداء الأكثر ثباتًا. أما [pg_duckdb] و[pg_lake]، وكلاهما يعتمد على DuckDB، فيستغرقان ما يقارب ضعفين إلى ثلاثة أضعاف الوقت لاستيراد البيانات من CSV وJSON وParquet. ولا يقترب من أداء [chdb_hook] سوى [aws_s3]، لكنه يدعم مجموعة أضيق بكثير من تنسيقات البيانات:

الامتداد	الضغط	تنسيقات البيانات
aws_s3	لا يوجد	Text (TSV), CSV, Postgres Binary
pg_lake	gzip, zstd, snappy (Parquet فقط)	CSV, JSON, Parquet
pg_duckdb	gzip, zstd, snappy (Parquet فقط)	CSV, JSON, Parquet
chdb	gzip, zstd, lz4, bz2, snappy, brotli	TSV, CSV, JSON, BSON, Prometheus, Protobuf, Avro, Parquet, Arrow, XML, CapnProto, Markdown, MsgPack, ORC، والمزيد!

وتُظهر قياسات الأداء الإضافية ثباتًا نسبيًا في الأداء عند استيراد NYC Taxi dataset بمجموعة متنوعة من التنسيقات:

يستخدم قياس الأداء تنسيق JSONCompact لضمان التوافق مع الامتدادات الأخرى؛ أما تنسيقات JSON الأخرى، مثل JSONCompactEachRow، فأداؤها أقرب إلى أداء التنسيقات الأخرى.

​

المعمارية

يعتمد امتدادا chdb و chdb_hook على عملية chdb_helper لتنفيذ استعلامات chDB. وتُبقي هذه العملية المساعدة استهلاك chDB للموارد منفصلًا عن عملية Postgres الرئيسية، وهي ميزة مفيدة في سير عمل لا يُستخدم إلا من حين لآخر مثل تحميل البيانات من data lake.

                  +-------------+
                  |   helper    |
+----------+      |    app      |      +------+
| Postgres |      | +---------+ |      | chDB |
| Backend  |----->| |  chDB   | |----->| Data |
+----------+      | | Library | |      +------+
                  | +---------+ |
                  +-------------+

على خلاف worker الخلفي، لا يحتفظ المساعد بأي ذاكرة مشتركة خاصة بـ Postgres ولا تديره عملية postmaster. وهذا يعزل حالات الـ crash فلا تؤثر على Postgres. فالمساعد الذي يتوقف يؤدي إلى ظهور error في الـ backend الذي شغّله فقط، بينما تبقى بقية الـ sessions دون تأثر.

​

التبعيات

يتطلب امتداد chdb إصدار PostgreSQL 15 أو أحدث، ومكتبة chDB بالإصدار v26.7.0 أو أحدث (المتوفرة حاليًا لنظامي Linux وmacOS فقط). وأبسط طريقة لتثبيتها هي باستخدام البرنامج النصي لـ shell من lib.chdb.io:

curl -sL https://lib.chdb.io | bash

لتضمين chDB عبر التجميع الساكن (static) في التطبيق المساعد، عيّن المتغيرات التالية قبل تشغيل أوامر make الخاصة بـالتثبيت.

export BUNDLE_LIBCHDB=1 LIBCHDB_BUILD=static

سيقوم Makefile بتنزيل مكتبة libchdb الثابتة (static) وترجمتها داخل التطبيق.

على Linux، يمكنك أيضاً جعل عملية التثبيت تنزّل مكتبة libchdb الديناميكية وتثبّتها، وذلك بتعيين export BUNDLE_LIBCHDB=1 قبل تشغيل أوامر make الخاصة بـ التثبيت.

​

البناء من المصدر

لبناء chdb، نفّذ ما يلي فقط:

make
make installcheck
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 أيضًا. وإذا لزم الأمر، حدِّد لعملية البناء مكان العثور عليه:

env PG_CONFIG=/path/to/pg_config make && make installcheck && make install

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

chdb_helper.c:22:10: fatal error: 'chdb.h' file not found

عليك إما تثبيت chDB أو إخبار المصرّف بمكان العثور عليه. فعلى سبيل المثال، إذا ثبّتته عبر البرنامج النصي لـ shell من lib.chdb.io، فأشِر إلى /usr/local:

make CFLAGS=-I/usr/local/include \
     LDFLAGS=-L/usr/local/lib

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

ERROR:  must be owner of database regression

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

make installcheck PGUSER=postgres

لتثبيت الامتداد في custom prefix على PostgreSQL 18 أو أحدث، مرّر الـ argument المسمى prefix إلى install (وليس إلى أي أهداف make أخرى):

make install prefix=/usr/local/extras

ثم تأكد من تضمين الـ prefix في postgresql.conf parameters التالية:

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

​

المؤلفون

• David E. Wheeler
• serprex

​

حقوق النشر

حقوق النشر (c) 2026، ClickHouse