MariaDB connector#

The MariaDB connector allows querying and creating tables in an external MariaDB database.

Requirements#

To connect to MariaDB, you need:

MariaDB version 10.10 or higher.
Network access from the Trino coordinator and workers to MariaDB. Port 3306 is the default port.

Configuration#

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

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

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.

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

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

непосредственно в файле конфигурации коннектора;
в отдельном файле свойств;
в файле хранилища ключей;
как дополнительные учетные данные, заданные при подключении к 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`	Пароль для сущности хранилища ключей с паролем.

Общие свойства конфигурации#

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

Имя свойства	Описание
`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`.

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

Проталкивание большого списка предикатов в источник данных может ухудшить производительность. По умолчанию 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.

Querying MariaDB#

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

SHOW SCHEMAS FROM example;

If you have a MariaDB 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.

Type mapping#

Because Trino and MariaDB 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.

MariaDB type to Trino type mapping#

The connector maps MariaDB types to the corresponding Trino types according to the following table:

MariaDB type to Trino type mapping#
MariaDB type	Trino type	Notes
`BOOLEAN`	`TINYINT`	`BOOL` and `BOOLEAN` are aliases of `TINYINT(1)`
`TINYINT`	`TINYINT`
`TINYINT UNSIGNED`	`SMALLINT`
`SMALLINT`	`SMALLINT`
`SMALLINT UNSIGNED`	`INTEGER`
`INT`	`INTEGER`
`INT UNSIGNED`	`BIGINT`
`BIGINT`	`BIGINT`
`BIGINT UNSIGNED`	`DECIMAL(20, 0)`
`FLOAT`	`REAL`
`DOUBLE`	`DOUBLE`
`DECIMAL(p,s)`	`DECIMAL(p,s)`
`CHAR(n)`	`CHAR(n)`
`TINYTEXT`	`VARCHAR(255)`
`TEXT`	`VARCHAR(65535)`
`MEDIUMTEXT`	`VARCHAR(16777215)`
`LONGTEXT`	`VARCHAR`
`VARCHAR(n)`	`VARCHAR(n)`
`TINYBLOB`	`VARBINARY`
`BLOB`	`VARBINARY`
`MEDIUMBLOB`	`VARBINARY`
`LONGBLOB`	`VARBINARY`
`VARBINARY(n)`	`VARBINARY`
`DATE`	`DATE`
`TIME(n)`	`TIME(n)`
`TIMESTAMP(n)`	`TIMESTAMP(n)`	MariaDB stores the current timestamp by default. Enable explicit_defaults_for_timestamp to avoid implicit default values and use `NULL` as the default value.
`DATETIME(n)`	`TIMESTAMP(n)`

No other types are supported.

Trino type mapping to MariaDB type mapping#

The connector maps Trino types to the corresponding MariaDB types according to the following table:

Trino type mapping to MariaDB type mapping#
Trino type	MariaDB type	Notes
`BOOLEAN`	`BOOLEAN`
`TINYINT`	`TINYINT`
`SMALLINT`	`SMALLINT`
`INTEGER`	`INT`
`BIGINT`	`BIGINT`
`REAL`	`FLOAT`
`DOUBLE`	`DOUBLE`
`DECIMAL(p,s)`	`DECIMAL(p,s)`
`CHAR(n)`	`CHAR(n)`
`VARCHAR(255)`	`TINYTEXT`	Maps on `VARCHAR` of length 255 or less.
`VARCHAR(65535)`	`TEXT`	Maps on `VARCHAR` of length between 256 and 65535, inclusive.
`VARCHAR(16777215)`	`MEDIUMTEXT`	Maps on `VARCHAR` of length between 65536 and 16777215, inclusive.
`VARCHAR`	`LONGTEXT`	`VARCHAR` of length greater than 16777215 and unbounded `VARCHAR` map to `LONGTEXT`.
`VARBINARY`	`MEDIUMBLOB`
`DATE`	`DATE`
`TIME(n)`	`TIME(n)`
`TIMESTAMP(n)`	`TIMESTAMP(n)`	MariaDB stores the current timestamp by default. Enable `explicit_defaults_for_timestamp <https://mariadb.com/docs/reference/mdb/system-variables/explicit_defaults_for_timestamp/>`_ to avoid implicit default values and use `NULL` as the default value.

No other types are supported.

Complete list of MariaDB data types.

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

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

Имя свойства

Описание

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

unsupported-type-handling

Настраивает обработку неподдерживаемых типов данных столбцов:

IGNORE — столбец недоступен.
CONVERT_TO_VARCHAR — столбец преобразуется в неограниченный VARCHAR.

Соответствующее свойство сеанса каталога — unsupported_type_handling.

IGNORE

jdbc-types-mapped-to-varchar

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

SQL support#

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

INSERT, see also Нетранзакционный INSERT
UPDATE, see also Ограничение UPDATE
DELETE, see also Ограничение DELETE
TRUNCATE
CREATE TABLE
CREATE TABLE AS
DROP TABLE
ALTER TABLE
CREATE SCHEMA
DROP SCHEMA
Procedures
Table functions

Нетранзакционный 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 работает только в том случае, если предикат в предложении может быть полностью протолкнут в источник данных.

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

`query(varchar) -> table`#

The query function allows you to query the underlying database directly. It requires syntax native to MariaDB, because the full query is pushed down and processed in MariaDB. 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 не выполняет эти задачи. Используйте транзитные запросы только для чтения данных.

As an example, query the example catalog and select the age of employees by using TIMESTAMPDIFF and CURDATE:

SELECT
  age
FROM
  TABLE(
    example.system.query(
      query => 'SELECT
        TIMESTAMPDIFF(
          YEAR,
          date_of_birth,
          CURDATE()
        ) AS age
      FROM
        tiny.employees'
    )
  );

Note

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

Performance#

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

Table statistics#

The MariaDB 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 MariaDB and retrieved by the connector.

To collect statistics for a table, execute the following statement in MariaDB.

ANALYZE TABLE table_name;

Refer to MariaDB documentation for additional information.

Pushdown#

The connector supports pushdown for a number of operations:

Aggregate pushdown for the following functions:

Note

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

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

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

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

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

MariaDB connector#

Requirements#

Configuration#

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

Общие свойства конфигурации#

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

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

Fault-tolerant execution support#

Querying MariaDB#

Type mapping#

MariaDB type to Trino type mapping#

Trino type mapping to MariaDB type mapping#

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

SQL support#

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

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

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

Procedures#

system.flush_metadata_cache()#

system.execute('query')#

Table functions#

query(varchar) -> table#

Performance#

Table statistics#

Pushdown#

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

`system.flush_metadata_cache()`#

`system.execute('query')`#

`query(varchar) -> table`#