Содержание

Тип sql

Тип sql

KUMA поддерживает работу с несколькими типами баз данных.

Программа поддерживает работу со следующими типами баз данных SQL:

SQLite.
MsSQL.
MySQL.
PostgreSQL.
Cockroach.
Oracle.
Firebird.

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

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

Название (обязательно) – уникальное имя ресурса. Должно содержать от 1 до 128 символов в кодировке Unicode.
Тип (обязательно) – тип коннектора, sql.
Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
Запрос по умолчанию (обязательно) – SQL-запрос, который выполняется при подключении к базе данных.
Переподключаться к БД каждый раз при отправке запроса – по умолчанию флажок снят.
Интервал запросов, сек. – интервал выполнения SQL-запросов. Указывается в секундах. Значение по умолчанию: 10 секунд.
Описание – описание ресурса: до 4000 символов в кодировке Unicode.

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

URL (обязательно) – секрет, в котором хранится список URL-адресов для подключения к базе данных.
При необходимости вы можете изменить или создать секрет.
1. Нажмите на кнопку .
  Откроется окно секрета.
2. Укажите значения для следующих параметров:
  1. Название – имя добавляемого секрета.
  2. Тип – urls.
    Значение установлено по умолчанию, его редактирование недоступно.
  3. 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>
      В качестве плейсхолдера используется знак вопроса: ?.
  4. Описание – любая дополнительная информация.
3. При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес.
  В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке адресов.
4. Нажмите на кнопку Сохранить.
1. Нажмите на кнопку .
  Откроется окно секрета.
2. Укажите значения для параметров, которые требуется изменить.
  Вы можете изменить значения для следующих параметров:
  1. Название – имя добавляемого секрета.
  2. 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>
      В качестве плейсхолдера используется знак вопроса: ?.
  3. Описание – любая дополнительная информация.
3. При необходимости нажмите на кнопку Добавить и укажите дополнительный URL-адрес.
  В этом случае при недоступности одного URL-адреса программа подключается к следующему URL-адресу, указанному в списке адресов.
4. Нажмите на кнопку Сохранить.
При создании подключений могут некорректно обрабатываться строки с учетными данными, содержащими специальные символы. Если при создании подключения возникает ошибка, но вы уверены в том, что значения параметров корректны, укажите специальные символы в процентной кодировке.

Коды специальных символов

!

#

$

%

&

'

(

)

*

+

%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 секунд.

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

Кодировка символов – кодировка символов. Значение по умолчанию: UTF-8.
KUMA конвертирует ответы SQL в кодировку UTF-8. Вы можете настроить SQL-сервер на отправку ответов в кодировке UTF-8 или выбрать их кодировку на стороне KUMA.
Отладка – раскрывающийся список, в котором можно указать, будет ли включено логирование ресурса. По умолчанию указывается значение Выключено.

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

Чтобы создать подключение для нескольких баз данных 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

В начало

!	#	$	%	&	'	(	)	*	+
%21	%23	%24	%25	%26	%27	%28	%29	%2A	%2B
,	/	:	;	=	?	@	[	]	\
%2C	%2F	%3A	%3B	%3D	%3F	%40	%5B	%5D	%5C

!	#	$	%	&	'	(	)	*	+
%21	%23	%24	%25	%26	%27	%28	%29	%2A	%2B
,	/	:	;	=	?	@	[	]	\
%2C	%2F	%3A	%3B	%3D	%3F	%40	%5B	%5D	%5C

!	#	$	%	&	'	(	)	*	+
%21	%23	%24	%25	%26	%27	%28	%29	%2A	%2B
,	/	:	;	=	?	@	[	]	\
%2C	%2F	%3A	%3B	%3D	%3F	%40	%5B	%5D	%5C