Тип sql
Тип sql используется для связи с SQL. Настройки коннектора разделены на три блока:
- Общие параметры коннектора.
- Параметры определенного SQL-подключения. Таких подключений в одном коннекторе может быть более одного.
- Дополнительные параметры коннектора.
Общие параметры коннектора
Общие параметры коннектора расположены на закладке Основные параметры:
- Название (обязательно) – уникальное имя для этого типа ресурса. Должно содержать от 1 до 128 символов Юникода.
- Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
- Тип (обязательно) – тип коннектора.
- Запрос по умолчанию (обязательно) – поле для SQL-запроса, общего для всех подключений коннектора.
- Интервал запросов, сек. – время между SQL-запросами в секундах. Значение по умолчанию: 10 секунд.
- Описание – описание ресурса: до 256 символов Юникода.
Если для определенного подключения (см. ниже) указаны свои запрос и/или интервал запросов, для этого подключении будут использоваться указанные в нем значения.
Параметры определенного SQL-подключения
Общие параметры коннектора расположены на закладке Основные параметры. В одном коннекторе можно создать несколько подключений, добавляя новые с помощью кнопки Добавить подключение. Удалить подключения можно с помощью кнопки 
.
Параметры подключения:
- URL (обязательно) – раскрывающийся список для выбора ресурса секрета, в котором хранится список строк с запросами на SQL-подключения. Формат строки зависит от конкретной базы данных (см. ниже поддерживаемые типы SQL).
При создании подключений могут некорректно обрабатываться строки с учетными данными, содержащими специальные символы. Если подключение не создается, но вы уверены в правильности параметров, укажите специальные символы в процентной кодировке.
Доступные форматы адресов сервера: hostname:port, IPv4:port, IPv6:port.
При необходимости секрет можно создать в окне создания коннектора с помощью кнопки
. Выбранный секрет можно изменить, нажав на кнопку 
. - Столбец идентификатора (обязательно) – название столбца, который будет принят за столбец идентификаторов.
- Начальное значение идентификатора (обязательно) – значение в столбце идентификатора, по которому будет определена строка, с которой требуется начать считывание данных из SQL-таблицы.
- Запрос – поле для SQL-запросов. Если у определенного подключения в коннекторе указан запрос, он будет использоваться вместо запроса, указанного в поле Запрос по умолчанию.
- Интервал запросов, сек. – время между SQL-запросами в секундах. Значение по умолчанию: 10 секунд. Если у определенного подключения в коннекторе указан интервал запросов, этот интервал будет использоваться вместо общего интервала запросов коннектора.
С помощью параметров URL, Столбец идентификатора и Начальное значение идентификатора определяется одно SQL-подключение. Строка, до которой были получены данные из SQL-таблицы, сохраняется в коллекторе KUMA, из которого был сделан запрос в базу данных SQL. Это позволяет считывать данные из SQL-таблицы с последней прочитанной строки. Идентификатор последней прочитанной строки не меняется при указании в коннекторе иного URL или запроса. Для изменения строки, начиная с которой будут получены данные из SQL-таблицы, необходимо изменить значение полей Начальное значение идентификатора и/или Столбец идентификатора.
Дополнительные параметры коннектора
Дополнительные параметры коннектора расположены на закладке Дополнительные параметры:
- Кодировка символов – параметр для установки кодировки символов. Значение по умолчанию:
UTF-8.KUMA может обрабатывать ответы SQL в кодировке UTF-8. Настройте SQL-сервер на отправку сообщений в кодировке UTF-8 или принудительно меняйте кодировку входящих сообщений на UTF-8, выбрав этот вариант в раскрывающемся списке Кодировка символов в настройках коннектора.
- Отладка – раскрывающийся список, в котором можно указать, будет ли включено логирование ресурса. По умолчанию указывается значение Выключено.
Поддерживаемые типы SQL и особенности их использования
Оператор UNION не поддерживается коннекторами типа SQL.
Поддерживаются следующие типы SQL:
- MSSQL
Примеры URL:
sqlserver://{user}:{password}@{server:port}/{instance_name}?database={database}– (рекомендуемый вариант)sqlserver://{user}:{password}@{server}?database={database}
В качестве плейсхолдера в SQL-запросе используются символы
@p1.Если вам требуется подключиться с доменными учетными данными, укажите имя учетной записи в формате
<домен>%5C<пользователь>. Например:sqlserver://domain%5Cuser:password@ksc.example.com:1433/SQLEXPRESS?database=KAV. - MySQL
Пример URL:
mysql://{user}:{password}@tcp({server}:{port})/{database}В качестве плейсхолдера в SQL-запросе используется символ
?. - PostgreSQL
Пример URL:
postgres://{user}:{password}@{server}/{database}?sslmode=disableВ качестве плейсхолдера в SQL-запросе используются символы
$1. - CockroachDB
Пример URL:
postgres://{user}:{password}@{server}:{port}/{database}?sslmode=disableВ качестве плейсхолдера в SQL-запросе используются символы
$1. - SQLite3
Пример URL:
sqlite3://file:{file_path}В качестве плейсхолдера в SQL-запросе используется знак вопроса:
?. - Oracle DB
Пример URL:
oracle://{user}/{password}@{server}:{port}/{service_name}Используется синтаксис Easy Connect. В качестве плейсхолдера в SQL-запросе используется символы
:val.При обращении к Oracle DB, если начальное значение идентификатора используется в формате datetime, в SQL-запрос нужно добавить преобразование даты с помощью функции Oracle
to_timestamp_tz. Например,select * from connections where login_time > to_timestamp_tz(:val, 'YYYY-MM-DD"T"HH24:MI:SSTZH:TZM'). В этом примереConnections– это таблица Oracle DB, а значение переменной:valберется из поля Начальное значение идентификатора, поэтому его требуется указывать в формате с timezone (например,2021-01-01T00:10:00+03:00).Для обращения к Oracle DB необходимо установить пакет libaio1.
- Firebird® SQL
Пример URL:
firebirdsql://{user}:{password}@{server}:{port}/{database}В качестве плейсхолдера в SQL-запросе используется знак вопроса:
?.
В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать запрос select * from <название таблицы с данными> where id > <плейсхолдер>, то при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.