MySQL connector#

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.

Requirements#

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.

Configuration#

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 parameter 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.

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

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

  • непосредственно в файле конфигурации коннектора;

  • в отдельном файле свойств;

  • в файле хранилища ключей;

  • как дополнительные учетные данные, заданные при подключении к Trino.

Можно использовать секреты, чтобы не хранить конфиденциальные значения в файлах свойств каталога.

В следующей таблице описаны свойства конфигурации для учетных данных подключения:

Имя свойства

Описание

credential-provider.type

Тип поставщика учетных данных. Должен быть одним из INLINE, FILE или KEYSTORE; по умолчанию — INLINE.

connection-user

Имя пользователя подключения.

connection-password

Пароль подключения.

user-credential-name

Имя свойства дополнительных учетных данных, значение которого используется как имя пользователя. См. extraCredentials в справочнике параметров.

password-credential-name

Имя свойства дополнительных учетных данных, значение которого используется как пароль.

connection-credential-file

Расположение файла свойств, в котором находятся учетные данные. Он должен содержать свойства connection-user и connection-password.

keystore-file-path

Расположение файла Java Keystore, из которого считываются учетные данные.

keystore-type

Формат файла хранилища ключей, например JKS или PEM.

keystore-password

Пароль для хранилища ключей.

keystore-user-credential-name

Имя сущности хранилища ключей, используемой как имя пользователя.

keystore-user-credential-password

Пароль для сущности хранилища ключей с именем пользователя.

keystore-password-credential-name

Имя сущности хранилища ключей, используемой как пароль.

keystore-password-credential-password

Пароль для сущности хранилища ключей с паролем.

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

Поддержка имен схем и таблиц без учета регистра. По умолчанию — false.

case-insensitive-name-matching.cache-ttl

Длительность, в течение которой кэшируются имена схем и таблиц при сопоставлении без учета регистра. По умолчанию — 1m.

case-insensitive-name-matching.config-file

Путь к конфигурационному файлу сопоставления имен в формате JSON, который позволяет Trino различать схемы и таблицы с похожими именами в разных регистрах. По умолчанию — null.

case-insensitive-name-matching.config-file.refresh-period

Частота, с которой Trino проверяет конфигурационный файл сопоставления имен на изменения. Значение длительности по умолчанию — 0s (обновление отключено).

metadata.cache-ttl

Длительность, в течение которой кэшируются метаданные, включая статистику таблиц и столбцов. По умолчанию — 0s (кэширование отключено).

metadata.cache-missing

Кэшировать факт недоступности метаданных, включая статистику таблиц и столбцов. По умолчанию — false.

metadata.schemas.cache-ttl

Длительность, в течение которой кэшируются метаданные схем. По умолчанию равно значению metadata.cache-ttl.

metadata.tables.cache-ttl

Длительность, в течение которой кэшируются метаданные таблиц. По умолчанию равно значению metadata.cache-ttl.

metadata.statistics.cache-ttl

Длительность, в течение которой кэшируется статистика таблиц. По умолчанию равно значению metadata.cache-ttl.

metadata.cache-maximum-size

Максимальное число объектов, хранящихся в кэше метаданных. По умолчанию — 10000.

write.batch-size

Максимальное число операторов в пакетном выполнении. Не меняйте это значение относительно значения по умолчанию. Нестандартные значения могут отрицательно повлиять на производительность. По умолчанию — 1000.

dynamic-filtering.enabled

Проталкивать динамические фильтры в JDBC-запросы. По умолчанию — true.

dynamic-filtering.wait-timeout

Максимальная длительность, в течение которой Trino ожидает сбора динамических фильтров со стороны построения соединения перед запуском JDBC-запроса. Большой тайм-аут потенциально может дать более подробные динамические фильтры, но также может увеличить задержку некоторых запросов. По умолчанию — 20s.

Добавление метаданных запроса#

Необязательный параметр query.comment-format позволяет настроить SQL-комментарий, который отправляется источнику данных с каждым запросом. Формат комментария может содержать любые символы и следующие метаданные:

  • $QUERY_ID: идентификатор запроса.

  • $USER: имя пользователя, отправившего запрос в Trino.

  • $SOURCE: идентификатор клиентского инструмента, использованного для отправки запроса, например trino-cli.

  • $TRACE_TOKEN: токен трассировки, настроенный в клиентском инструменте.

Комментарий может предоставить больше контекста о запросе. Эта дополнительная информация доступна в журналах источника данных. Чтобы включить в комментарий переменные окружения из кластера Trino, используйте синтаксис ${ENV:VARIABLE-NAME}.

Следующий пример задает простой комментарий, идентифицирующий каждый запрос, отправленный Trino:

query.comment-format=Query sent by Trino.

С такой конфигурацией запрос вроде SELECT * FROM example_table; отправляется источнику данных с добавленным комментарием:

SELECT * FROM example_table; /*Query sent by Trino.*/

Следующий пример улучшает предыдущий, используя метаданные:

query.comment-format=Query $QUERY_ID sent by user $USER from Trino.

Если Jane отправила запрос с идентификатором 20230622_180528_00000_bkizg, источнику данных отправляется следующая строка комментария:

SELECT * FROM example_table; /*Query 20230622_180528_00000_bkizg sent by user Jane from Trino.*/

Note

Некоторые настройки драйвера JDBC и конфигурации журналирования могут привести к удалению комментария.

Порог компактирования домена#

Проталкивание большого списка предикатов в источник данных может ухудшить производительность. По умолчанию Trino компактирует большие предикаты в более простой предикат диапазона, чтобы сохранить баланс между производительностью и проталкиванием предикатов. При необходимости порог такого компактирования можно увеличить, чтобы повысить производительность, когда источник данных способен эффективно использовать большие предикаты. Увеличение этого порога может улучшить проталкивание больших динамических фильтров. Свойство конфигурации каталога domain-compaction-threshold или свойство сеанса каталога domain_compaction_threshold можно использовать для изменения значения по умолчанию 256 для этого порога.

Сопоставление без учета регистра#

Когда case-insensitive-name-matching установлено в true, Trino может запрашивать схемы и таблицы с именами не только в нижнем регистре, поддерживая сопоставление имени в нижнем регистре с фактическим именем в удаленной системе. Однако если две схемы и/или таблицы имеют имена, различающиеся только регистром, например “customers” и “Customers”, Trino не сможет запрашивать их из-за неоднозначности.

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

{
  "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"
    }]
}

Запросы к одной из таблиц или схем, заданных в атрибутах mapping, выполняются к соответствующей удаленной сущности. Например, запрос к таблицам в схеме case_insensitive_1 перенаправляется в схему CaseSensitiveName, а запрос к case_insensitive_2 — в схему cASEsENSITIVEnAME.

На уровне сопоставления таблиц запрос к case_insensitive_1.table_1 в приведенной выше конфигурации перенаправляется к CaseSensitiveName.tablex, а запрос к case_insensitive_1.table_2 — к CaseSensitiveName.TABLEX.

По умолчанию после изменения конфигурационного файла сопоставления Trino нужно перезапустить, чтобы загрузить изменения. При необходимости можно задать case-insensitive-name-matching.config-file.refresh-period, чтобы Trino обновлял свойства без перезапуска:

case-insensitive-name-matching.config-file.refresh-period=30s

Fault-tolerant execution support#

The connector supports Fault-tolerant execution of query processing. Read and write operations are both supported with any retry policy.

Table properties#

Table property usage example:

CREATE TABLE person (
  id INT NOT NULL,
  name VARCHAR,
  age INT,
  birthday DATE 
)
WITH (
  primary_key = ARRAY['id']
);

The following are supported MySQL table properties:

Property name

Required

Description

primary_key

No

The primary key of the table, can choose multi columns as the table primary key. All key columns must be defined as NOT NULL.

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

TINYINT UNSIGNED

SMALLINT

SMALLINT

SMALLINT

SMALLINT UNSIGNED

INTEGER

INTEGER

INTEGER

INTEGER UNSIGNED

BIGINT

BIGINT

BIGINT

BIGINT UNSIGNED

DECIMAL(20, 0)

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)

TIMESTAMP(n)

TIMESTAMP(n)

TIMESTAMP(n) WITH TIME ZONE

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)

DATETIME(n)

TIMESTAMP(n) WITH TIME ZONE

TIMESTAMP(n)

No other types are supported.

Timestamp type handling#

MySQL TIMESTAMP types are mapped to Trino TIMESTAMP WITH TIME ZONE. To preserve time instants, Trino sets the session time zone of the MySQL connection to match the JVM time zone. As a result, error messages similar to the following example occur when a timezone from the JVM does not exist on the MySQL server:

com.mysql.cj.exceptions.CJException: Unknown or incorrect time zone: 'UTC'

To avoid the errors, you must use a time zone that is known on both systems, or install the missing time zone on the MySQL server.

Decimal type handling#

DECIMAL types with unspecified precision or scale are ignored unless the decimal-mapping configuration property or the decimal_mapping session property is set to allow_overflow. Then such types are mapped to a Trino DECIMAL with a default precision of 38 and default scale of 0. To change the scale of the resulting type, use the decimal-default-scale configuration property or the decimal_default_scale session property. The precision is always 38.

By default, values that require rounding or truncation to fit will cause a failure at runtime. This behavior is controlled via the decimal-rounding-mode configuration property or the decimal_rounding_mode session property, which can be set to UNNECESSARY (the default), UP, DOWN, CEILING, FLOOR, HALF_UP, HALF_DOWN, or HALF_EVEN (see RoundingMode).

Свойства конфигурации сопоставления типов#

Следующие свойства можно использовать для настройки того, как типы данных из подключенного источника данных сопоставляются с типами данных Trino и как метаданные кэшируются в Trino.

Имя свойства

Описание

Значение по умолчанию

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 features:

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

Коннектор поддерживает добавление строк с помощью операторов INSERT. По умолчанию вставка данных выполняется путем записи данных во временную таблицу. Этот шаг можно пропустить, чтобы повысить производительность и писать напрямую в целевую таблицу. Установите свойство каталога insert.non-transactional-insert.enabled или соответствующее свойство сеанса каталога non_transactional_insert в true.

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

Ограничение UPDATE#

Поддерживаются только операторы UPDATE с константными присваиваниями и предикатами. Например, следующий оператор поддерживается, потому что присваиваемые значения являются константами:

UPDATE table SET col1 = 1 WHERE col3 = 1

Арифметические выражения, вызовы функций и другие неконстантные операторы UPDATE не поддерживаются. Например, следующий оператор не поддерживается, поскольку арифметические выражения нельзя использовать с командой SET:

UPDATE table SET col1 = col2 + 2 WHERE col3 = 1

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

UPDATE table SET col1 = 1, col2 = 2, col3 = 3 WHERE col3 = 1

Ограничение DELETE#

Если указано предложение WHERE, операция DELETE работает только в том случае, если предикат в предложении может быть полностью протолкнут в источник данных.

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

Коннектор поддерживает добавление, обновление и удаление строк с помощью операторов MERGE, если свойство каталога merge.non-transactional-merge.enabled или соответствующее свойство сеанса каталога non_transactional_merge_enabled установлено в true. Merge поддерживается только для непосредственного изменения целевых таблиц.

В редких случаях во время операции merge могут возникать исключения, что потенциально приводит к частичному обновлению.

Procedures#

system.flush_metadata_cache()#

Очищает кэши метаданных JDBC. Например, следующий системный вызов очищает кэши метаданных для всех схем в каталоге example:

USE example.example_schema;
CALL system.flush_metadata_cache();

system.execute('query')#

Процедура execute позволяет выполнить запрос напрямую в базовом источнике данных. Запрос должен использовать поддерживаемый синтаксис подключенного источника данных. Используйте процедуру для доступа к возможностям, которые недоступны в Trino, или для выполнения запросов, которые не возвращают набор результатов и поэтому не могут использоваться с транзитной табличной функцией query или raw_query. Типичные случаи применения — операторы, создающие или изменяющие объекты и требующие нативных возможностей, таких как ограничения, значения по умолчанию, автоматическое создание идентификаторов или индексы. Запросы также могут вызывать операторы, которые вставляют, обновляют или удаляют данные и не возвращают данных в результате.

Текст запроса не разбирается Trino, а только передается дальше, поэтому он подчиняется только правилам безопасности и контроля доступа базового источника данных.

В следующем примере текущая база данных устанавливается в example_schema каталога example. Затем в этой схеме вызывается процедура, чтобы удалить значение по умолчанию из your_column в таблице your_table с помощью стандартного SQL-синтаксиса в значении параметра query:

USE example.example_schema;
CALL system.execute(query => 'ALTER TABLE your_table ALTER COLUMN your_column DROP DEFAULT');

Убедитесь, что конкретная база данных поддерживает этот синтаксис, и при необходимости адаптируйте его на основе документации конкретной подключенной базы данных и ее версии.

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.

Нативный запрос, переданный базовому источнику данных, должен возвращать таблицу как набор результатов. Проверку и контроль безопасности для таких запросов выполняет только источник данных, используя собственную конфигурацию. Trino не выполняет эти задачи. Используйте транзитные запросы только для чтения данных.

For example, query the example catalog and 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'
    )
  );

Note

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

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;

Note

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 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:

Note

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

Проталкивание соединений на основе стоимости#

Коннектор поддерживает проталкивание соединений на основе стоимости, чтобы принимать обоснованные решения о том, нужно ли проталкивать операцию соединения в источник данных.

Когда проталкивание соединений на основе стоимости включено, коннектор проталкивает операции соединения только если доступная Статистика таблиц указывает, что это повышает производительность. Обратите внимание: если статистика таблиц недоступна, проталкивание операции соединения не выполняется, чтобы избежать потенциального снижения производительности запроса.

В следующей таблице описаны свойства конфигурации каталога для проталкивания соединений:

Имя свойства

Описание

Значение по умолчанию

join-pushdown.enabled

Включает проталкивание соединений. Эквивалентное свойство сеанса каталогаjoin_pushdown_enabled.

true

join-pushdown.strategy

Стратегия, используемая для оценки того, следует ли проталкивать операции соединения. Установите AUTOMATIC, чтобы включить проталкивание соединений на основе стоимости, или EAGER, чтобы проталкивать соединения всегда, когда это возможно. Обратите внимание, что EAGER может проталкивать соединения даже при отсутствии статистики таблиц, что может привести к ухудшению производительности запросов. Поэтому EAGER рекомендуется только для тестирования и диагностики.

AUTOMATIC

Поддержка проталкивания предикатов#

Коннектор не поддерживает проталкивание любых предикатов для столбцов с текстовыми типами, такими как CHAR или VARCHAR. Это обеспечивает корректность результатов, поскольку источник данных может сравнивать строки без учета регистра.

В следующем примере предикат не проталкивается ни для одного запроса, поскольку name — столбец типа VARCHAR:

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