Тип sql
KUMA поддерживает работу с несколькими типами баз данных.
Программа поддерживает работу со следующими типами баз данных SQL:
- SQLite.
- MsSQL.
- MySQL.
- PostgreSQL.
- Cockroach.
- Oracle.
- Firebird.
При создании коннектора вам требуется задать значения для общих параметров коннектора и индивидуальных параметров подключения к базе данных.
Для коннектора на закладке Основные параметры вам требуется задать значения следующих параметров:
- Название (обязательно) – уникальное имя ресурса. Должно содержать от 1 до 128 символов в кодировке Unicode.
- Тип (обязательно) – тип коннектора, sql.
- Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
- Запрос по умолчанию (обязательно) – SQL-запрос, который выполняется при подключении к базе данных.
- Переподключаться к БД каждый раз при отправке запроса – по умолчанию флажок снят.
- Интервал запросов, сек. – интервал выполнения SQL-запросов. Указывается в секундах. Значение по умолчанию: 10 секунд.
- Описание – описание ресурса: до 4000 символов в кодировке Unicode.
Для подключения к базе данных на закладке Основные параметры вам требуется задать значения следующих параметров:
- URL (обязательно) – секрет, в котором хранится список URL-адресов для подключения к базе данных.
При необходимости вы можете изменить или создать секрет.
- Нажмите на кнопку
.Откроется окно секрета.
- Укажите значения для следующих параметров:
- Название – имя добавляемого секрета.
- Тип – urls.
Значение установлено по умолчанию, его редактирование недоступно.
- URL – URL-адрес базы данных.
Вам требуется учитывать, что для подключения к каждому типу базы данных используется свой формат URL-адреса.
Доступные форматы URL-адресов:
- Для SQLite:
sqlite3://file:<file_path>
В качестве плейсхолдера используется знак вопроса: ?.
- Для MsSQL:
sqlserver://<user>:<password>@<server:port>/<instance_name>?database=<database>
(рекомендуется)sqlserver://<user>:<password>@<server>?database=<database>&encrypt=disable
В качестве плейсхолдера используются символы @p1.
- Для MySQL:
mysql://<user>:<password>@tcp(<server>:<port>)/<database>
В качестве плейсхолдера используются символы %s.
- Для PostgreSQL:
postgres://<user>:<password>@<server>/<database>?sslmode=disable
В качестве плейсхолдера используются символы $1.
- Для Cockroach:
postgres://<user>:<password>@<server>:<port>/<database>?sslmode=disable
В качестве плейсхолдера используются символы $1.
- Для Firebird:
firebirdsql://<user>:<password>@<server>:<port>/<database>
В качестве плейсхолдера используется знак вопроса: ?.
- Описание – любая дополнительная информация.
- При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес.
В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке адресов.
- Нажмите на кнопку Сохранить.
- Нажмите на кнопку
.Откроется окно секрета.
- Укажите значения для параметров, которые требуется изменить.
Вы можете изменить значения для следующих параметров:
- Название – имя добавляемого секрета.
- URL – URL-адрес базы данных.
Вам требуется учитывать, что для подключения к каждому типу базы данных используется свой формат URL-адреса.
Доступные форматы URL-адресов:
- Для SQLite:
sqlite3://file:<file_path>
В качестве плейсхолдера используется знак вопроса: ?.
- Для MsSQL:
sqlserver://<user>:<password>@<server:port>/<instance_name>?database=<database>
(рекомендуется)sqlserver://<user>:<password>@<server>?database=<database>&encrypt=disable
В качестве плейсхолдера используются символы @p1.
- Для MySQL:
mysql://<user>:<password>@tcp(<server>:<port>)/<database>
В качестве плейсхолдера используется символ ?
.
- Для PostgreSQL:
postgres://<user>:<password>@<server>/<database>?sslmode=disable
В качестве плейсхолдера используются символы $1.
- Для Cockroach:
postgres://<user>:<password>@<server>:<port>/<database>?sslmode=disable
В качестве плейсхолдера используются символы $1.
- Для Firebird:
firebirdsql://<user>:<password>@<server>:<port>/<database>
В качестве плейсхолдера используется знак вопроса: ?.
- Описание – любая дополнительная информация.
- При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес.
В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке адресов.
- Нажмите на кнопку Сохранить.
При создании подключений могут некорректно обрабатываться строки с учетными данными, содержащими специальные символы. Если при создании подключения возникает ошибка, но вы уверены в том, что значения параметров корректны, укажите специальные символы в процентной кодировке.
Коды специальных символов
!
|
#
|
$
|
%
|
&
|
'
|
(
|
)
|
*
|
+
|
%21
|
%23
|
%24
|
%25
|
%26
|
%27
|
%28
|
%29
|
%2A
|
%2B
|
,
|
/
|
:
|
;
|
=
|
?
|
@
|
[
|
]
|
\
|
%2C
|
%2F
|
%3A
|
%3B
|
%3D
|
%3F
|
%40
|
%5B
|
%5D
|
%5C
|
Следующие специальные символы не поддерживаются в паролях доступа к базам SQL: пробел, [, ], :, /, #, %, \.
- Столбец идентификатора (обязательно) – название столбца, содержащего идентификатор для каждой строки таблицы.
- Начальное значение идентификатора (обязательно) – значение в столбце идентификатора, по которому будет определена строка, с которой требуется начать считывание данных из SQL-таблицы.
- Запрос – поле для дополнительного SQL-запроса. Запрос, указанный в этом поле, выполняется вместо запроса по умолчанию.
- Интервал запросов, сек. – интервал выполнения SQL-запросов. Интервал, указанный в этом поле, используется вместо интервала, указанного по умолчанию для коннектора.
Указывается в секундах. Значение по умолчанию: 10 секунд.
Для коннектора на закладке Дополнительные параметры вам требуется задать значения следующих параметров:
В рамках одного коннектора вы можете создать подключение для нескольких поддерживаемых баз данных.
Чтобы создать подключение для нескольких баз данных SQL:
- Нажмите на кнопку Добавить подключение.
- Задайте значение для параметров URL, Столбец идентификатора, Начальное значение идентификатора, Запрос, Интервал запросов, сек.
- Повторите шаги 1–2 для каждого требуемого подключения.
Поддерживаемые типы 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-запросе используется знак вопроса: ?
.
При обращении к SQLite3, если начальное значение идентификатора используется в формате datetime, в SQL-запрос нужно добавить преобразование даты с помощью функции sqlite datetime. Например, select * from connections where datetime(login_time) > datetime(?, 'utc') order by login_time. В этом примере connections
– это таблица SQLite, а значение переменной ?
берется из поля Начальное значение идентификатора, и его следует указывать в формате {date}T{time}Z (например, - 2021-01-01T00:10:00Z).
- Oracle DB
Начиная с версии 2.1.3 KUMA использует новый драйвер для подключения к oracle. При обновлении KUMA переименует секрет для подключения в oracle-deprecated и коннектор продолжит работу. Если после запуска коллектора с типом драйвера oracle-deprecated не удается получить события, создайте новый секрет с драйвером oracle и используйте его для подключения.
Мы рекомендуем использовать новый драйвер.
Пример URL секрета с новым драйвером oracle:
oracle://{user}:{password}@{server}:{port}/{service_name}
oracle://{user}:{password}@{server}:{port}/?SID={SID_VALUE}
Пример URL секрета с прежним драйвером oracle-deprecated:
oracle-deprecated://{user}/{password}@{server}:{port}/{service_name}
В качестве плейсхолдера в SQL-запросе используется переменная :val
.
При обращении к Oracle DB, если начальное значение идентификатора используется в формате datetime, нужно учитывать тип поля в самой базе данных и при необходимости добавить дополнительные преобразования строки со временем в запросе для обеспечения корректной работы sql коннектора. Например, если в базе создана таблица Connections, в которой есть поле login_time, возможны следующие преобразования:
- Если у поля login_time тип TIMESTAMP, то в зависимости от настроек базы в поле login_time может лежать значение в формате YYYY-MM-DD HH24:MI:SS (например, 2021-01-01 00:00:00). Тогда в поле Начальное значение идентификатора следует указать значение 2021-01-01T00:00:00Z, а в запросе произвести преобразование с помощью функции to_timestamp. Например:
select * from connections where login_time > to_timestamp(:val, 'YYYY-MM-DD"T"HH24:MI:SS"Z"')
- Если у поля login_time тип TIMESTAMP WITH TIME ZONE, то в зависимости от настроек базы в поле login_time может лежать значение в формате YYYY-MM-DD"T"HH24:MI:SSTZH:TZM (например, 2021-01-01T00:00:00+03:00). Тогда в поле Начальное значение идентификатора следует указать значение 2021-01-01T00:00:00+03:00, а в запросе произвести преобразование с помощью функции to_timestamp_tz. Например:
select * from connections_tz where login_time > to_timestamp_tz(:val, 'YYYY-MM-DD"T"HH24:MI:SSTZH:TZM')
Подробнее о функциях to_timestamp и to_timestamp_tz см. в официальной документации Oracle.
Для обращения к Oracle DB необходимо установить пакет Astra Linux libaio1.
- Firebird® SQL
Пример URL:
firebirdsql://{user}:{password}@{server}:{port}/{database}
В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?
.
Если возникает проблема подключения к firebird на Windows, используйте полный путь до файла с базой данных. Например:
firebirdsql://{user}:{password}@{server}:{port}/C:\Users\user\firebird\db.FDB
В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать запрос select * from <название таблицы с данными> where id > <плейсхолдер>
, то при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.
Примеры SQL-запросов
SQLite, Firebird – select * from table_name where id > ?
MsSQL – select * from table_name where id > @p1
MySQL – select * from table_name where id > ?
PostgreSQL, Cockroach – select * from table_name where id > $1
Oracle – select * from table_name where id > :val
В начало