Merge pull request #21268 from olgarev/revolg-DOCSUP-5920-PostgreSQL_function_dictionary_engine

DOCSUP-5920: Documented PostgreSQL engines, function and dictionary

docs/README.md

@@ -126,7 +126,13 @@ Contribute all new information in English language. Other languages are translat
 
 ### Adding a New File
 
-When adding a new file:
+When you add a new file, it should end with a link like:
+
+`[Original article](https://clickhouse.tech/docs/<path-to-the-page>) <!--hide-->`
+
+and there should be **a new empty line** after it.
+
+{## When adding a new file:
 
 - Make symbolic links for all other languages. You can use the following commands:
 
@@ -134,7 +140,7 @@ When adding a new file:
     $ cd /ClickHouse/clone/directory/docs
     $ ln -sr en/new/file.md lang/new/file.md
     ```
-
+##}
 <a name="adding-a-new-language"/>
 
 ### Adding a New Language
@@ -195,8 +201,11 @@ Templates:
 
 - [Function](_description_templates/template-function.md)
 - [Setting](_description_templates/template-setting.md)
+- [Server Setting](_description_templates/template-server-setting.md)
 - [Database or Table engine](_description_templates/template-engine.md)
 - [System table](_description_templates/template-system-table.md)
+- [Data type](_description_templates/data-type.md)
+- [Statement](_description_templates/statement.md)
 
 
 <a name="how-to-build-docs"/>

docs/en/engines/database-engines/index.md

@@ -18,4 +18,8 @@ You can also use the following database engines:
 
 -   [Lazy](../../engines/database-engines/lazy.md)
 
+-   [Atomic](../../engines/database-engines/atomic.md)
+
+-   [PostgreSQL](../../engines/database-engines/postgresql.md)
+
 [Original article](https://clickhouse.tech/docs/en/database_engines/) <!--hide-->

docs/en/engines/database-engines/postgresql.md

+---
+toc_priority: 35
+toc_title: PostgreSQL
+---
+
+# PostgreSQL {#postgresql}
+
+Allows to connect to databases on a remote [PostgreSQL](https://www.postgresql.org) server. Supports read and write operations (`SELECT` and `INSERT` queries) to exchange data between ClickHouse and PostgreSQL.
+
+Gives the real-time access to table list and table structure from remote PostgreSQL with the help of `SHOW TABLES` and `DESCRIBE TABLE` queries.
+
+Supports table structure modifications (`ALTER TABLE ... ADD|DROP COLUMN`). If `use_table_cache` parameter (see the Engine Parameters below) it set to `1`, the table structure is cached and not checked for being modified, but can be updated with `DETACH` and `ATTACH` queries.
+
+## Creating a Database {#creating-a-database}
+
+``` sql
+CREATE DATABASE test_database 
+ENGINE = PostgreSQL('host:port', 'database', 'user', 'password'[, `use_table_cache`]);
+```
+
+**Engine Parameters**
+
+-   `host:port` — PostgreSQL server address.
+-   `database` — Remote database name.
+-   `user` — PostgreSQL user.
+-   `password` — User password.
+-   `use_table_cache` —  Defines if the database table structure is cached or not. Optional. Default value: `0`.
+
+## Data Types Support {#data_types-support}
+
+| PostgerSQL       | ClickHouse                                                   |
+|------------------|--------------------------------------------------------------|
+| DATE             | [Date](../../sql-reference/data-types/date.md)               |
+| TIMESTAMP        | [DateTime](../../sql-reference/data-types/datetime.md)       |
+| REAL             | [Float32](../../sql-reference/data-types/float.md)           |
+| DOUBLE           | [Float64](../../sql-reference/data-types/float.md)           |
+| DECIMAL, NUMERIC | [Decimal](../../sql-reference/data-types/decimal.md)       |
+| SMALLINT         | [Int16](../../sql-reference/data-types/int-uint.md)          |
+| INTEGER          | [Int32](../../sql-reference/data-types/int-uint.md)          |
+| BIGINT           | [Int64](../../sql-reference/data-types/int-uint.md)          |
+| SERIAL           | [UInt32](../../sql-reference/data-types/int-uint.md)         |
+| BIGSERIAL        | [UInt64](../../sql-reference/data-types/int-uint.md)         |
+| TEXT, CHAR       | [String](../../sql-reference/data-types/string.md)           |
+| INTEGER          | Nullable([Int32](../../sql-reference/data-types/int-uint.md))|
+| ARRAY            | [Array](../../sql-reference/data-types/array.md)             |
+ 
+
+## Examples of Use {#examples-of-use}
+
+Database in ClickHouse, exchanging data with the PostgreSQL server:
+
+``` sql
+CREATE DATABASE test_database 
+ENGINE = PostgreSQL('postgres1:5432', 'test_database', 'postgres', 'mysecretpassword', 1);
+```
+
+``` sql
+SHOW DATABASES;
+```
+
+``` text
+┌─name──────────┐
+│ default       │
+│ test_database │
+│ system        │
+└───────────────┘
+```
+
+``` sql
+SHOW TABLES FROM test_database;
+```
+
+``` text
+┌─name───────┐
+│ test_table │
+└────────────┘
+```
+
+Reading data from the PostgreSQL table:
+
+``` sql
+SELECT * FROM test_database.test_table;
+```
+
+``` text
+┌─id─┬─value─┐
+│  1 │     2 │
+└────┴───────┘
+```
+
+Writing data to the PostgreSQL table:
+
+``` sql
+INSERT INTO test_database.test_table VALUES (3,4);
+SELECT * FROM test_database.test_table;
+```
+
+``` text
+┌─int_id─┬─value─┐
+│      1 │     2 │
+│      3 │     4 │
+└────────┴───────┘
+```
+
+Consider the table structure was modified in PostgreSQL: 
+
+``` sql
+postgre> ALTER TABLE test_table ADD COLUMN data Text
+```
+
+As the `use_table_cache` parameter was set to `1` when the database was created, the table structure in ClickHouse was cached and therefore not modified:
+
+``` sql
+DESCRIBE TABLE test_database.test_table;
+```
+``` text
+┌─name───┬─type──────────────┐
+│ id     │ Nullable(Integer) │
+│ value  │ Nullable(Integer) │
+└────────┴───────────────────┘
+```
+
+After detaching the table and attaching it again, the structure was updated:
+
+``` sql
+DETACH TABLE test_database.test_table;
+ATTACH TABLE test_database.test_table;
+DESCRIBE TABLE test_database.test_table;
+```
+``` text
+┌─name───┬─type──────────────┐
+│ id     │ Nullable(Integer) │
+│ value  │ Nullable(Integer) │
+│ data   │ Nullable(String)  │
+└────────┴───────────────────┘
+```
+
+[Original article](https://clickhouse.tech/docs/en/database-engines/postgresql/) <!--hide-->

docs/en/engines/table-engines/index.md

@@ -47,12 +47,17 @@ Engines for communicating with other data storage and processing systems.
 
 Engines in the family:
 
--   [Kafka](../../engines/table-engines/integrations/kafka.md#kafka)
--   [MySQL](../../engines/table-engines/integrations/mysql.md#mysql)
--   [ODBC](../../engines/table-engines/integrations/odbc.md#table-engine-odbc)
--   [JDBC](../../engines/table-engines/integrations/jdbc.md#table-engine-jdbc)
--   [HDFS](../../engines/table-engines/integrations/hdfs.md#hdfs)
--   [S3](../../engines/table-engines/integrations/s3.md#table-engine-s3)
+
+-   [ODBC](../../engines/table-engines/integrations/odbc.md)
+-   [JDBC](../../engines/table-engines/integrations/jdbc.md)
+-   [MySQL](../../engines/table-engines/integrations/mysql.md)
+-   [MongoDB](../../engines/table-engines/integrations/mongodb.md)
+-   [HDFS](../../engines/table-engines/integrations/hdfs.md)
+-   [S3](../../engines/table-engines/integrations/s3.md)
+-   [Kafka](../../engines/table-engines/integrations/kafka.md)
+-   [EmbeddedRocksDB](../../engines/table-engines/integrations/embedded-rocksdb.md)
+-   [RabbitMQ](../../engines/table-engines/integrations/rabbitmq.md)
+-   [PostgreSQL](../../engines/table-engines/integrations/postgresql.md)
 
 ### Special Engines {#special-engines}
 

docs/en/engines/table-engines/integrations/embedded-rocksdb.md

 ---
-toc_priority: 6
+toc_priority: 9
 toc_title: EmbeddedRocksDB
 ---
 

docs/en/engines/table-engines/integrations/hdfs.md

 ---
-toc_priority: 4
+toc_priority: 6
 toc_title: HDFS
 ---
 

docs/en/engines/table-engines/integrations/index.md

 ---
 toc_folder_title: Integrations
-toc_priority: 30
+toc_priority: 1
 ---
 
 # Table Engines for Integrations {#table-engines-for-integrations}
@@ -19,5 +19,3 @@ List of supported integrations:
 -   [EmbeddedRocksDB](../../../engines/table-engines/integrations/embedded-rocksdb.md)
 -   [RabbitMQ](../../../engines/table-engines/integrations/rabbitmq.md)
 -   [PostgreSQL](../../../engines/table-engines/integrations/postgresql.md)
-
-[Original article](https://clickhouse.tech/docs/en/engines/table-engines/integrations/) <!--hide-->

docs/en/engines/table-engines/integrations/jdbc.md

 ---
-toc_priority: 2
+toc_priority: 3
 toc_title: JDBC
 ---
 

docs/en/engines/table-engines/integrations/kafka.md

 ---
-toc_priority: 5
+toc_priority: 8
 toc_title: Kafka
 ---
 

docs/en/engines/table-engines/integrations/mongodb.md

 ---
-toc_priority: 7
+toc_priority: 5
 toc_title: MongoDB
 ---
 

docs/en/engines/table-engines/integrations/mysql.md

 ---
-toc_priority: 3
+toc_priority: 4
 toc_title: MySQL
 ---
 

docs/en/engines/table-engines/integrations/odbc.md

 ---
-toc_priority: 1
+toc_priority: 2
 toc_title: ODBC
 ---
 

docs/en/engines/table-engines/integrations/postgresql.md

 ---
-toc_priority: 8
+toc_priority: 11
 toc_title: PostgreSQL
 ---
 
 # PostgreSQL {#postgresql}
 
-The PostgreSQL engine allows you to perform `SELECT` queries on data that is stored on a remote PostgreSQL server.
+The PostgreSQL engine allows to perform `SELECT` and `INSERT` queries on data that is stored on a remote PostgreSQL server.
 
 ## Creating a Table {#creating-a-table}
 
@@ -15,7 +15,7 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
     name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [TTL expr1],
     name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2] [TTL expr2],
     ...
-) ENGINE = PostgreSQL('host:port', 'database', 'table', 'user', 'password');
+) ENGINE = PostgreSQL('host:port', 'database', 'table', 'user', 'password'[, `schema`]);
 ```
 
 See a detailed description of the [CREATE TABLE](../../../sql-reference/statements/create/table.md#create-table-query) query.
@@ -29,25 +29,51 @@ The table structure can differ from the original PostgreSQL table structure:
 **Engine Parameters**
 
 -   `host:port` — PostgreSQL server address.
-
 -   `database` — Remote database name.
-
 -   `table` — Remote table name.
-
 -   `user` — PostgreSQL user.
-
 -   `password` — User password.
+-   `schema` — Non-default table schema. Optional.
 
-SELECT Queries on PostgreSQL side run as `COPY (SELECT ...) TO STDOUT` inside read-only PostgreSQL transaction with commit after each `SELECT` query.
+## Implementation Details {#implementation-details}
 
-Simple `WHERE` clauses such as `=, !=, >, >=, <, <=, IN` are executed on the PostgreSQL server.
+`SELECT` queries on PostgreSQL side run as `COPY (SELECT ...) TO STDOUT` inside read-only PostgreSQL transaction with commit after each `SELECT` query.
 
-All joins, aggregations, sorting, `IN [ array ]` conditions and the `LIMIT` sampling constraint are executed in ClickHouse only after the query to PostgreSQL finishes.
+Simple `WHERE` clauses such as `=`, `!=`, `>`, `>=`, `<`, `<=`, and `IN` are executed on the PostgreSQL server.
 
-INSERT Queries on PostgreSQL side run as `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` inside PostgreSQL transaction with auto-commit after each `INSERT` statement.
+All joins, aggregations, sorting, `IN [ array ]` conditions and the `LIMIT` sampling constraint are executed in ClickHouse only after the query to PostgreSQL finishes.
 
-PostgreSQL Array types converts into ClickHouse arrays.
-Be careful in PostgreSQL an array data created like a type_name[] may contain multi-dimensional arrays of different dimensions in different table rows in same column, but in ClickHouse it is only allowed to have multidimensional arrays of the same count of dimensions in all table rows in same column.
+`INSERT` queries on PostgreSQL side run as `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` inside PostgreSQL transaction with auto-commit after each `INSERT` statement.
+
+PostgreSQL `Array` types are converted into ClickHouse arrays.
+
+!!! info "Note"
+    Be careful - in PostgreSQL an array data, created like a `type_name[]`, may contain multi-dimensional arrays of different dimensions in different table rows in same column. But in ClickHouse it is only allowed to have multidimensional arrays of the same count of dimensions in all table rows in same column.
+
+Replicas priority for PostgreSQL dictionary source is supported. The bigger the number in map, the less the priority. The highest priority is `0`. 
+
+In the example below replica `example01-1` has the highest priority:
+
+```xml
+<postgresql>
+    <port>5432</port>
+    <user>clickhouse</user>
+    <password>qwerty</password>
+    <replica>
+        <host>example01-1</host>
+        <priority>1</priority>
+    </replica>
+    <replica>
+        <host>example01-2</host>
+        <priority>2</priority>
+    </replica>
+    <db>db_name</db>
+    <table>table_name</table>
+    <where>id=10</where>
+    <invalidate_query>SQL_QUERY</invalidate_query>
+</postgresql>
+</source>
+```
 
 ## Usage Example {#usage-example}
 
@@ -64,10 +90,10 @@ PRIMARY KEY (int_id));
 
 CREATE TABLE
 
-postgres=# insert into test (int_id, str, "float") VALUES (1,'test',2);
+postgres=# INSERT INTO test (int_id, str, "float") VALUES (1,'test',2);
 INSERT 0 1
 
-postgresql> select * from test;
+postgresql> SELECT * FROM test;
  int_id | int_nullable | float | str  | float_nullable
 --------+--------------+-------+------+----------------
       1 |              |     2 | test |
@@ -87,20 +113,33 @@ ENGINE = PostgreSQL('localhost:5432', 'public', 'test', 'postges_user', 'postgre
 ```
 
 ``` sql
-SELECT * FROM postgresql_table WHERE str IN ('test') 
+SELECT * FROM postgresql_table WHERE str IN ('test');
 ```
 
 ``` text
 ┌─float_nullable─┬─str──┬─int_id─┐
 │           ᴺᵁᴸᴸ │ test │      1 │
 └────────────────┴──────┴────────┘
-1 rows in set. Elapsed: 0.019 sec.
 ```
 
+Using Non-default Schema:
+
+```text
+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
+CREATE TABLE pg_table_schema_with_dots (a UInt32)
+        ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
+```
 
-## See Also {#see-also}
+**See Also**
 
--   [The ‘postgresql’ table function](../../../sql-reference/table-functions/postgresql.md)
+-   [The `postgresql` table function](../../../sql-reference/table-functions/postgresql.md)
 -   [Using PostgreSQL as a source of external dictionary](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md#dicts-external_dicts_dict_sources-postgresql)
 
 [Original article](https://clickhouse.tech/docs/en/engines/table-engines/integrations/postgresql/) <!--hide-->

docs/en/engines/table-engines/integrations/rabbitmq.md

 ---
-toc_priority: 6
+toc_priority: 10
 toc_title: RabbitMQ
 ---
 

docs/en/engines/table-engines/integrations/s3.md

 ---
-toc_priority: 4
+toc_priority: 7
 toc_title: S3
 ---
 

docs/en/sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md

@@ -69,6 +69,8 @@ Types of sources (`source_type`):
     -   [ClickHouse](#dicts-external_dicts_dict_sources-clickhouse)
     -   [MongoDB](#dicts-external_dicts_dict_sources-mongodb)
     -   [Redis](#dicts-external_dicts_dict_sources-redis)
+    -   [Cassandra](#dicts-external_dicts_dict_sources-cassandra)
+    -   [PostgreSQL](#dicts-external_dicts_dict_sources-postgresql)    
 
 ## Local File {#dicts-external_dicts_dict_sources-local_file}
 

docs/en/sql-reference/table-functions/index.md

@@ -21,16 +21,18 @@ You can use table functions in:
 !!! warning "Warning"
     You can’t use table functions if the [allow_ddl](../../operations/settings/permissions-for-queries.md#settings_allow_ddl) setting is disabled.
 
-| Function                                                        | Description                                                                                                                            |
-|-----------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
-| [file](../../sql-reference/table-functions/file.md)             | Creates a File-engine table. |
-| [merge](../../sql-reference/table-functions/merge.md)           | Creates a Merge-engine table. |
-| [numbers](../../sql-reference/table-functions/numbers.md)       | Creates a table with a single column filled with integer numbers. |
-| [remote](../../sql-reference/table-functions/remote.md)         | Allows you to access remote servers without creating a Distributed-engine table. |
-| [url](../../sql-reference/table-functions/url.md)               | Creates a URL-engine table. |
-| [mysql](../../sql-reference/table-functions/mysql.md)           | Creates a MySQL-engine table. |
-| [postgresql](../../sql-reference/table-functions/postgresql.md) | Creates a PostgreSQL-engine table. |
-| [jdbc](../../sql-reference/table-functions/jdbc.md)             | Creates a JDBC-engine table. |
-| [odbc](../../sql-reference/table-functions/odbc.md)             | Creates a ODBC-engine table. |
-| [hdfs](../../sql-reference/table-functions/hdfs.md)             | Creates a HDFS-engine table. |
-| [s3](../../sql-reference/table-functions/s3.md)                 | Creates a S3-engine table. |
+| Function                                                         | Description                                                                                                                            |
+|------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| [file](../../sql-reference/table-functions/file.md)              | Creates a [File](../../engines/table-engines/special/file.md)-engine table.                                                            |
+| [merge](../../sql-reference/table-functions/merge.md)            | Creates a [Merge](../../engines/table-engines/special/merge.md)-engine table.                                                          |
+| [numbers](../../sql-reference/table-functions/numbers.md)        | Creates a table with a single column filled with integer numbers.                                                                      |
+| [remote](../../sql-reference/table-functions/remote.md)          | Allows you to access remote servers without creating a [Distributed](../../engines/table-engines/special/distributed.md)-engine table. |
+| [url](../../sql-reference/table-functions/url.md)                | Creates a [Url](../../engines/table-engines/special/url.md)-engine table.                                                              |
+| [mysql](../../sql-reference/table-functions/mysql.md)            | Creates a [MySQL](../../engines/table-engines/integrations/mysql.md)-engine table.                                                     |
+| [postgresql](../../sql-reference/table-functions/postgresql.md)  | Creates a [PostgreSQL](../../engines/table-engines/integrations/postgresql.md)-engine table.                                           |
+| [jdbc](../../sql-reference/table-functions/jdbc.md)              | Creates a [JDBC](../../engines/table-engines/integrations/jdbc.md)-engine table.                                                       |
+| [odbc](../../sql-reference/table-functions/odbc.md)              | Creates a [ODBC](../../engines/table-engines/integrations/odbc.md)-engine table.                                                       |
+| [hdfs](../../sql-reference/table-functions/hdfs.md)              | Creates a [HDFS](../../engines/table-engines/integrations/hdfs.md)-engine table.                                                       |
+| [s3](../../sql-reference/table-functions/s3.md)                  | Creates a [S3](../../engines/table-engines/integrations/s3.md)-engine table.                                                           |
+
+[Original article](https://clickhouse.tech/docs/en/sql-reference/table-functions/) <!--hide-->

docs/en/sql-reference/table-functions/postgresql.md

@@ -10,40 +10,41 @@ Allows `SELECT` and `INSERT` queries to be performed on data that is stored on a
 **Syntax**
 
 ``` sql
-postgresql('host:port', 'database', 'table', 'user', 'password')
+postgresql('host:port', 'database', 'table', 'user', 'password'[, `schema`])
 ```
 
 **Arguments**
 
 -   `host:port` — PostgreSQL server address.
-
 -   `database` — Remote database name.
-
 -   `table` — Remote table name.
-
 -   `user` — PostgreSQL user.
-
 -   `password` — User password.
+-   `schema` — Non-default table schema. Optional.
 
+**Returned Value**
 
-SELECT Queries on PostgreSQL side run as `COPY (SELECT ...) TO STDOUT` inside read-only PostgreSQL transaction with commit after each `SELECT` query.
+A table object with the same columns as the original PostgreSQL table.
 
-Simple `WHERE` clauses such as `=, !=, >, >=, <, <=, IN` are executed on the PostgreSQL server.
+!!! info "Note"
+    In the `INSERT` query to distinguish table function `postgresql(...)` from table name with column names list you must use keywords `FUNCTION` or `TABLE FUNCTION`. See examples below.
 
-All joins, aggregations, sorting, `IN [ array ]` conditions and the `LIMIT` sampling constraint are executed in ClickHouse only after the query to PostgreSQL finishes.
+## Implementation Details {#implementation-details}
 
-INSERT Queries on PostgreSQL side run as `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` inside PostgreSQL transaction with auto-commit after each `INSERT` statement.
+`SELECT` queries on PostgreSQL side run as `COPY (SELECT ...) TO STDOUT` inside read-only PostgreSQL transaction with commit after each `SELECT` query.
 
-PostgreSQL Array types converts into ClickHouse arrays.
+Simple `WHERE` clauses such as `=`, `!=`, `>`, `>=`, `<`, `<=`, and `IN` are executed on the PostgreSQL server.
 
-Be careful in PostgreSQL an array data type column like Integer[] may contain arrays of different dimensions in different rows, but in ClickHouse it is only allowed to have multidimensional arrays of the same dimension in all rows.
+All joins, aggregations, sorting, `IN [ array ]` conditions and the `LIMIT` sampling constraint are executed in ClickHouse only after the query to PostgreSQL finishes.
 
-**Returned Value**
+`INSERT` queries on PostgreSQL side run as `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` inside PostgreSQL transaction with auto-commit after each `INSERT` statement.
 
-A table object with the same columns as the original PostgreSQL table.
+PostgreSQL Array types converts into ClickHouse arrays.
 
 !!! info "Note"
-    In the `INSERT` query to distinguish table function `postgresql(...)` from table name with column names list you must use keywords `FUNCTION` or `TABLE FUNCTION`. See examples below.
+    Be careful, in PostgreSQL an array data type column like Integer[] may contain arrays of different dimensions in different rows, but in ClickHouse it is only allowed to have multidimensional arrays of the same dimension in all rows.
+
+Supports replicas priority for PostgreSQL dictionary source. The bigger the number in map, the less the priority. The highest priority is `0`. 
 
 **Examples**
 
@@ -60,10 +61,10 @@ PRIMARY KEY (int_id));
 
 CREATE TABLE
 
-postgres=# insert into test (int_id, str, "float") VALUES (1,'test',2);
+postgres=# INSERT INTO test (int_id, str, "float") VALUES (1,'test',2);
 INSERT 0 1
 
-postgresql> select * from test;
+postgresql> SELECT * FROM test;
  int_id | int_nullable | float | str  | float_nullable
 --------+--------------+-------+------+----------------
       1 |              |     2 | test |
@@ -96,9 +97,24 @@ SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'p
 └────────┴──────────────┴───────┴──────┴────────────────┘
 ```
 
+Using Non-default Schema:
+
+```text
+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
+CREATE TABLE pg_table_schema_with_dots (a UInt32)
+        ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
+```
+
 **See Also**
 
--   [The ‘PostgreSQL’ table engine](../../engines/table-engines/integrations/postgresql.md)
+-   [The PostgreSQL table engine](../../engines/table-engines/integrations/postgresql.md)
 -   [Using PostgreSQL as a source of external dictionary](../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md#dicts-external_dicts_dict_sources-postgresql)
 
 [Original article](https://clickhouse.tech/docs/en/sql-reference/table-functions/postgresql/) <!--hide-->

docs/ru/engines/database-engines/index.md

@@ -4,7 +4,7 @@ toc_priority: 27
 toc_title: "Введение"
 ---
 
-# Движки баз данных {#dvizhki-baz-dannykh}
+# Движки баз данных {#database-engines}
 
 Движки баз данных обеспечивают работу с таблицами.
 
@@ -18,3 +18,5 @@ toc_title: "Введение"
 
 -   [Lazy](../../engines/database-engines/lazy.md)
 
+-   [PostgreSQL](../../engines/database-engines/postgresql.md)
+

docs/ru/engines/database-engines/postgresql.md

+---
+toc_priority: 35
+toc_title: PostgreSQL
+---
+
+# PostgreSQL {#postgresql}
+
+Позволяет подключаться к БД на удаленном сервере [PostgreSQL](https://www.postgresql.org). Поддерживает операции чтения и записи (запросы `SELECT` и `INSERT`) для обмена данными между ClickHouse и PostgreSQL.
+
+Позволяет в реальном времени получать от удаленного сервера PostgreSQL информацию о таблицах БД и их структуре с помощью запросов `SHOW TABLES` и `DESCRIBE TABLE`.
+
+Поддерживает операции изменения структуры таблиц (`ALTER TABLE ... ADD|DROP COLUMN`). Если параметр `use_table_cache` (см. ниже раздел Параметры движка) установлен в значение `1`, структура таблицы кешируется, и изменения в структуре не отслеживаются, но будут обновлены, если выполнить команды `DETACH` и `ATTACH`.
+
+## Создание БД {#creating-a-database}
+
+``` sql
+CREATE DATABASE test_database 
+ENGINE = PostgreSQL('host:port', 'database', 'user', 'password'[, `use_table_cache`]);
+```
+
+**Параметры движка**
+
+-   `host:port` — адрес сервера PostgreSQL.
+-   `database` — имя удаленной БД.
+-   `user` — пользователь PostgreSQL.
+-   `password` — пароль пользователя.
+-   `use_table_cache` —  определяет кеширование структуры таблиц БД. Необязательный параметр. Значение по умолчанию: `0`.
+
+## Поддерживаемые типы данных {#data_types-support}
+
+| PostgerSQL       | ClickHouse                                                   |
+|------------------|--------------------------------------------------------------|
+| DATE             | [Date](../../sql-reference/data-types/date.md)               |
+| TIMESTAMP        | [DateTime](../../sql-reference/data-types/datetime.md)       |
+| REAL             | [Float32](../../sql-reference/data-types/float.md)           |
+| DOUBLE           | [Float64](../../sql-reference/data-types/float.md)           |
+| DECIMAL, NUMERIC | [Decimal](../../sql-reference/data-types/decimal.md)       |
+| SMALLINT         | [Int16](../../sql-reference/data-types/int-uint.md)          |
+| INTEGER          | [Int32](../../sql-reference/data-types/int-uint.md)          |
+| BIGINT           | [Int64](../../sql-reference/data-types/int-uint.md)          |
+| SERIAL           | [UInt32](../../sql-reference/data-types/int-uint.md)         |
+| BIGSERIAL        | [UInt64](../../sql-reference/data-types/int-uint.md)         |
+| TEXT, CHAR       | [String](../../sql-reference/data-types/string.md)           |
+| INTEGER          | Nullable([Int32](../../sql-reference/data-types/int-uint.md))|
+| ARRAY            | [Array](../../sql-reference/data-types/array.md)             |
+ 
+
+## Примеры использования {#examples-of-use}
+
+Обмен данными между БД ClickHouse и сервером PostgreSQL:
+
+``` sql
+CREATE DATABASE test_database 
+ENGINE = PostgreSQL('postgres1:5432', 'test_database', 'postgres', 'mysecretpassword', 1);
+```
+
+``` sql
+SHOW DATABASES;
+```
+
+``` text
+┌─name──────────┐
+│ default       │
+│ test_database │
+│ system        │
+└───────────────┘
+```
+
+``` sql
+SHOW TABLES FROM test_database;
+```
+
+``` text
+┌─name───────┐
+│ test_table │
+└────────────┘
+```
+
+Чтение данных из таблицы PostgreSQL:
+
+``` sql
+SELECT * FROM test_database.test_table;
+```
+
+``` text
+┌─id─┬─value─┐
+│  1 │     2 │
+└────┴───────┘
+```
+
+Запись данных в таблицу PostgreSQL:
+
+``` sql
+INSERT INTO test_database.test_table VALUES (3,4);
+SELECT * FROM test_database.test_table;
+```
+
+``` text
+┌─int_id─┬─value─┐
+│      1 │     2 │
+│      3 │     4 │
+└────────┴───────┘
+```
+
+Пусть структура таблицы была изменена в PostgreSQL: 
+
+``` sql
+postgre> ALTER TABLE test_table ADD COLUMN data Text
+```
+
+Поскольку при создании БД параметр `use_table_cache` был установлен в значение `1`, структура таблицы в ClickHouse была кеширована и поэтому не изменилась:
+
+``` sql
+DESCRIBE TABLE test_database.test_table;
+```
+``` text
+┌─name───┬─type──────────────┐
+│ id     │ Nullable(Integer) │
+│ value  │ Nullable(Integer) │
+└────────┴───────────────────┘
+```
+
+После того как таблицу «отцепили» и затем снова «прицепили», структура обновилась:
+
+``` sql
+DETACH TABLE test_database.test_table;
+ATTACH TABLE test_database.test_table;
+DESCRIBE TABLE test_database.test_table;
+```
+``` text
+┌─name───┬─type──────────────┐
+│ id     │ Nullable(Integer) │
+│ value  │ Nullable(Integer) │
+│ data   │ Nullable(String)  │
+└────────┴───────────────────┘
+```
+
+[Оригинальная статья](https://clickhouse.tech/docs/ru/database-engines/postgresql/) <!--hide-->

docs/ru/engines/table-engines/index.md

@@ -16,7 +16,7 @@ toc_title: "Введение"
 -   Возможно ли многопоточное выполнение запроса.
 -   Параметры репликации данных.
 
-## Семейства движков {#semeistva-dvizhkov}
+## Семейства движков {#engine-families}
 
 ### MergeTree {#mergetree}
 
@@ -42,18 +42,23 @@ toc_title: "Введение"
 -   [StripeLog](log-family/stripelog.md#stripelog)
 -   [Log](log-family/log.md#log)
 
-### Движки для интеграции {#dvizhki-dlia-integratsii}
+### Движки для интеграции {#integration-engines}
 
 Движки для связи с другими системами хранения и обработки данных.
 
 Движки семейства:
 
--   [Kafka](integrations/kafka.md#kafka)
--   [MySQL](integrations/mysql.md#mysql)
--   [ODBC](integrations/odbc.md#table-engine-odbc)
--   [JDBC](integrations/jdbc.md#table-engine-jdbc)
-
-### Специальные движки {#spetsialnye-dvizhki}
+-   [ODBC](../../engines/table-engines/integrations/odbc.md)
+-   [JDBC](../../engines/table-engines/integrations/jdbc.md)
+-   [MySQL](../../engines/table-engines/integrations/mysql.md)
+-   [MongoDB](../../engines/table-engines/integrations/mongodb.md)
+-   [HDFS](../../engines/table-engines/integrations/hdfs.md)
+-   [Kafka](../../engines/table-engines/integrations/kafka.md)
+-   [EmbeddedRocksDB](../../engines/table-engines/integrations/embedded-rocksdb.md)
+-   [RabbitMQ](../../engines/table-engines/integrations/rabbitmq.md)
+-   [PostgreSQL](../../engines/table-engines/integrations/postgresql.md)
+
+### Специальные движки {#special-engines}
 
 Движки семейства:
 

docs/ru/engines/table-engines/integrations/embedded-rocksdb.md

 ---
-toc_priority: 6
+toc_priority: 9
 toc_title: EmbeddedRocksDB
 ---
 

docs/ru/engines/table-engines/integrations/hdfs.md

 ---
-toc_priority: 4
+toc_priority: 6
 toc_title: HDFS
 ---
 

docs/ru/engines/table-engines/integrations/jdbc.md

 ---
-toc_priority: 2
+toc_priority: 3
 toc_title: JDBC
 ---
 

docs/ru/engines/table-engines/integrations/kafka.md

 ---
-toc_priority: 5
+toc_priority: 8
 toc_title: Kafka
 ---
 

docs/ru/engines/table-engines/integrations/mongodb.md

 ---
-toc_priority: 7
+toc_priority: 5
 toc_title: MongoDB
 ---
 

docs/ru/engines/table-engines/integrations/mysql.md

 ---
-toc_priority: 3
+toc_priority: 4
 toc_title: MySQL
 ---
 

docs/ru/engines/table-engines/integrations/odbc.md

 ---
-toc_priority: 1
+toc_priority: 2
 toc_title: ODBC
 ---
 

docs/ru/engines/table-engines/integrations/postgresql.md

 ---
-toc_priority: 8
+toc_priority: 11
 toc_title: PostgreSQL
 ---
 
-# PostgreSQL {#postgresql}
+#PostgreSQL {#postgresql}
 
-Движок PostgreSQL позволяет выполнять запросы `SELECT` над данными, хранящимися на удалённом PostgreSQL сервере.
+Движок PostgreSQL позволяет выполнять запросы `SELECT` и `INSERT` для таблиц на удаленном сервере PostgreSQL.
 
 ## Создание таблицы {#creating-a-table}
 
@@ -15,7 +15,7 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
     name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1] [TTL expr1],
     name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2] [TTL expr2],
     ...
-) ENGINE = PostgreSQL('host:port', 'database', 'table', 'user', 'password');
+) ENGINE = PostgreSQL('host:port', 'database', 'table', 'user', 'password'[, `schema`]);
 ```
 
 Смотрите подробное описание запроса [CREATE TABLE](../../../sql-reference/statements/create/table.md#create-table-query).
@@ -29,25 +29,51 @@ CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster]
 **Параметры движка**
 
 -   `host:port` — адрес сервера PostgreSQL.
-
 -   `database` — Имя базы данных на сервере PostgreSQL.
-
 -   `table` — Имя таблицы.
-
 -   `user` — Имя пользователя PostgreSQL.
-
 -   `password` — Пароль пользователя PostgreSQL.
+-   `schema` — имя схемы, если не используется схема по умолчанию. Необязательный аргумент. 
 
-SELECT запросы на стороне PostgreSQL выполняются как `COPY (SELECT ...) TO STDOUT` внутри транзакции PostgreSQL только на чтение  с коммитом после каждого `SELECT` запроса.
+## Особенности реализации {#implementation-details}
 
-Простые условия для `WHERE` такие как `=, !=, >, >=, <, <=, IN` исполняются на стороне PostgreSQL сервера.
+Запросы `SELECT` на стороне PostgreSQL выполняются как `COPY (SELECT ...) TO STDOUT` внутри транзакции PostgreSQL только на чтение с коммитом после каждого запроса `SELECT`.
 
-Все операции объединения, аггрегации, сортировки, условия `IN [ array ]` и ограничения `LIMIT` выполняются на стороне ClickHouse только после того как запрос к PostgreSQL закончился.
+Простые условия для `WHERE`, такие как `=`, `!=`, `>`, `>=`, `<`, `<=` и `IN`, исполняются на стороне PostgreSQL сервера.
 
-INSERT запросы на стороне PostgreSQL выполняются как `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` внутри PostgreSQL транзакции с автоматическим коммитом после каждого `INSERT` запроса.
+Все операции объединения, аггрегации, сортировки, условия `IN [ array ]` и ограничения `LIMIT` выполняются на стороне ClickHouse только после того, как запрос к PostgreSQL закончился.
+
+Запросы `INSERT` на стороне PostgreSQL выполняются как `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` внутри PostgreSQL транзакции с автоматическим коммитом после каждого запроса `INSERT`.
 
 PostgreSQL массивы конвертируются в массивы ClickHouse.
-Будьте осторожны в PostgreSQL массивы созданные как type_name[], являются многомерными и могут содержать в себе разное количество измерений в разных строках одной таблицы, внутри ClickHouse допустипы только многомерные массивы с одинаковым кол-вом измерений во всех строках таблицы.
+
+!!! info "Внимание"
+    Будьте внимательны, в PostgreSQL массивы, созданные как `type_name[]`, являются многомерными и могут содержать в себе разное количество измерений в разных строках одной таблицы. Внутри ClickHouse допустимы только многомерные массивы с одинаковым кол-вом измерений во всех строках таблицы.
+
+При использовании словаря PostgreSQL поддерживается приоритет реплик. Чем больше номер реплики, тем ниже ее приоритет. Наивысший приоритет у реплики с номером `0`.  
+
+В примере ниже реплика `example01-1` имеет более высокий приоритет:
+
+```xml
+<postgresql>
+    <port>5432</port>
+    <user>clickhouse</user>
+    <password>qwerty</password>
+    <replica>
+        <host>example01-1</host>
+        <priority>1</priority>
+    </replica>
+    <replica>
+        <host>example01-2</host>
+        <priority>2</priority>
+    </replica>
+    <db>db_name</db>
+    <table>table_name</table>
+    <where>id=10</where>
+    <invalidate_query>SQL_QUERY</invalidate_query>
+</postgresql>
+</source>
+```
 
 ## Пример использования {#usage-example}
 
@@ -64,17 +90,17 @@ PRIMARY KEY (int_id));
 
 CREATE TABLE
 
-postgres=# insert into test (int_id, str, "float") VALUES (1,'test',2);
+postgres=# INSERT INTO test (int_id, str, "float") VALUES (1,'test',2);
 INSERT 0 1
 
-postgresql> select * from test;
+postgresql> SELECT * FROM test;
  int_id | int_nullable | float | str  | float_nullable
 --------+--------------+-------+------+----------------
       1 |              |     2 | test |
 (1 row)
 ```
 
-Таблица в ClickHouse, получение данных из PostgreSQL таблицы созданной выше:
+Таблица в ClickHouse, получение данных из PostgreSQL таблицы, созданной выше:
 
 ``` sql
 CREATE TABLE default.postgresql_table
@@ -87,19 +113,33 @@ ENGINE = PostgreSQL('localhost:5432', 'public', 'test', 'postges_user', 'postgre
 ```
 
 ``` sql
-SELECT * FROM postgresql_table WHERE str IN ('test') 
+SELECT * FROM postgresql_table WHERE str IN ('test'); 
 ```
 
 ``` text
 ┌─float_nullable─┬─str──┬─int_id─┐
 │           ᴺᵁᴸᴸ │ test │      1 │
 └────────────────┴──────┴────────┘
-1 rows in set. Elapsed: 0.019 sec.
 ```
 
+Using Non-default Schema:
+
+```text
+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
+CREATE TABLE pg_table_schema_with_dots (a UInt32)
+        ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
+```
 
-## Смотри также {#see-also}
+**См. также** 
 
--   [Табличная функция ‘postgresql’](../../../sql-reference/table-functions/postgresql.md)
--   [Использование PostgreSQL в качестве истояника для внешнего словаря](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md#dicts-external_dicts_dict_sources-postgresql)
+-   [Табличная функция `postgresql`](../../../sql-reference/table-functions/postgresql.md)
+-   [Использование PostgreSQL в качестве источника для внешнего словаря](../../../sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md#dicts-external_dicts_dict_sources-postgresql)
 
+[Оригинальная статья](https://clickhouse.tech/docs/ru/engines/table-engines/integrations/postgresql/) <!--hide-->

docs/ru/sql-reference/dictionaries/external-dictionaries/external-dicts-dict-sources.md

@@ -69,6 +69,7 @@ SETTINGS(format_csv_allow_single_quotes = 0)
     -   [ClickHouse](#dicts-external_dicts_dict_sources-clickhouse)
     -   [MongoDB](#dicts-external_dicts_dict_sources-mongodb)
     -   [Redis](#dicts-external_dicts_dict_sources-redis)
+    -   [PostgreSQL](#dicts-external_dicts_dict_sources-postgresql)      
 
 ## Локальный файл {#dicts-external_dicts_dict_sources-local_file}
 

docs/ru/sql-reference/table-functions/postgresql.md

@@ -5,43 +5,46 @@ toc_title: postgresql
 
 # postgresql {#postgresql}
 
-Позволяет выполнять запросы `SELECT` над данными, хранящимися на удалённом PostgreSQL сервере.
+Позволяет выполнять запросы `SELECT` и `INSERT` над таблицами удаленной БД PostgreSQL.
 
 **Синтаксис**
+
 ``` sql
-postgresql('host:port', 'database', 'table', 'user', 'password')
+postgresql('host:port', 'database', 'table', 'user', 'password'[, `schema`])
 ```
 
-**Параметры**
+**Аргументы**
 
 -   `host:port` — адрес сервера PostgreSQL.
-
 -   `database` — имя базы данных на удалённом сервере.
-
 -   `table` — имя таблицы на удалённом сервере.
-
 -   `user` — пользователь PostgreSQL.
-
 -   `password` — пароль пользователя.
+-   `schema` — имя схемы, если не используется схема по умолчанию. Необязательный аргумент. 
 
+**Возвращаемое значение**
 
-SELECT запросы на стороне PostgreSQL выполняются как `COPY (SELECT ...) TO STDOUT` внутри транзакции PostgreSQL только на чтение  с коммитом после каждого `SELECT` запроса.
+Таблица с теми же столбцами, что и в исходной таблице PostgreSQL.
 
-Простые условия для `WHERE` такие как `=, !=, >, >=, <, <=, IN` исполняются на стороне PostgreSQL сервера.
+!!! info "Примечание"
+    В запросах `INSERT` для того чтобы отличить табличную функцию `postgresql(...)` от таблицы со списком имен столбцов вы должны указывать ключевые слова `FUNCTION` или `TABLE FUNCTION`. См. примеры ниже.
 
-Все операции объединения, аггрегации, сортировки, условия `IN [ array ]` и ограничения `LIMIT` выполняются на стороне ClickHouse только после того как запрос к PostgreSQL закончился.
+## Особенности реализации {#implementation-details}
 
-INSERT запросы на стороне PostgreSQL выполняются как `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` внутри PostgreSQL транзакции с автоматическим коммитом после каждого `INSERT` запроса.
+Запросы `SELECT` на стороне PostgreSQL выполняются как `COPY (SELECT ...) TO STDOUT` внутри транзакции PostgreSQL только на чтение  с коммитом после каждого запроса `SELECT`.
 
-PostgreSQL массивы конвертируются в массивы ClickHouse.
-Будьте осторожны в PostgreSQL массивы созданные как type_name[], являются многомерными и могут содержать в себе разное количество измерений в разных строках одной таблицы, внутри ClickHouse допустипы только многомерные массивы с одинаковым кол-вом измерений во всех строках таблицы.
+Простые условия для `WHERE` такие как `=`, `!=`, `>`, `>=`, `<`, `<=` и `IN` исполняются на стороне PostgreSQL сервера.
 
-**Возвращаемое значение**
+Все операции объединения, аггрегации, сортировки, условия `IN [ array ]` и ограничения `LIMIT` выполняются на стороне ClickHouse только после того как запрос к PostgreSQL закончился.
 
-Объект таблицы с теми же столбцами, что и в исходной таблице PostgreSQL.
+Запросы `INSERT` на стороне PostgreSQL выполняются как `COPY "table_name" (field1, field2, ... fieldN) FROM STDIN` внутри PostgreSQL транзакции с автоматическим коммитом после каждого запроса `INSERT`.
+
+PostgreSQL массивы конвертируются в массивы ClickHouse.
 
 !!! info "Примечание"
-В запросах `INSERT` для того чтобы отличить табличную функцию `postgresql(...)` от таблицы со списком имен столбцов вы должны указывать ключевые слова `FUNCTION` или `TABLE FUNCTION`. See examples below.
+    Будьте внимательны, в PostgreSQL массивы, созданные как `type_name[]`, являются многомерными и могут содержать в себе разное количество измерений в разных строках одной таблицы. Внутри ClickHouse допустипы только многомерные массивы с одинаковым кол-вом измерений во всех строках таблицы.
+
+При использовании словаря PostgreSQL поддерживается приоритет реплик. Чем больше номер реплики, тем ниже ее приоритет. Наивысший приоритет у реплики с номером `0`.    
 
 **Примеры**
 
@@ -58,10 +61,10 @@ PRIMARY KEY (int_id));
 
 CREATE TABLE
 
-postgres=# insert into test (int_id, str, "float") VALUES (1,'test',2);
+postgres=# INSERT INTO test (int_id, str, "float") VALUES (1,'test',2);
 INSERT 0 1
 
-postgresql> select * from test;
+postgresql> SELECT * FROM test;
  int_id | int_nullable | float | str  | float_nullable
 --------+--------------+-------+------+----------------
       1 |              |     2 | test |
@@ -80,7 +83,7 @@ SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'p
 └────────┴──────────────┴───────┴──────┴────────────────┘
 ```
 
-Вставка:
+Вставка данных:
 
 ```sql
 INSERT INTO TABLE FUNCTION postgresql('localhost:5432', 'test', 'test', 'postgrsql_user', 'password') (int_id, float) VALUES (2, 3);
@@ -94,7 +97,24 @@ SELECT * FROM postgresql('localhost:5432', 'test', 'test', 'postgresql_user', 'p
 └────────┴──────────────┴───────┴──────┴────────────────┘
 ```
 
-**Смотрите также**
+Using Non-default Schema:
+
+```text
+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)
+```
 
--   [Движок таблиц ‘PostgreSQL’](../../sql-reference/table-functions/postgresql.md)
+```sql
+CREATE TABLE pg_table_schema_with_dots (a UInt32)
+        ENGINE PostgreSQL('localhost:5432', 'clickhouse', 'nice.table', 'postgrsql_user', 'password', 'nice.schema');
+```
+
+**См. также**
+
+-   [Движок таблиц PostgreSQL](../../sql-reference/table-functions/postgresql.md)
 -   [Использование PostgreSQL как источника данных для внешнего словаря](../../sql-reference/table-functions/postgresql.md#dicts-external_dicts_dict_sources-postgresql)
+
+[Оригинальная статья](https://clickhouse.tech/docs/ru/sql-reference/table-functions/postgresql/) <!--hide-->