> ## Documentation Index > Fetch the complete documentation index at: https://private-7c7dfe99-parallel-read-in-order-multi-part.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Документация по движку таблицы MySQL # Движок таблицы MySQL Движок MySQL позволяет выполнять запросы `SELECT` и `INSERT` к данным, которые хранятся на удалённом сервере MySQL. ## Создание таблицы ```sql theme={null} CREATE TABLE [IF NOT EXISTS] [db.]table_name [ON CLUSTER cluster] ( name1 [type1] [DEFAULT|MATERIALIZED|ALIAS expr1], name2 [type2] [DEFAULT|MATERIALIZED|ALIAS expr2], ... ) ENGINE = MySQL({host:port, database, table, user, password[, replace_query, on_duplicate_clause] | named_collection[, option=value [,..]]}) SETTINGS [ connection_pool_size=16, ] [ connection_max_tries=3, ] [ connection_wait_timeout=5, ] [ connection_auto_close=true, ] [ connect_timeout=10, ] [ read_write_timeout=300, ] [ enable_compression=false ] ; ``` См. подробное описание запроса [CREATE TABLE](/ru/reference/statements/create/table). Структура таблицы может отличаться от структуры исходной таблицы MySQL: * Имена столбцов должны совпадать с именами в исходной таблице MySQL, но можно использовать только часть этих столбцов и в любом порядке. * Типы столбцов могут отличаться от типов в исходной таблице MySQL. ClickHouse пытается [преобразовать](/ru/reference/engines/database-engines/mysql#data_types-support) значения в типы данных ClickHouse. * Настройка [external\_table\_functions\_use\_nulls](/ru/reference/settings/session-settings/external-table#external_table_functions_use_nulls) определяет, как обрабатывать столбцы Nullable. Значение по умолчанию: 1. Если установлено значение 0, функция таблицы не создаёт столбцы типа Nullable и вместо NULL выполняет вставку значений по умолчанию. Это также применимо к значениям NULL внутри массивов. **Параметры движка** * `host:port` — адрес сервера MySQL. * `database` — имя удалённой базы данных. * `table` — имя удалённой таблицы или запрос, передаваемый в MySQL как есть (см. [Передача запроса вместо имени таблицы](#passing-a-query)). * `user` — пользователь MySQL. * `password` — пароль пользователя. * `replace_query` — флаг, преобразующий запросы `INSERT INTO` в `REPLACE INTO`. Если `replace_query=1`, запрос заменяется. * `on_duplicate_clause` — выражение `ON DUPLICATE KEY on_duplicate_clause`, которое добавляется к запросу `INSERT`. Пример: `INSERT INTO t (c1,c2) VALUES ('a', 2) ON DUPLICATE KEY UPDATE c2 = c2 + 1`, где `on_duplicate_clause` — это `UPDATE c2 = c2 + 1`. См. [документацию MySQL](https://dev.mysql.com/doc/refman/8.0/en/insert-on-duplicate.html), чтобы узнать, какие `on_duplicate_clause` можно использовать с секцией `ON DUPLICATE KEY`. Чтобы указать `on_duplicate_clause`, нужно передать `0` в параметр `replace_query`. Если одновременно передать `replace_query = 1` и `on_duplicate_clause`, ClickHouse сгенерирует исключение. Аргументы также можно передавать с помощью [именованных коллекций](/ru/concepts/features/configuration/server-config/named-collections). В этом случае `host` и `port` следует указывать отдельно. Этот подход рекомендуется для продакшн-среды. Простые условия `WHERE`, такие как `=, !=, >, >=, <, <=`, выполняются на сервере MySQL. Остальные условия и ограничение выборки `LIMIT` выполняются в ClickHouse только после завершения запроса к MySQL. ## TLS/SSL Учетные данные для зашифрованного соединения с MySQL передаются как ключи именованной коллекции (или как аргументы «ключ-значение»): | Параметр | Описание | | - | - | | `ssl_ca_pem` | Содержимое CA‑сертификата, по которому проверяется сертификат сервера MySQL. | | `ssl_cert_pem` | Содержимое клиентского сертификата для аутентификации на основе сертификата. | | `ssl_key_pem` | Содержимое закрытого ключа, соответствующего `ssl_cert_pem`. | Значения — это содержимое соответствующих PEM-файлов, которое можно скопировать в именованную коллекцию или в запрос. Они маскируются в журналах и запросах `SHOW` так же, как пароли. Эти же учетные данные можно указать в виде путей к файлам на сервере — в `ssl_ca`, `ssl_cert` и `ssl_key`, — но **только в именованной коллекции, определенной в файле конфигурации сервера**; такое значение нельзя переопределить в запросе. Сервер открывает эти файлы со своими привилегиями, поэтому прием пути из SQL позволил бы любому пользователю, который может определить источник MySQL, исследовать локальную файловую систему и проходить аутентификацию с сертификатом и ключом, к которым у него нет прав на чтение. ```xml theme={null} mysql-host 3306 mysql_user **** /etc/clickhouse-server/mysql-ca.crt ``` ## Передача запроса вместо имени таблицы Вместо имени таблицы аргумент `table` может представлять собой запрос `SELECT`, который передаётся в MySQL как есть. Структура таблицы определяется по результату запроса. Запрос можно записать либо как подзапрос, либо обернуть в функцию `query`: ```sql theme={null} CREATE TABLE mysql_table ENGINE = MySQL('localhost:3306', 'test', (SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0), 'user', 'password'); CREATE TABLE mysql_table ENGINE = MySQL('localhost:3306', 'test', query('SELECT a, b FROM t1 JOIN t2 USING (id) WHERE a > 0'), 'user', 'password'); ``` Это позволяет передать выполнение JOIN, агрегаций и любой другой обработки в MySQL. Такая таблица доступна только для чтения: `INSERT` в неё не допускается. Тот же синтаксис поддерживает табличная функция [`mysql`](/ru/reference/functions/table-functions/mysql). Форма подзапроса `(SELECT ...)` разбирается в ClickHouse и перед отправкой на сервер повторно сериализуется в диалекте MySQL (с экранированием идентификаторов обратными кавычками). Поэтому она должна быть корректным ClickHouse SQL. Чтобы передать синтаксис, специфичный для MySQL и не разбираемый ClickHouse, используйте форму `query('...')`, текст которой отправляется в MySQL дословно. Любые внешние `WHERE`, `LIMIT`, агрегация и т. д. из окружающего запроса к ClickHouse **не** проталкиваются в переданный запрос — они применяются в ClickHouse после получения полного результата запроса. Чтобы ограничить объём данных, читаемых из MySQL, поместите фильтр внутрь переданного запроса. При [`external_table_strict_query = 1`](/ru/reference/settings/session-settings/external-table#external_table_strict_query) внешний фильтр по столбцам таблицы приводит к исключению вместо локального применения, поскольку его нельзя протолкнуть в переданный запрос. Проверка охватывает предикат верхнего уровня в `WHERE` и каждый конъюнкт `AND` верхнего уровня. `PREWHERE` по столбцам этой таблицы не относится к области действия этой настройки: данный движок таблицы не поддерживает `PREWHERE`, и такой запрос отклоняется с ошибкой `ILLEGAL_PREWHERE` независимо от настройки. Проверка выполняется только там, где фильтр в принципе может быть протолкнут: когда эта таблица является единственной таблицей запроса, с любой стороны `INNER JOIN` или на сохраняющей стороне внешнего JOIN (левая сторона `LEFT JOIN`, правая сторона `RIGHT JOIN`). На несохраняющей стороне `LEFT`/`RIGHT JOIN` и с любой стороны `FULL JOIN` ничего не проталкивается и ничего не проверяется, поэтому фильтр по столбцам этой таблицы применяется локально после JOIN даже в строгом режиме. Там, где проверка выполняется, предикат, ссылающийся на другие таблицы, соединённые в окружающем запросе, не проталкивается и исключается из проверки — как если он ссылается только на присоединённую сторону, так и если смешивает её с этой таблицей внутри одного выражения без `AND` (например, `OR`); такой предикат сохраняет обычную точку вычисления в ClickHouse (`WHERE` после JOIN, `PREWHERE` до него) и не отклоняется. Поддерживается несколько реплик, которые должны быть перечислены через `|`. Например: ```sql theme={null} CREATE TABLE test_replicas (id UInt32, name String, age UInt32, money UInt32) ENGINE = MySQL(`mysql{2|3|4}:3306`, 'clickhouse', 'test_replicas', 'root', 'clickhouse'); ``` ## Пример использования Создайте таблицу в MySQL: ```text theme={null} mysql> CREATE TABLE `test`.`test` ( -> `int_id` INT NOT NULL AUTO_INCREMENT, -> `int_nullable` INT NULL DEFAULT NULL, -> `float` FLOAT NOT NULL, -> `float_nullable` FLOAT NULL DEFAULT NULL, -> PRIMARY KEY (`int_id`)); Query OK, 0 rows affected (0,09 sec) mysql> insert into test (`int_id`, `float`) VALUES (1,2); Query OK, 1 row affected (0,00 sec) mysql> select * from test; +------+----------+-----+----------+ | int_id | int_nullable | float | float_nullable | +------+----------+-----+----------+ | 1 | NULL | 2 | NULL | +------+----------+-----+----------+ 1 row in set (0,00 sec) ``` Создайте таблицу в ClickHouse, используя обычные аргументы: ```sql theme={null} CREATE TABLE mysql_table ( `float_nullable` Nullable(Float32), `int_id` Int32 ) ENGINE = MySQL('localhost:3306', 'test', 'test', 'bayonet', '123') ``` Или с помощью [именованных коллекций](/ru/concepts/features/configuration/server-config/named-collections): ```sql theme={null} CREATE NAMED COLLECTION creds AS host = 'localhost', port = 3306, database = 'test', user = 'bayonet', password = '123'; CREATE TABLE mysql_table ( `float_nullable` Nullable(Float32), `int_id` Int32 ) ENGINE = MySQL(creds, table='test') ``` Получение данных из таблицы MySQL: ```sql theme={null} SELECT * FROM mysql_table ``` ```text theme={null} ┌─float_nullable─┬─int_id─┐ │ ᴺᵁᴸᴸ │ 1 │ └────────────────┴────────┘ ``` ## Настройки Настройки по умолчанию не очень эффективны, поскольку при них даже не переиспользуются соединения. Эти настройки позволяют увеличить число запросов, выполняемых сервером в секунду. ### `connection_auto_close` Позволяет автоматически закрывать соединение после выполнения запроса, то есть отключать его повторное использование. Возможные значения: * 1 — автоматическое закрытие соединения разрешено, поэтому его повторное использование отключено * 0 — автоматическое закрытие соединения не разрешено, поэтому его повторное использование включено Значение по умолчанию: `1`. ### `connection_max_tries` Задаёт число повторных попыток в пуле с failover. Возможные значения: * Положительное целое число. * 0 — Для пула с failover повторные попытки не выполняются. Значение по умолчанию: `3`. ### `connection_pool_size` Размер пула соединений (если все соединения заняты, запрос будет ждать, пока одно из них не освободится). Возможные значения: * Положительное целое число. Значение по умолчанию: `16`. ### `connection_wait_timeout` Тайм-аут (в секундах) ожидания свободного соединения (если уже имеется `connection_pool_size` активных соединений), 0 — не ждать. Возможные значения: * Положительное целое число. Значение по умолчанию: `5`. ### `connect_timeout` Тайм-аут подключения (в секундах). Возможные значения: * Положительное целое число. Значение по умолчанию: `10`. ### `read_write_timeout` Тайм-аут операций чтения/записи (в секундах). Возможные значения: * Положительное целое число. Значение по умолчанию: `300`. ### `enable_compression` Включает сжатие для соединения по протоколу MySQL. Значение по умолчанию: `false`. Этот параметр применяется к: * движку таблицы `MySQL`; * движку базы данных `MySQL`; * табличной функции `mysql`; * именованным коллекциям, используемым в интеграциях MySQL. Когда этот параметр включен, ClickHouse запрашивает сжатие для соединения. Пример: ```sql theme={null} CREATE TABLE mysql_engine_compression ( id UInt32, name String, age UInt32, money UInt32 ) ENGINE = MySQL('mysql80:3306', 'clickhouse', 'test_table', 'root', 'password') SETTINGS enable_compression = 1; ``` ## См. также * [Табличная функция MySQL](/ru/reference/functions/table-functions/mysql) * [Использование MySQL в качестве источника данных для словаря](/ru/reference/statements/create/dictionary/sources/mysql)