> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> يسمح بتنفيذ استعلامات `SELECT` و`INSERT` على البيانات المخزنة على خادم PostgreSQL بعيد.

# postgresql

يسمح بتنفيذ استعلامات `SELECT` و`INSERT` على البيانات المخزنة على خادم PostgreSQL بعيد.

<div id="syntax">
  ## الصياغة
</div>

```sql theme={null}
postgresql({host:port, database, table, user, password[, schema, [, on_conflict]] | named_collection[, option=value [,..]]} [, SETTINGS name=value, ...])
```

<div id="arguments">
  ## الوسيطات
</div>

| الوسيطة       | الوصف                                                                                                                   |
| ------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `host:port`   | عنوان خادم PostgreSQL.                                                                                                  |
| `database`    | اسم قاعدة البيانات البعيدة.                                                                                             |
| `table`       | اسم الجدول البعيد، أو استعلام يُمرَّر إلى PostgreSQL كما هو (انظر [تمرير استعلام بدلًا من اسم جدول](#passing-a-query)). |
| `user`        | مستخدم PostgreSQL.                                                                                                      |
| `password`    | كلمة مرور المستخدم.                                                                                                     |
| `schema`      | مخطط جدول غير `default`. اختياري.                                                                                       |
| `on_conflict` | استراتيجية معالجة التعارض. مثال: `ON CONFLICT DO NOTHING`. اختياري.                                                     |

يمكن أيضًا تمرير الوسيطات باستخدام [المجموعات المسماة](/docs/ar/concepts/features/configuration/server-config/named-collections). في هذه الحالة، يجب تحديد `host` و`port` كلٌّ منهما على حدة. ويُنصح بهذا النهج في بيئة الإنتاج.

<div id="returned_value">
  ## القيمة المعادة
</div>

كائن جدول يحتوي على الأعمدة نفسها الموجودة في جدول PostgreSQL الأصلي.

<Note>
  في استعلام `INSERT`، وللتمييز بين دالة الجدول `postgresql(...)` واسم الجدول المصحوب بقائمة أسماء الأعمدة، يجب استخدام الكلمتين المفتاحيتين `FUNCTION` أو `TABLE FUNCTION`. راجع الأمثلة أدناه.
</Note>

<div id="settings">
  ## الإعدادات
</div>

يمكن تهيئة تجمّع الاتصالات المستخدم في دالة الجدول `postgresql` (وفي محرك الجدول [`PostgreSQL`](/docs/ar/reference/engines/table-engines/integrations/postgresql)) باستخدام عبارة `SETTINGS` في نهاية العبارة. وإذا لم يُحدَّد إعداد معيّن، فستُستخدم تلقائيًا قيمة إعداد `postgresql_*` المناظر له على مستوى الاستعلام. راجع قسم [الإعدادات](/docs/ar/reference/engines/table-engines/integrations/postgresql#settings) الخاص بمحرك الجدول للاطلاع على القائمة الكاملة لإعدادات `postgresql_connection_pool_*` و`postgresql_connection_attempt_timeout` وقيمها الافتراضية.

مثال:

```sql theme={null}
SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'password', SETTINGS postgresql_connection_pool_size = 32);
```

<div id="implementation-details">
  ## تفاصيل التنفيذ
</div>

تُنفَّذ استعلامات `SELECT` على جانب PostgreSQL بصيغة `COPY (SELECT ...) TO STDOUT` داخل معاملة PostgreSQL للقراءة فقط، مع إجراء commit بعد كل استعلام `SELECT`.

تُنفَّذ عبارات `WHERE` البسيطة مثل `=`, `!=`, `>`, `>=`, `<`, `<=` و`IN` على خادم PostgreSQL.

تُنفَّذ جميع عمليات الربط والتجميع والفرز وشروط `IN [ array ]` وقيد sampling الخاص بـ `LIMIT` في ClickHouse فقط بعد اكتمال الاستعلام على PostgreSQL.

<div id="passing-a-query">
  ## تمرير استعلام بدلاً من اسم جدول
</div>

بدلاً من اسم جدول، يمكن أن تكون الوسيطة الثالثة استعلام `SELECT` يُمرَّر إلى PostgreSQL كما هو. ويُستدل على بنية الجدول الناتج من نتيجة الاستعلام. ويمكن كتابة الاستعلام إما على شكل استعلام فرعي، أو بتغليفه داخل الدالة `query`:

```sql theme={null}
SELECT * FROM postgresql('localhost:5432', 'test', (SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0), 'user', 'password');
SELECT * FROM postgresql('localhost:5432', 'test', query('SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0'), 'user', 'password');
```

يفيد هذا في دفع عمليات الربط والتجميع أو أي معالجة أخرى إلى PostgreSQL. ويكون هذا الجدول للقراءة فقط: لا يُسمح بتنفيذ `INSERT` فيه. وتدعم البنية نفسها في محرك الجدول [`PostgreSQL`](/docs/ar/reference/engines/table-engines/integrations/postgresql).

<Note>
  يُحلِّل ClickHouse صيغة الاستعلام الفرعي `(SELECT ...)` ويُعيد تسلسلها بلهجة PostgreSQL (بما في ذلك وضع علامات الاقتباس لمعرّفات PostgreSQL وإفلات القيم الحرفية النصية) قبل إرسالها إلى الخادم. لذلك يجب أن تكون صالحة في ClickHouse SQL. ولتمرير بنية خاصة بـ PostgreSQL لا يحلّلها ClickHouse، استخدم الصيغة `query('...')`، إذ يُرسل نصها إلى PostgreSQL كما هو.

  إن أي `WHERE` أو `LIMIT` خارجي، أو aggregation، وما إلى ذلك، من استعلام ClickHouse المحيط **لا** يُدفَع إلى داخل الاستعلام المُمرَّر، بل يُطبَّق في ClickHouse بعد جلب نتيجة الاستعلام الكاملة. ولتقييد البيانات المقروءة من PostgreSQL، ضع شرط التصفية داخل الاستعلام المُمرَّر. ومع [`external_table_strict_query = 1`](/docs/ar/reference/settings/session-settings#external_table_strict_query)، يُرفَض أي شرط تصفية خارجي لا يمكن دفعه مع استثناء بدلًا من تطبيقه محليًا.
</Note>

تُنفَّذ استعلامات `INSERT` على جانب PostgreSQL بصيغة `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` داخل معاملة PostgreSQL، مع auto-commit بعد كل تعليمة `INSERT`.

تُحوَّل أنواع Array في PostgreSQL إلى مصفوفات في ClickHouse.

<Note>
  انتبه، في PostgreSQL قد يحتوي عمود من نوع بيانات المصفوفة مثل Integer\[] على مصفوفات بأبعاد مختلفة في صفوف مختلفة، لكن في ClickHouse لا يُسمح إلا بأن تكون المصفوفات متعددة الأبعاد ذات الأبعاد نفسها في جميع الصفوف.
</Note>

يدعم عدة نُسخ متماثلة يجب إدراجها باستخدام `|`. على سبيل المثال:

```sql theme={null}
SELECT name FROM postgresql(`postgres{1|2|3}:5432`, 'postgres_database', 'postgres_table', 'user', 'password');
```

أو

```sql theme={null}
SELECT name FROM postgresql(`postgres1:5431|postgres2:5432`, 'postgres_database', 'postgres_table', 'user', 'password');
```

يدعم تحديد أولوية النسخ المتماثلة لمصدر القاموس في PostgreSQL. وكلما كان الرقم في map أكبر، كانت الأولوية أقل. وأعلى أولوية هي `0`.

<div id="examples">
  ## أمثلة
</div>

جدول في PostgreSQL:

```text theme={null}
postgres=# CREATE TABLE "public"."test" (
"int_id" SERIAL,
"int_nullable" INT NULL DEFAULT NULL,
"float" FLOAT NOT NULL,
"str" VARCHAR(100) NOT NULL DEFAULT '',
"float_nullable" FLOAT NULL DEFAULT NULL,
PRIMARY KEY (int_id));

CREATE TABLE

postgres=# INSERT INTO test (int_id, str, "float") VALUES (1,'test',2);
INSERT 0 1

postgresql> SELECT * FROM test;
  int_id | int_nullable | float | str  | float_nullable
 --------+--------------+-------+------+----------------
       1 |              |     2 | test |
(1 row)
```

اختيار البيانات من ClickHouse باستخدام الوسيطات المباشرة:

```sql theme={null}
SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'password') WHERE str IN ('test');
```

أو باستخدام [المجموعات المُسمّاة](/docs/ar/concepts/features/configuration/server-config/named-collections):

```sql theme={null}
CREATE NAMED COLLECTION mypg AS
        host = 'localhost',
        port = 5432,
        database = 'test',
        user = 'postgresql_user',
        password = 'password';
SELECT * FROM postgresql(mypg, table='test') WHERE str IN ('test');
```

```text theme={null}
┌─int_id─┬─int_nullable─┬─float─┬─str──┬─float_nullable─┐
│      1 │         ᴺᵁᴸᴸ │     2 │ test │           ᴺᵁᴸᴸ │
└────────┴──────────────┴───────┴──────┴────────────────┘
```

الإدراج:

```sql theme={null}
INSERT INTO TABLE FUNCTION postgresql('localhost:5432', 'test', 'test', 'postgrsql_user', 'password') (int_id, float) VALUES (2, 3);
SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'password');
```

```text theme={null}
┌─int_id─┬─int_nullable─┬─float─┬─str──┬─float_nullable─┐
│      1 │         ᴺᵁᴸᴸ │     2 │ test │           ᴺᵁᴸᴸ │
│      2 │         ᴺᵁᴸᴸ │     3 │      │           ᴺᵁᴸᴸ │
└────────┴──────────────┴───────┴──────┴────────────────┘
```

استخدام مخطط غير افتراضي:

```text theme={null}
postgres=# CREATE SCHEMA "nice.schema";

postgres=# CREATE TABLE "nice.schema"."nice.table" (a integer);

postgres=# INSERT INTO "nice.schema"."nice.table" SELECT i FROM generate_series(0, 99) as t(i)
```

```sql theme={null}
CREATE TABLE pg_table_schema_with_dots (a UInt32)
        ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
```

<div id="related">
  ## مواضيع ذات صلة
</div>

* [محرك جداول PostgreSQL](/docs/ar/reference/engines/table-engines/integrations/postgresql)
* [استخدام PostgreSQL كمصدر للقاموس](/docs/ar/reference/statements/create/dictionary/sources/postgresql)

<div id="replicating-or-migrating-postgres-data-with-peerdb">
  ### نسخ بيانات Postgres أو ترحيلها باستخدام PeerDB
</div>

> إلى جانب دوال الجداول، يمكنك دائمًا استخدام [PeerDB](https://docs.peerdb.io/introduction) من ClickHouse لإعداد مسار بيانات مستمر من Postgres إلى ClickHouse. تُعد PeerDB أداةً مصممةً خصيصًا لنسخ البيانات من Postgres إلى ClickHouse باستخدام التقاط بيانات التغيير (CDC).