MySQL коннектор#

Примечание

Ниже приведена оригинальная документация Trino. Скоро мы ее переведем на русский язык и дополним полезными примерами.

The MySQL connector allows querying and creating tables in an external MySQL instance. This can be used to join data between different systems like MySQL and Hive, or between two different MySQL instances.

Требования#

To connect to MySQL, you need:

MySQL 5.7, 8.0 or higher.
Network access from the Trino coordinator and workers to MySQL. Port 3306 is the default port.

Конфигурация#

To configure the MySQL connector, create a catalog properties file in etc/catalog named, for example, example.properties, to mount the MySQL connector as the mysql catalog. Create the file with the following contents, replacing the connection properties as appropriate for your setup:

connector.name=mysql
connection-url=jdbc:mysql://example.net:3306
connection-user=root
connection-password=secret

The connection-url defines the connection information and parameters to pass to the MySQL JDBC driver. The supported parameters for the URL are available in the MySQL Developer Guide.

For example, the following connection-url allows you to require encrypted connections to the MySQL server:

connection-url=jdbc:mysql://example.net:3306?sslMode=REQUIRED

The connection-user and connection-password are typically required and determine the user credentials for the connection, often a service user. You can use secrets to avoid actual values in the catalog properties files.

Connection security#

If you have TLS configured with a globally-trusted certificate installed on your data source, you can enable TLS between your cluster and the data source by appending a parameter to the JDBC connection string set in the connection-url catalog configuration property.

For example, with version 8.0 of MySQL Connector/J, use the sslMode parameter to secure the connection with TLS. By default the parameter is set to PREFERRED which secures the connection if enabled by the server. You can also set this parameter to REQUIRED which causes the connection to fail if TLS is not established.

You can set the sslMode paremeter in the catalog configuration file by appending it to the connection-url configuration property:

connection-url=jdbc:mysql://example.net:3306/?sslMode=REQUIRED

For more information on TLS configuration options, see the MySQL JDBC security documentation.

Аутентификация в источнике данных#

Вы можете предоставить имя пользователя и пароль для подключения к источнику данных несколькими способами:

INLINE - в файле конфигурации каталога (в том числе, используя секреты, что бы не хранить значения в открытом виде).
FILE - в отдельном properties файле.
KEYSTORE - в зашифрованном keystore файле.
Из extra credentials клиента CedrusData.

The following table describes configuration properties for connection credentials:

Property name	Description
`credential-provider.type`	Тип credential provider. Допустимые значения: `INLINE` (значение по умолчанию), `FILE` или `KEYSTORE`.
`connection-user`	Имя пользователя для подключения к источнику. Используется при `credential-provider.type=INLINE`.
`connection-password`	Пароль для подключения к источнику. Используется при `credential-provider.type=INLINE`.
`connection-credential-file`	Путь к properties файлу, содержащему параметры `connection-user` and `connection-password`. Используется при `credential-provider.type=FILE`.
`keystore-file-path`	Путь к keystore файлу, из которого следует прочитать имя пользователя и пароль. Используется при `credential-provider.type=KEYSTORE`.
`keystore-type`	Тип keystore файла. Например, `JKS` или `PEM`.
`keystore-password`	Пароль к keystore файлу.
`keystore-user-credential-name`	Имя keystore entity, содержащей имя пользователя для подключения к источнику.
`keystore-user-credential-password`	Пароль к keystore entity, содержащей имя пользователя для подключения к источнику
`keystore-password-credential-name`	Имя keystore entity, содержащей пароль для подключения к источнику.
`keystore-password-credential-password`	Пароль к keystore entity, содержащей пароль для подключения к источнику.
`user-credential-name`	Имя параметра extra credentials, значение которого следует использовать в качестве имени пользователя. См. `extraCredentials` в разделе Параметры подключения.
`password-credential-name`	Имя параметра extra credentials, значение которого следует использовать в качестве пароля. См. `extraCredentials` в разделе Параметры подключения.

Multiple MySQL servers#

You can have as many catalogs as you need, so if you have additional MySQL servers, simply add another properties file to etc/catalog with a different name, making sure it ends in .properties. For example, if you name the property file sales.properties, Trino creates a catalog named sales using the configured connector.

Общие параметры конфигурации#

Общие параметры конфигурации каталога приведены в таблице ниже:

Название	Описание	Значение по умолчанию
`case-insensitive-name-matching`	Включить поддержку case insensitive идентификаторов.	`false`
`case-insensitive-name-matching.cache-ttl`	Время жизни закэшированных метаданных о case insensitive идентификаторах.	`1m`
`case-insensitive-name-matching.config-file`	Путь к файлу конфигурации в формате JSON, который позволяет разрешать конфликты имен между case insensitive схемами и таблицами.	`null`
`case-insensitive-name-matching.config-file.refresh-period`	Частота проверки обновлений файла `case-insensitive-name-matching.config-file`.	`0` (refresh disabled)
`metadata.cache-ttl`	Время жизни закэшированных метаданных. Положительное значение включает кэширование.	`0` (caching disabled)
`metadata.cache-missing`	Кэшировать ли информацию о том, что для используемых таблиц и колонок отсутствуют статистики. Включение данного параметра может ускорить планирование некоторых запросов. Однако, если информация об отсутствии статистик для конкретного объекта СУБД закэширована, но статистики стали доступны позднее (например, была запущена команда `ANALYZE`), CedrusData не сможет использовать статистики, пока не истечет время жизни закэшированной записи в соответствии с `metadata.cache-ttl`.	`false`
`metadata.cache-maximum-size`	Максимальное количество объектов, хранящихся в metadata cache.	`10000`
`write.batch-size`	Максимальное количество команд в batch операциях записи данных. Изменение данного параметра не рекомендовано, так как оно может негативно сказаться на производительности.	`1000`
`dynamic-filtering.enabled`	Использовать ли динамические фильтры при работе с JDBC источником.	`true`
`dynamic-filtering.wait-timeout`	Максимальное время ожидания готовности динамических фильтров с build стороны оператора join перед запуском JDBC запроса к источнику. Увеличение таймаута может позволить CedrusData выполнить запрос к источнику с более селективными фильтрами, но в то же время может увеличить latency некоторых запросов.	`20s`

Domain compaction threshold#

CedrusData позволяет делегировать применение предикатов источнику данных (pushdown). Во многих случаях это существенно уменьшает количество записей, которые возвращает источник, и улучшает производительность. Однако, pushdown сложных предикатов (например, выражение IN со множеством значений) может негативно сказаться на производительности. При достижении порога сложности предиката, CedrusData автоматически преобразует предикат к более компактной форме. Например, предикат a IN (1, 2, ..., 100) может быть преобразован в a BETWEEN 1 AND 100. В большинстве случаев такое преобразование улучшает производительность запросов. Однако, в некоторых случаях может быть предпочтительнее передать сложный предикат в неизменном виде, так как источник данных может его обработать эффективнее, чем преобразованный предикат.

Вы можете увеличить значение порога сложности, что бы CedrusData передавал предикат в источник без изменений. Используйте для этого параметр конфигурации каталога domain-compaction-threshold или параметр сессии domain_compaction_threshold catalog session property.

Процедуры#

system.flush_metadata_cache()

Очистить кэш JDBC метаданных. Команда ниже очищает кэш метаданных всех схем в каталоге example.
```
USE example.example_schema;
CALL system.flush_metadata_cache();
```

Case insensitive идентификаторы#

Когда параметр конфигурации case-insensitive-name-matching установлен в true, CedrusData может обращаться к схемам и таблицам источника, имена которых на являются lowercase. Для этого CedrusData сопоставляет lowercase название схемы или таблицы с ее реальным названием в источнике данных. Например, если таблица в источнике данных имеет название Customers, CedrusData позволяет обратиться к ней по имени customers.

В случае, если источник имеет несколько объектов, имена которых отличаются только регистром (например, Customer и customer), CedrusData не может автоматически определить, к какому объекту обращаться.

В этом случае вы можете явно задать сопоставление имен в помощью файла в JSON формате, путь к которому следует указать в параметре конфигурации каталога case-insensitive-name-matching.config-file. Например:

{
  "schemas": [
    {
      "remoteSchema": "CaseSensitiveName",
      "mapping": "case_insensitive_1"
    },
    {
      "remoteSchema": "cASEsENSITIVEnAME",
      "mapping": "case_insensitive_2"
    }],
  "tables": [
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "tablex",
      "mapping": "table_1"
    },
    {
      "remoteSchema": "CaseSensitiveName",
      "remoteTable": "TABLEX",
      "mapping": "table_2"
    }]
}

В данном случае, при обращении из CedrusData к схеме case_insensitive_1, запрос будет переадресован к схеме источника CaseSensitiveName, а при обращении из CedrusData к таблице case_insensitive_1.table_1 запрос будет переадресован к таблице источника CaseSensitiveName.tablex.

По умолчанию если вы изменяете содержимое данного файла, экземпляр CedrusData должен быть перезапущен, что бы применить изменения. Если вы хотите изменять содержимое файла без перезапуска CedrusData, вы можете установить параметр конфигурации case-insensitive-name-mapping.refresh-period, который определяет частоту повторного чтения данного файла.

case-insensitive-name-mapping.refresh-period=30s

Нетракзакционный INSERT#

Коннектор поддерживает добавление записей в источник с помощью команды INSERT statements. По умолчанию CedrusData осуществляет запись данных, используя временную таблицу, что обеспечивает транзакционные гарантии: в источник будут записаны либо все данные, либо не будет записано ничего (в случае возникновения ошибки). Однако,

Вы можете осуществлять запись данных в таблицу источника напрямую, минуя временную таблицу. Для этого установите параметр конфигурации каталога insert.non-transactional-insert.enabled или параметр сессии non_transactional_insert в значение true. Изменение данного параметра может улучшает производительность записи, но так же может привести данные в источнике в неопределенное состояние при возникновении ошибки в момент записи. Например, если при вставке 10 записей в таблицу источника в середине процесса произошла ошибка, откат вставки уже сохраненных записей может оказаться невозможным, и после выполнения команды источник будет содержать только часть записей.

Type mapping#

Because Trino and MySQL each support types that the other does not, this connector modifies some types when reading or writing data. Data types may not map the same way in both directions between Trino and the data source. Refer to the following sections for type mapping in each direction.

MySQL to Trino type mapping#

The connector maps MySQL types to the corresponding Trino types following this table:

MySQL to Trino type mapping#
MySQL database type	Trino type	Notes
`BIT`	`BOOLEAN`
`BOOLEAN`	`TINYINT`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`DOUBLE PRECISION`	`DOUBLE`
`FLOAT`	`REAL`
`REAL`	`REAL`
`DECIMAL(p, s)`	`DECIMAL(p, s)`	See MySQL DECIMAL type handling
`CHAR(n)`	`CHAR(n)`
`VARCHAR(n)`	`VARCHAR(n)`
`TINYTEXT`	`VARCHAR(255)`
`TEXT`	`VARCHAR(65535)`
`MEDIUMTEXT`	`VARCHAR(16777215)`
`LONGTEXT`	`VARCHAR`
`ENUM(n)`	`VARCHAR(n)`
`BINARY`, `VARBINARY`, `TINYBLOB`, `BLOB`, `MEDIUMBLOB`, `LONGBLOB`	`VARBINARY`
`JSON`	`JSON`
`DATE`	`DATE`
`TIME(n)`	`TIME(n)`
`DATETIME(n)`	`DATETIME(n)`
`TIMESTAMP(n)`	`TIMESTAMP(n)`

No other types are supported.

Trino to MySQL type mapping#

The connector maps Trino types to the corresponding MySQL types following this table:

Trino to MySQL type mapping#
Trino type	MySQL type	Notes
`BOOLEAN`	`TINYINT`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INTEGER`
`BIGINT`	`BIGINT`
`REAL`	`REAL`
`DOUBLE`	`DOUBLE PRECISION`
`DECIMAL(p, s)`	`DECIMAL(p, s)`	MySQL DECIMAL type handling
`CHAR(n)`	`CHAR(n)`
`VARCHAR(n)`	`VARCHAR(n)`
`JSON`	`JSON`
`DATE`	`DATE`
`TIME(n)`	`TIME(n)`
`TIMESTAMP(n)`	`TIMESTAMP(n)`

No other types are supported.

Обработка DECIMAL типов#

Тип данных DECIMAL без явного указания precision ил scale сопоставляется с типом данных CedrusData DECIMAL с precision 38 и scale 0. Scale может быть изменен путем установки параметра конфигурации коннектора decimal-mapping или параметра сессии decimal_mapping в значение allow_overflow. В этом случае scale типа будет равен значению параметра конфигурации коннектора decimal-default-scale или параметра сессии decimal_default_scale. Precision всегда равен 38.

Если DECIMAL значение не умещается в заданные precision и scale без округления, CedrusData сгенерирует ошибку. Вы можете изменить данное поведение, разрешив автоматическое округление значение с помощью параметра конфигурации коннектора decimal-rounding-mode или параметра сессии decimal_rounding_mode. Допустимые значения: UNNECESSARY (the default), UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, HALF_EVEN. Данные значения соответствуют поведению RoundingMode в Java 17.

Конфигурация приведения типов#

Следующие параметры конфигурации могут быть использованы для изменения логики приведения типов.

Название	Описание	Значение по умолчанию
`unsupported-type-handling`	Как обрабатывать колонки неподдерживаемых типов: * `IGNORE`, не обрабатывать колонку. * `CONVERT_TO_VARCHAR`, привести значение колонки к `VARCHAR` неограниченной длины. Соответствующий параметр сессии: `unsupported_type_handling`.	`IGNORE`
`jdbc-types-mapped-to-varchar`	Список типов данных источника, которые должны быть принудительно приведены к `VARCHAR` неограниченной длины (даже если указанный тип поддерживается коннектором).

Querying MySQL#

The MySQL connector provides a schema for every MySQL database. You can see the available MySQL databases by running SHOW SCHEMAS:

SHOW SCHEMAS FROM example;

If you have a MySQL database named web, you can view the tables in this database by running SHOW TABLES:

SHOW TABLES FROM example.web;

You can see a list of the columns in the clicks table in the web database using either of the following:

DESCRIBE example.web.clicks;
SHOW COLUMNS FROM example.web.clicks;

Finally, you can access the clicks table in the web database:

SELECT * FROM example.web.clicks;

If you used a different name for your catalog properties file, use that catalog name instead of example in the above examples.

SQL support#

The connector provides read access and write access to data and metadata in the MySQL database. In addition to the globally available and read operation statements, the connector supports the following statements:

SQL DELETE#

Команда DELETE с выражением WHERE работает только в случае, когда выполнение предиката может быть полностью делегировано источнику.

Table functions#

The connector provides specific table functions to access MySQL.

`query(varchar) -> table`#

The query function allows you to query the underlying database directly. It requires syntax native to MySQL, because the full query is pushed down and processed in MySQL. This can be useful for accessing native features which are not available in Trino or for improving query performance in situations where running a query natively may be faster.

Примечание

Полиморфные табличные функции не всегда сохраняют оригинальный порядок записей в результате запроса. Есть табличная функция содержит запрос с ORDER BY, результат работы функции может вернуть записи в ином порядке. Для восстановления требуемого порядка используйте ORDER BY в запросе CedrusData.

For example, group and concatenate all employee IDs by manager ID:

SELECT
  *
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        manager_id, GROUP_CONCAT(employee_id)
      FROM
        company.employees
      GROUP BY
        manager_id'
    )
  );

Performance#

The connector includes a number of performance improvements, detailed in the following sections.

Table statistics#

The MySQL connector can use table and column statistics for cost based optimizations, to improve query processing performance based on the actual data in the data source.

The statistics are collected by MySQL and retrieved by the connector.

The table-level statistics are based on MySQL’s INFORMATION_SCHEMA.TABLES table. The column-level statistics are based on MySQL’s index statistics INFORMATION_SCHEMA.STATISTICS table. The connector can return column-level statistics only when the column is the first column in some index.

MySQL database can automatically update its table and index statistics. In some cases, you may want to force statistics update, for example after creating new index, or after changing data in the table. You can do that by executing the following statement in MySQL Database.

ANALYZE TABLE table_name;

Примечание

MySQL and Trino may use statistics information in different ways. For this reason, the accuracy of table and column statistics returned by the MySQL connector might be lower than than that of others connectors.

Improving statistics accuracy

You can improve statistics accuracy with histogram statistics (available since MySQL 8.0). To create histogram statistics execute the following statement in MySQL Database.

ANALYZE TABLE table_name UPDATE HISTOGRAM ON column_name1, column_name2, ...;

Refer to MySQL documentation for information about options, limitations and additional considerations.

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Примечание

Коннектор осуществляет pushdown для улучшения производительности запросов. Вместо с тем, коннектор не будет делать pushdown конкретной операции, если это может привести к некорректным результатам. Таким образом коннектор предпочитает корректность производительности. В некоторых случаях коннекторы могут предоставлять дополнительные параметры конфигурации, которые разрешают pushdown небезопасных операций, но только при явном указании соответствующего параметра пользователем.

Join pushdown#

Коннектор поддерживает Join pushdown в режимах AUTOMATIC (значение по умолчанию) и EAGER.

В режиме AUTOMATIC коннектор принимает решение о join pushdown на основе предполагаемой стоимости запроса с и без join pushdown. Join pushdown происходит только тогда, когда доступные Статистики оптимизатора позволяют предположить, что join pushdown приведет к улучшению производительности. Если статистики задействованных таблиц и колонок недоступны, join pushdown не будет произведен, что бы избежать потенциального ухудшения производительности.

В режиме EAGER join pushdown происходит всегда, когда это допустимо коннектором с точки зрения корректности, даже если соответствующие статистики недоступны. По этой причине использование режима EAGER рекомендовано только для тестирования и отладки.

Таблица ниже содержит параметры конфигурации, относящиеся к cost-based join pushdown:

Название	Описание	Значение по умолчанию
`join-pushdown.enabled`	Разрешать join pushdown или нет. Соответствующий параметр сессии: `join_pushdown_enabled`.	`true`
`join-pushdown.strategy`	Стратегия принятия решения о join pushdown. Допустимые значения: `AUTOMATIC`, `EAGER`.	`AUTOMATIC`

Predicate pushdown support#

The connector does not support pushdown of any predicates on columns with textual types like CHAR or VARCHAR. This ensures correctness of results since the data source may compare strings case-insensitively.

In the following example, the predicate is not pushed down for either query since name is a column of type VARCHAR:

SELECT * FROM nation WHERE name > 'CANADA';
SELECT * FROM nation WHERE name = 'CANADA';

MySQL коннектор#

Требования#

Конфигурация#

Connection security#

Аутентификация в источнике данных#

Multiple MySQL servers#

Общие параметры конфигурации#

Domain compaction threshold#

Процедуры#

Case insensitive идентификаторы#

Нетракзакционный INSERT#

Type mapping#

MySQL to Trino type mapping#

Trino to MySQL type mapping#

Обработка DECIMAL типов#

Конфигурация приведения типов#

Querying MySQL#

SQL support#

SQL DELETE#

Table functions#

query(varchar) -> table#

Performance#

Table statistics#

Pushdown#

Join pushdown#

Predicate pushdown support#

`query(varchar) -> table`#