Коннектор, тип sql

Развернуть всё | Свернуть всё

Коннекторы с типом sql используются для выборки данных из Систем Управления Базами Данных (СУБД). KUMA поддерживает работу с несколькими типами баз данных. При создании коннектора с типом sql вам нужно указать значения для общих параметров коннектора и отдельных параметров подключения к базе данных. Доступные параметры коннектора с типом sql описаны в таблицах ниже.

Вкладка Основные параметры

Вкладка Дополнительные параметры

В рамках одного коннектора вы можете создать подключение для нескольких поддерживаемых баз данных. Если коллектор с коннектором типа sql не удаётся запустить, вам нужно проверить, пуст ли state-файл /opt/kaspersky/kuma/collector/<идентификатор коллектора>/sql/state-<идентификатор файла>. Если state-файл пуст, вам нужно его удалить и перезапустить коллектор.

Поддерживаемые типы SQL и особенности их использования

Поддерживаются следующие типы SQL:

• MSSQL.

  Например:

  • sqlserver://{user}:{password}@{server:port}/{instance_name}?database={database}

  Мы рекомендуем использовать этот вариант URL.

  • sqlserver://{user}:{password}@{server}?database={database}

  В качестве плейсхолдера в SQL-запросе используются символы @p1.

  Если вы хотите подключиться с доменными учетными данными, укажите имя учетной записи в формате <домен>%5C<пользователь>. Например: sqlserver://domain%5Cuser:password@ksc.example.com:1433/SQLEXPRESS?database=KAV.

• MySQL/MariaDB .

  Например:

  mysql://{user}:{password}@tcp({server}:{port})/{database}

  В качестве плейсхолдера в SQL-запросе используются символ ?.

• PostgreSQL.

  Например: postgres://{user}:{password}@{server}/{database}?sslmode=disable

  В качестве плейсхолдера в SQL-запросе используются символы $1.

• CockroachDB.

  Например:

  postgres://{user}:{password}@{server}:{port}/{database}?sslmode=disable

  В качестве плейсхолдера в SQL-запросе используются символы $1.

• SQLite3.

  Например:

  sqlite3://file:{file_path}

  В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

  При обращении к SQLite3, если начальное значение идентификатора используется в формате datetime, вам нужно добавить преобразование даты с помощью функции sqlite datetime в SQL-запрос. Например:

  select * from connections where datetime(login_time) > datetime(?, 'utc') order by login_time

  В этом примере connections – это таблица SQLite, а значение переменной ? берется из поля Начальное значение идентификатора, и его требуется указывать в формате {<дата>}T{<время>}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}

  Если время выполнения запроса превышает 30 секунд. драйвер oracle прерывает SQL-запрос и в журнале коллектора появится ошибка user requested cancel of current operation. Для увеличения времени выполнения SQL-запроса укажите в строке подключения значение параметра timeout в секундах, например:

  oracle://{user}:{password}@{server}:{port}/{service_name}?timeout=300

  Пример URL секрета с прежним драйвером oracle-deprecated:

  oracle-deprecated://{user}/{password}@{server}:{port}/{service_name}

  В качестве плейсхолдера в SQL-запросе используется переменная :val.

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

  Например:

  firebirdsql://{user}:{password}@{server}:{port}/{database}

  В качестве плейсхолдера в SQL-запросе используется знак вопроса: ?.

  Если возникает проблема подключения к firebird на Windows, используйте полный путь до файла с базой данных, например:

  firebirdsql://{user}:{password}@{server}:{port}/C:\Users\user\firebird\db.FDB

• ClickHouse.

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

  • Данные, которые можно привести к строкам (например, строки, численные значения и BLOB-объекты), отображаются в виде строк.
  • Массивы данных и карты отображаются в формате JSON или с помощью встроенного механизма go fmt.Sprintf("%v",v) показываются оптимальным доступным образом.

  Подключение к ClickHouse может осуществляться двумя способами:

  • Без использования учетных данных: необходимо ввести URL-адрес clickhouse://host:port/database.
  • С учетными данными: требуется использовать URL-адрес clickhouse://user:password@host:port/database.

  При использовании шифрования TLS по умолчанию коннектор работает только по порту 9440. Если шифрование TLS не используется, по умолчанию коннектор работает с ClickHouse только по порту 9000.

  Коннектор не работает по протоколу http.

  Если на сервере с ClickHouse настроен режим шифрования TLS, а в параметрах коннектора в раскрывающемся списке Режим TLS выбрано Выключено или наоборот, соединение с базой данных не будет установлено.

  Режим TLS используется только если указан драйвер ClickHouse.

  Если вы хотите подключиться к ClickHouse KUMA, вам нужно в параметрах коннектора с типом SQL указать тип секрета PublicPki, который содержит закрытый ключ PEM, закодированный в base64, и открытый ключ.

  В параметрах коннектора с типом SQL для типа соединения ClickHouse вам нужно выбрать Выключено в раскрывающемся списке Режим TLS. Это значение недопустимо указывать, если для аутентификации используется сертификат. Если в раскрывающемся списке Режим TLS вы выбираете Нестандартный CA, в поле Столбец идентификатора вам нужно указать ID секрета типа certificate. Вам также нужно выбрать одно из следующих значений в раскрывающемся списке Тип авторизации:

  • Выключено. При выборе этого значения вам нужно оставить пустым значение в поле Столбец идентификатора.
  • Обычная. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа credentials.
  • PublicPki. Вам нужно выбрать это значение, если установлен флажок Секрет отдельно и в поле Столбец идентификатора указан ID секрета типа PublicPki.

  Если в начальном значении идентификатора есть указание времени (datetime), в запросе необходимо ввести переменную для преобразования времени ( parseDateTimeBestEffort). Например, если время указано как 2021-01-01 00:10:00, то запрос будет следующим:

  select connections, username, host, login_time from connections where login_time > parseDateTimeBestEffort(?) order by login_time

В SQL-запросах поддерживается последовательный запрос сведений из базы данных. Например, если в поле Запрос указать SQL-запрос select * from <название таблицы с данными> where id > <плейсхолдер>, при первом обращении к таблице в качестве значения плейсхолдера будет использоваться значение поля Начальное значение идентификатора. При этом в сервисе, в котором используется SQL-коннектор, сохраняется идентификатор последней прочитанной записи, и во время следующего обращения к базе данных в качестве значения плейсхолдера в запросе будет использоваться идентификатор этой записи.

В строку запроса рекомендуется добавлять команду order by, после которой указывается поле для сортировки. Например, select * from table_name where id > ? order by id.

Примеры SQL-запросов