diff --git a/docs/en/engines/database-engines/materialized-postgresql.md b/docs/en/engines/database-engines/materialized-postgresql.md index d1440746b2f..5c1dc105d72 100644 --- a/docs/en/engines/database-engines/materialized-postgresql.md +++ b/docs/en/engines/database-engines/materialized-postgresql.md @@ -14,32 +14,37 @@ This feature is experimental. ## Creating a Database {#creating-a-database} ``` sql -CREATE DATABASE test_database -ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password'); - -SELECT * FROM test_database.postgres_table; +CREATE DATABASE [IF NOT EXISTS] db_name [ON CLUSTER cluster] +ENGINE = MaterializedPostgreSQL('host:port', ['database' | database], 'user', 'password') [SETTINGS ...] ``` +**Engine Parameters** + +- `host:port` — PostgreSQL server endpoint. +- `database` — PostgreSQL database name. +- `user` — PostgreSQL user. +- `password` — User password. + ## Settings {#settings} -1. `materialized_postgresql_max_block_size` — Number of rows collected in memory before flushing data into table. Default: `65536`. +- [materialized_postgresql_max_block_size](../../operations/settings/settings.md#materialized-postgresql-max-block-size) -2. `materialized_postgresql_tables_list` — A comma-separated list of PostgreSQL database tables, which will be replicated via MaterializedPostgreSQL database engine. Default: empty list - means whole PostgreSQL database will be replicated. +- [materialized_postgresql_tables_list](../../operations/settings/settings.md#materialized-postgresql-tables-list) -3. `materialized_postgresql_allow_automatic_update` — Allow to reload table in the background, when schema changes are detected. Default: `0` (`false`). DDL queries on PostgreSQL side are not replicated via ClickHouse `MaterializedPostgreSQL` engine, because it is not allowed with PostgreSQL logical replication protocol, but the fact of DDL changes is detected transactionally. In this case the default behaviour is to stop replicating those tables once DDL is detected. However, if this setting is enabled, then, instead of stopping replication of those tables, they will be reloaded in the background via database snapshot without data losses and replication will continue for them. +- [materialized_postgresql_allow_automatic_update](../../operations/settings/settings.md#materialized-postgresql-allow-automatic-update) ``` sql -CREATE DATABASE test_database +CREATE DATABASE database1 ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password') SETTINGS materialized_postgresql_max_block_size = 65536, materialized_postgresql_tables_list = 'table1,table2,table3'; -SELECT * FROM test_database.table1; +SELECT * FROM database1.table1; ``` ## Requirements {#requirements} -1. Setting [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) to `logical` and `max_replication_slots` to at least `2` in the PostgreSQL config file. +1. The [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) setting must have a value `logical` and `max_replication_slots` parameter must have a value at least `2` in the PostgreSQL config file. 2. Each replicated table must have one of the following [replica identity](https://www.postgresql.org/docs/10/sql-altertable.html#SQL-CREATETABLE-REPLICA-IDENTITY): @@ -69,4 +74,13 @@ WHERE oid = 'postgres_table'::regclass; ``` !!! warning "Warning" - Replication of [**TOAST**](https://www.postgresql.org/docs/9.5/storage-toast.html) values is not supported. Default value for the data type will be used. + Replication of [**TOAST**](https://www.postgresql.org/docs/9.5/storage-toast.html) values is not supported. The default value for the data type will be used. + +## Example of Use {#example-of-use} + +``` sql +CREATE DATABASE postgresql_db +ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password'); + +SELECT * FROM postgresql_db.postgres_table; +``` diff --git a/docs/en/engines/table-engines/integrations/materialized-postgresql.md b/docs/en/engines/table-engines/integrations/materialized-postgresql.md index 142639507d6..1704563570b 100644 --- a/docs/en/engines/table-engines/integrations/materialized-postgresql.md +++ b/docs/en/engines/table-engines/integrations/materialized-postgresql.md @@ -5,42 +5,40 @@ toc_title: MaterializedPostgreSQL # MaterializedPostgreSQL {#materialize-postgresql} +The `MaterializedPostgreSQL` engine allows you to perform `SELECT` and `INSERT` queries on data that is stored on a remote PostgreSQL server. + ## Creating a Table {#creating-a-table} ``` sql -CREATE TABLE test.postgresql_replica (key UInt64, value UInt64) +CREATE TABLE postgresql_db.postgresql_replica (key UInt64, value UInt64) ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgresql_replica', 'postgres_user', 'postgres_password') PRIMARY KEY key; ``` - ## Requirements {#requirements} -- Setting `wal_level`to `logical` and `max_replication_slots` to at least `2` in the postgresql config file. +1. The [wal_level](https://www.postgresql.org/docs/current/runtime-config-wal.html) setting must have a value `logical` and `max_replication_slots` parameter must have a value at least `2` in the PostgreSQL config file. -- A table with engine `MaterializedPostgreSQL` must have a primary key - the same as a replica identity index (default: primary key) of a postgres table (See [details on replica identity index](../../database-engines/materialized-postgresql.md#requirements)). +2. A table with `MaterializedPostgreSQL` engine must have a primary key — the same as a replica identity index (by default: primary key) of a PostgreSQL table (see [details on replica identity index](../../database-engines/materialized-postgresql.md#requirements)). -- Only database `Atomic` is allowed. +3. Only database [Atomic](https://en.wikipedia.org/wiki/Atomicity_(database_systems)) is allowed. +## Virtual columns {#virtual-columns} -## Virtual columns {#creating-a-table} +- `_version` (type: UInt64) -- `_version` (`UInt64`) +- `_sign` (type: Int8) -- `_sign` (`Int8`) - -These columns do not need to be added, when table is created. They are always accessible in `SELECT` query. +These columns do not need to be added when a table is created. They are always accessible in `SELECT` query. `_version` column equals `LSN` position in `WAL`, so it might be used to check how up-to-date replication is. ``` sql -CREATE TABLE test.postgresql_replica (key UInt64, value UInt64) +CREATE TABLE postgresql_db.postgresql_replica (key UInt64, value UInt64) ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgresql_replica', 'postgres_user', 'postgres_password') PRIMARY KEY key; -SELECT key, value, _version FROM test.postgresql_replica; +SELECT key, value, _version FROM postgresql_db.postgresql_replica; ``` - -## Warning {#warning} - -1. **TOAST** values convertion is not supported. Default value for the data type will be used. +!!! warning "Warning" + Replication of [**TOAST**](https://www.postgresql.org/docs/9.5/storage-toast.html) values is not supported. The default value for the data type will be used. diff --git a/docs/en/operations/settings/settings.md b/docs/en/operations/settings/settings.md index 5042aeae162..40e1d72170c 100644 --- a/docs/en/operations/settings/settings.md +++ b/docs/en/operations/settings/settings.md @@ -3285,3 +3285,30 @@ Possible values: - 1 — The `LowCardinality` type is converted to the `DICTIONARY` type. Default value: `0`. + +## materialized_postgresql_max_block_size {#materialized-postgresql-max-block-size} + +Sets the number of rows collected in memory before flushing data into PostgreSQL database table. + +Possible values: + +- Positive integer. + +Default value: `65536`. + +## materialized_postgresql_tables_list {#materialized-postgresql-tables-list} + +Sets a comma-separated list of PostgreSQL database tables, which will be replicated via [MaterializedPostgreSQL](../../engines/database-engines/materialized-postgresql.md) database engine. + +Default value: empty list — means whole PostgreSQL database will be replicated. + +## materialized_postgresql_allow_automatic_update {#materialized-postgresql-allow-automatic-update} + +Allow reloading table in the background, when schema changes are detected. DDL queries on the PostgreSQL side are not replicated via ClickHouse [MaterializedPostgreSQL](../../engines/database-engines/materialized-postgresql.md) engine, because it is not allowed with PostgreSQL logical replication protocol, but the fact of DDL changes is detected transactionally. In this case, the default behaviour is to stop replicating those tables once DDL is detected. However, if this setting is enabled, then, instead of stopping the replication of those tables, they will be reloaded in the background via database snapshot without data losses and replication will continue for them. + +Possible values: + +- 0 — The table is not automatically updated in the background, when schema changes are detected. +- 1 — The table is automatically updated in the background, when schema changes are detected. + +Default value: `0`. diff --git a/docs/ru/engines/database-engines/materialized-postgresql.md b/docs/ru/engines/database-engines/materialized-postgresql.md index 8c366ba14b6..7ec0df20804 100644 --- a/docs/ru/engines/database-engines/materialized-postgresql.md +++ b/docs/ru/engines/database-engines/materialized-postgresql.md @@ -14,27 +14,32 @@ toc_title: MaterializedPostgreSQL ## Создание базы данных {#creating-a-database} ``` sql -CREATE DATABASE test_database -ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password'); - -SELECT * FROM test_database.postgres_table; +CREATE DATABASE [IF NOT EXISTS] db_name [ON CLUSTER cluster] +ENGINE = MaterializedPostgreSQL('host:port', ['database' | database], 'user', 'password') [SETTINGS ...] ``` +**Параметры движка** + +- `host:port` — адрес сервера PostgreSQL. +- `database` — имя базы данных на удалённом сервере. +- `user` — пользователь PostgreSQL. +- `password` — пароль пользователя. + ## Настройки {#settings} -1. `materialized_postgresql_max_block_size` — задает максимальное количество строк, собранных перед вставкой данных в таблицу. По умолчанию: `65536`. +- [materialized_postgresql_max_block_size](../../operations/settings/settings.md#materialized-postgresql-max-block-size) -2. `materialized_postgresql_tables_list` — задает список таблиц для движка баз данных `MaterializedPostgreSQL`. По умолчанию: `whole database`. +- [materialized_postgresql_tables_list](../../operations/settings/settings.md#materialized-postgresql-tables-list) -3. `materialized_postgresql_allow_automatic_update` — позволяет автоматически обновить таблицу в фоновом режиме при обнаружении изменений схемы. По умолчанию: `0` (`false`). +- [materialized_postgresql_allow_automatic_update](../../operations/settings/settings.md#materialized-postgresql-allow-automatic-update) ``` sql -CREATE DATABASE test_database +CREATE DATABASE database1 ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password') SETTINGS materialized_postgresql_max_block_size = 65536, materialized_postgresql_tables_list = 'table1,table2,table3'; -SELECT * FROM test_database.table1; +SELECT * FROM database1.table1; ``` ## Требования {#requirements} @@ -69,4 +74,13 @@ WHERE oid = 'postgres_table'::regclass; ``` !!! warning "Предупреждение" - Преобразование **TOAST**-значений не поддерживается. Для типа данных будет использоваться значение по умолчанию. + Репликация **TOAST**-значений не поддерживается. Для типа данных будет использоваться значение по умолчанию. + +## Пример использования {#example-of-use} + +``` sql +CREATE DATABASE postgresql_db +ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgres_user', 'postgres_password'); + +SELECT * FROM postgresql_db.postgres_table; +``` diff --git a/docs/ru/engines/table-engines/integrations/materialized-postgresql.md b/docs/ru/engines/table-engines/integrations/materialized-postgresql.md new file mode 100644 index 00000000000..ec56084c338 --- /dev/null +++ b/docs/ru/engines/table-engines/integrations/materialized-postgresql.md @@ -0,0 +1,44 @@ +--- +toc_priority: 12 +toc_title: MaterializedPostgreSQL +--- + +# MaterializedPostgreSQL {#materialize-postgresql} + +Движок `MaterializedPostgreSQL` позволяет выполнять запросы `SELECT` и `INSERT` над данными, хранящимися на удалённом PostgreSQL сервере. + +## Создание таблицы {#creating-a-table} + +``` sql +CREATE TABLE postgresql_db.postgresql_replica (key UInt64, value UInt64) +ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgresql_replica', 'postgres_user', 'postgres_password') +PRIMARY KEY key; +``` + +## Требования {#requirements} + +1. Настройка [wal_level](https://postgrespro.ru/docs/postgrespro/10/runtime-config-wal) должна иметь значение `logical`, параметр `max_replication_slots` должен быть равен по меньшей мере `2` в конфигурационном файле в PostgreSQL. + +2. Таблица, созданная с помощью движка `MaterializedPostgreSQL`, должна иметь первичный ключ — такой же, как индекс идентичности реплики (по умолчанию: первичный ключ) таблицы PostgreSQL (смотрите [индекс идентичности реплики](../../database-engines/materialized-postgresql.md#requirements)). + +3. Допускается только база данных [Atomic](https://en.wikipedia.org/wiki/Atomicity_(database_systems)). + +## Виртуальные столбцы {#virtual-columns} + +- `_version` (тип: UInt64) + +- `_sign` (тип: Int8) + +Эти столбцы не нужно добавлять при создании таблицы. Они всегда доступны в `SELECT` запросе. +Столбец `_version` равен позиции `LSN` в `WAL`, поэтому его можно использовать для проверки актуальности репликации. + +``` sql +CREATE TABLE postgresql_db.postgresql_replica (key UInt64, value UInt64) +ENGINE = MaterializedPostgreSQL('postgres1:5432', 'postgres_database', 'postgresql_replica', 'postgres_user', 'postgres_password') +PRIMARY KEY key; + +SELECT key, value, _version FROM postgresql_db.postgresql_replica; +``` + +!!! warning "Предупреждение" + Репликация **TOAST**-значений не поддерживается. Для типа данных будет использоваться значение по умолчанию. diff --git a/docs/ru/operations/settings/settings.md b/docs/ru/operations/settings/settings.md index 9e926a63c62..547060ae970 100644 --- a/docs/ru/operations/settings/settings.md +++ b/docs/ru/operations/settings/settings.md @@ -3124,3 +3124,30 @@ SETTINGS index_granularity = 8192 │ - 1 — тип `LowCardinality` конвертируется в тип `DICTIONARY`. Значение по умолчанию: `0`. + +## materialized_postgresql_max_block_size {#materialized-postgresql-max-block-size} + +Задает максимальное количество строк, собранных в памяти перед вставкой данных в таблицу базы данных PostgreSQL. + +Возможные значения: + +- Положительное целое число. + +Значение по умолчанию: `65536`. + +## materialized_postgresql_tables_list {#materialized-postgresql-tables-list} + +Задает список таблиц базы данных PostgreSQL, разделенных запятыми, которые будут реплицироваться с помощью движка базы данных [MaterializedPostgreSQL](../../engines/database-engines/materialized-postgresql.md). + +Значение по умолчанию: пустой список — база данных PostgreSQL будет полностью реплицирована. + +## materialized_postgresql_allow_automatic_update {#materialized-postgresql-allow-automatic-update} + +Позволяет автоматически обновить таблицу в фоновом режиме при обнаружении изменений схемы. DDL-запросы на стороне сервера PostgreSQL не реплицируются с помощью движка ClickHouse [MaterializedPostgreSQL](../../engines/database-engines/materialized-postgresql.md), поскольку это запрещено протоколом логической репликации PostgreSQL, но факт DDL-измененений обнаруживается транзакционно. В этом случае по умолчанию прекращается репликация этих таблиц после обнаружения DDL. Однако, если эта настройка включена, то вместо остановки репликации этих таблиц они будут перезагружены в фоновом режиме с помощью снимка базы данных без потери информации, и репликация для них будет продолжена. + +Возможные значения: + +- 0 — таблица не обновляется автоматически в фоновом режиме при обнаружении изменений схемы. +- 1 — таблица обновляется автоматически в фоновом режиме при обнаружении изменений схемы. + +Значение по умолчанию: `0`.