+++
title = "PostgreSQL"
description = "Руководство по использованию PostgreSQL в Harvest"
keywords = ["harvest", "postgresql", "guide"]
aliases = ["/docs/harvest/latest/features/datasources/postgres/"]
weight = 1200
+++
# Источник данных PostgreSQL

Harvest поставляется со встроенным подключаемым модулем источника данных PostgreSQL, который позволяет запрашивать и визуализировать данные из базы данных, совместимой с PostgreSQL. В этом разделе описываются параметры, переменные, запросы и другие параметры, характерные для этого источника данных. Инструкции по добавлению источника данных в Harvest см. в разделе [Добавить источник данных]({{< relref "add-a-data-source.md" >}}). Добавлять источники данных могут только пользователи с ролью администратора организации.

## Настройки PostgreSQL

Чтобы получить доступ к настройкам PostgreSQL, наведите указатель мыши на значок **Конфигурация** (шестеренка), затем щелкните **Источники данных**, а затем щелкните источник данных Prometheus.
Имя               | Описание
-----------------  | -------------
`Name`             | Имя источника данных. Именно так вы обращаетесь к источнику данных в панелях и запросах.
`Default`          | Источник данных по умолчанию означает, что он будет предварительно выбран для новых панелей.
`Host`             | IP-адрес/имя хоста и необязательный порт вашего экземпляра PostgreSQL. _Не_ включайте имя базы данных. Строка подключения для подключения к Postgres будет неправильной, что может привести к ошибкам.
`Database`         | Имя вашей базы данных PostgreSQL.
`User`             | Логин/имя пользователя базы данных
`Password`         | Пароль пользователя базы данных
`SSL Mode`         | Определяет, будет ли и с каким приоритетом согласовываться безопасное соединение SSL TCP/IP с сервером. Когда режим SSL отключен, метод SSL и сведения об аутентификации не будут видны.
`SSL Auth Details Method`       | Определяет, будут ли детали аутентификации SSL настроены как путь к файлу или содержимое файла. Harvest v7.5+
`SSL Auth Details Value` | Путь к файлу или содержимое файла корневого сертификата SSL, сертификата клиента и ключа клиента
`Max open`         | Максимальное количество открытых подключений к базе данных, по умолчанию «неограничено» (Harvest v5.4+).
`Max idle`         |Максимальное количество подключений в пуле незанятых подключений, по умолчанию 2 (Harvest v5.4+).
`Max lifetime`     |Максимальное количество времени в секундах, в течение которого соединение может быть повторно использовано, по умолчанию `14400`/4 часа (Harvest v5.4+).
`Version`          |Определяет, какие функции доступны в построителе запросов (доступно только в Harvest 5.3+).
`TimescaleDB`      |База данных временных рядов, созданная как расширение PostgreSQL. Когда этот параметр включен, Harvest использует time_bucket в макросе $__timeGroup для отображения определенных агрегатных функций TimescaleDB в построителе запросов (доступно только в Harvest 5.3+).

### Минимальный временной интервал

Нижний предел для [$__interval]({{< relref "../variables/variable-types/_index.md#the-interval-variable" >}}) и [$__interval_ms]({{< relref ". ./variables/variable-types/_index.md#the-interval-ms-variable" >}}) переменных.
Рекомендуется установить частоту записи, например `1m`, если ваши данные записываются каждую минуту.
Этот параметр также можно переопределить/настроить на панели инструментов в разделе параметров источника данных. Важно отметить, что это значение **должно** быть отформатировано как
число, за которым следует действительный идентификатор времени, например. `1m` (1 минута) или `30s` (30 секунд). Поддерживаются следующие идентификаторы времени:

| Идентификатор | Описание |
| ---------- | ----------- |
| `y`        | год       |
| `M`        | месяц     |
| `w`        | неделя       |
| `d`        | день        |
| `h`        | час|
| `m`        | минута     |
| `s`        | секунда     |
| `ms`       | миллисекунда|

### Разрешения пользователя базы данных (Важно!)

Пользователю базы данных, которого вы укажете при добавлении источника данных, должны быть предоставлены разрешения SELECT только на
указанную базу данных и таблицы, которые вы хотите запросить. Harvest не проверяет безопасность запроса. Запрос
может включать любой оператор SQL. Например, такие операторы, как `DELETE FROM user` и `DROP TABLE user`, будут
казнен. Чтобы защититься от этого, мы **настоятельно** рекомендуем вам создать отдельного пользователя PostgreSQL с ограниченными разрешениями.

Пример:

```sql
 CREATE USER harvestreader WITH PASSWORD 'password';
 GRANT USAGE ON SCHEMA schema TO harvestreader;
 GRANT SELECT ON schema.table TO harvestreader;
```
Убедитесь, что пользователь не получает нежелательных привилегий от общедоступной роли.

## Редактор запросов

{{< рисунок src="/static/img/docs/v53/postgres_query_still.png" class="docs-image--no-shadow" анимированный-gif="/static/img/docs/v53/postgres_query.gif" >}}

Редактор запросов PostgreSQL находится на вкладке метрик в режиме редактирования панели Graph или Singlestat. Вы входите в режим редактирования, нажав кнопку
название панели, затем отредактируйте.

В редакторе запросов есть ссылка «Сгенерированный SQL», которая появляется после выполнения запроса в режиме редактирования панели. Нажмите на нее, и она развернется и покажет необработанную интерполированную строку SQL, которая была выполнена.

### Выберите таблицу, столбец времени и столбец показателей (ОТ)

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

В поле FROM Harvest предложит таблицы, которые находятся в `search_path` пользователя базы данных. Чтобы выбрать таблицу или представление не в вашем `search_path`
вы можете вручную ввести полное имя (schema.table), например `public.metrics`.

Поле столбца «Время» относится к имени столбца, содержащего ваши значения времени. Выбор значения для поля столбца «Метрика» не является обязательным. Если выбрано значение, поле столбца «Метрика» будет использоваться в качестве имени ряда.

Предлагаемые столбцы метрик будут содержать только столбцы с текстовым типом данных (char, varchar, text).
Если вы хотите использовать столбец с другим типом данных в качестве столбца метрики, вы можете ввести имя столбца с приведением: `ip::text`.
Вы также можете ввести произвольные SQL-выражения в поле столбца метрики, которые оцениваются как текстовый тип данных, например
`имя хоста || ' ' || имя_контейнера`.

### Столбцы, окна и функции агрегирования (SELECT)

В строке `SELECT` вы можете указать, какие столбцы и функции вы хотите использовать.
В поле столбца вы можете писать произвольные выражения вместо имени столбца, например `столбец1 * столбец2 / столбец3`.

Доступные функции в редакторе запросов зависят от версии PostgreSQL, которую вы выбрали при настройке источника данных.
Если вы используете агрегатные функции, вам необходимо сгруппировать набор результатов. Редактор автоматически добавит `GROUP BY time`, если вы добавите агрегатную функцию.

Редактор пытается упростить и унифицировать эту часть запроса. Например:<br>
![](/static/img/docs/v53/postgres_select_editor.png)<br>

Приведенное выше сгенерирует следующее предложение PostgreSQL `SELECT`:

```sql
avg(tx_bytes) OVER (ORDER BY "time" ROWS 5 PRECEDING) AS "tx_bytes"
```

Вы можете добавить дополнительные столбцы значений, нажав кнопку «плюс» и выбрав «Столбец» в меню. Столбцы с несколькими значениями будут отображаться в виде отдельных рядов на панели графика.

### Данные фильтра (ГДЕ)
Чтобы добавить фильтр, щелкните значок плюса справа от условия «ГДЕ». Вы можете удалить фильтры, нажав на
фильтр и выбрав «Удалить». К новым запросам автоматически добавляется фильтр для текущего выбранного временного диапазона.

### Группа по
Чтобы сгруппировать по времени или любым другим столбцам, щелкните значок плюса в конце строки СГРУППИРОВАТЬ ПО. В раскрывающемся списке предложений будут отображаться только текстовые столбцы выбранной таблицы, но вы можете ввести любой столбец вручную.
Вы можете удалить группу, щелкнув элемент и выбрав «Удалить».

Если вы добавите какую-либо группировку, ко всем выбранным столбцам необходимо применить агрегатную функцию. Построитель запросов автоматически добавит агрегатные функции ко всем столбцам без агрегатных функций при добавлении группировок.

#### Заполнение промежутка

Harvest может заполнить пропущенные значения при группировке по времени. Функция времени принимает два аргумента. Первый аргумент — это временное окно, по которому вы хотите сгруппировать, а второй аргумент — это значение, которым вы хотите, чтобы Harvest заполнила недостающие элементы.

### Режим текстового редактора (RAW)
Вы можете переключиться в режим редактора необработанных запросов, щелкнув значок гамбургера и выбрав «Переключить режим редактора» или нажав «Редактировать SQL» под запросом.

> Если вы используете редактор необработанных запросов, убедитесь, что ваш запрос как минимум имеет `ORDER BY time` и фильтр для возвращаемого временного диапазона.

## Макросы

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

Пример макроса                                          | Описание
------------------------------------------------------ | -------------
`$__time(dateColumn)`                                  | Будет заменено выражением для преобразования в метку времени UNIX и переименования столбца в `time_sec`. Например, *UNIX_TIMESTAMP(dateColumn) как time_sec*
`$__timeEpoch(dateColumn)`                             | Будет заменено выражением для преобразования в метку времени UNIX и переименования столбца в `time_sec`. Например, *UNIX_TIMESTAMP(dateColumn) как time_sec*
`$__timeFilter(dateColumn)`                            | Будет заменен фильтром временного диапазона, использующим указанное имя столбца. Например, *dateColumn МЕЖДУ FROM_UNIXTIME(1494410783) И FROM_UNIXTIME(1494410983)*
`$__timeFrom()`                                        | Будет заменено началом текущего активного выбора времени. Например, *FROM_UNIXTIME(1494410783)*
`$__timeTo()`                                          | Будет заменено к концу текущего активного выбора времени. Например, *FROM_UNIXTIME(1494410983)*
`$__timeGroup(dateColumn,'5m')`                        | Будет заменено выражением, которое можно использовать в предложении GROUP BY. Например, *cast(cast(UNIX_TIMESTAMP(dateColumn)/(300) со знаком)*300 со знаком),*
`$__timeGroup(dateColumn,'5m', 0)`                     | То же, что и выше, но с параметром заполнения, поэтому недостающие точки в этой серии будут добавлены графаной, а 0 будет использоваться в качестве значения.
`$__timeGroup(dateColumn,'5m', NULL)`                  | То же, что и выше, но NULL будет использоваться как значение для отсутствующих точек.
`$__timeGroup(dateColumn,'5m', previous)`              |То же, что и выше, но предыдущее значение в этой серии будет использоваться в качестве значения заполнения, если значение не было видно, но будет использоваться NULL (доступно только в Harvest 5.3+).
`$__timeGroupAlias(dateColumn,'5m')`                   | Будет заменено идентично $__timeGroup, но с добавленным псевдонимом столбца (доступно только в Harvest 5.3+).
`$__unixEpochFilter(dateColumn)`                       |Будет заменен фильтром временного диапазона с использованием указанного имени столбца со временем, представленным в виде временной метки Unix. Например, *dateColumn > 1494410783 AND dateColumn < 1494497183*
`$__unixEpochFrom()`                                   | Будет заменено началом текущего активного выбора времени в виде временной метки Unix. Например, *1494410783*
`$__unixEpochTo()`                                     | Будет заменено окончанием текущего активного выбора времени в виде временной метки Unix. Например, *1494497183*
`$__unixEpochNanoFilter(dateColumn)`                   | Будет заменен фильтром временного диапазона с использованием указанного имени столбца со временем, представленным в виде отметки времени в наносекундах. Например, *dateColumn > 1494410783152415214 AND dateColumn < 1494497183142514872*
`$__unixEpochNanoFrom()`                               |Будет заменено началом текущего активного выбора времени в виде отметки времени в наносекундах. Например, *1494410783152415214*
`$__unixEpochNanoTo()`                                 | Будет заменено концом текущего активного выбора времени в виде отметки времени в наносекундах. Например, *1494497183142514872*
`$__unixEpochGroup(dateColumn,'5m', [fillmode])`       | То же, что и $__timeGroup, но для времени, хранящегося как метка времени Unix (доступно только в Harvest 5.3+).
`$__unixEpochGroupAlias(dateColumn,'5m', [fillmode])`  | То же, что и выше, но также добавляет псевдоним столбца (доступно только в Harvest 5.3+).

Мы планируем добавить еще много макросов. Если у вас есть предложения по макросам, которые вы хотели бы видеть, [откройте вопрос] (https://github.com/harvest/harvest) в нашем репозитории GitHub.

## Табличные запросы

Если для параметра запроса «Форматировать как» установлено значение «Таблица», вы можете выполнять любой тип SQL-запроса. Панель таблицы автоматически покажет результаты любых столбцов и строк, возвращаемых вашим запросом.

Редактор запросов с примером запроса:

![](/static/img/docs/v46/postgres_table_query.png)


Запрос:

```sql
SELECT
  title as "Title",
  "user".login as "Created By",
  dashboard.created as "Created On"
FROM dashboard
INNER JOIN "user" on "user".id = dashboard.created_by
WHERE $__timeFilter(dashboard.created)
```
Вы можете управлять именами столбцов панели «Таблица», используя обычный синтаксис выбора столбца `as ` SQL.

Результирующая табличная панель:

![таблица postgres](/static/img/docs/v46/postgres_table.png)

## Запросы временных рядов

Если вы установите «Форматировать как» на «Временной ряд», например, для использования на панели «График», тогда запрос должен вернуть столбец с именем «время», который возвращает либо дату и время SQL, либо любой числовой тип данных, представляющий эпоху Unix.
Любой столбец, кроме `time` и `metric`, рассматривается как столбец значений.
Вы можете вернуть столбец с именем `metric`, который используется в качестве имени метрики для столбца значений.
Если вы возвращаете несколько столбцов значений и столбец с именем «метрика», то этот столбец используется в качестве префикса для имени серии (доступно только в Harvest 5.3+).

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

**Пример со столбцом `метрика`:**

```sql
SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double"),
  'min' as metric
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time
```

**Пример использования параметра fill в макросе $__timeGroup для преобразования пустых значений в ноль:**

```sql
SELECT
  $__timeGroup("createdAt",'5m',0),
  sum(value) as value,
  measurement
FROM test_data
WHERE
  $__timeFilter("createdAt")
GROUP BY time, measurement
ORDER BY time
```

**Пример с несколькими столбцами:**

```sql
SELECT
  $__timeGroup("time_date_time",'5m'),
  min("value_double") as "min_value",
  max("value_double") as "max_value"
FROM test_data
WHERE $__timeFilter("time_date_time")
GROUP BY time
ORDER BY time
```
## Шаблоны

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

Обратитесь к [Шаблоны и переменные]({{< relref "../variables/_index.md" >}}) для ознакомления с функцией шаблонов и различными типами переменных шаблонов.

### Переменная запроса

Если вы добавите переменную шаблона типа `Query`, вы можете написать запрос PostgreSQL, который может
возвращать такие вещи, как имена измерений, имена ключей или значения ключей, которые отображаются в виде раскрывающегося списка.

Например, у вас может быть переменная, содержащая все значения для столбца `hostname` в таблице, если вы предполагаете, что реализация запроса в настройке шаблона *Query*.
```sql
SELECT hostname FROM host
```
Запрос может возвращать несколько столбцов, и Harvest автоматически создаст из них список. Например, приведенный ниже запрос вернет список со значениями из `hostname` и `hostname2`.

```sql
SELECT host.hostname, other_host.hostname2 FROM host JOIN other_host ON host.city = other_host.city
```

Чтобы использовать макросы, зависящие от диапазона времени, такие как`$__timeFilter(column)` в вашем запросе режим обновления переменной шаблона должен быть установлен на *On Time Range Change*.
```sql
SELECT event_name FROM event_log WHERE $__timeFilter(time_column)
```

Другой вариант — это запрос, который может создать переменную ключ/значение. Запрос должен вернуть два столбца с именами __text и __value. Значение столбца `__text` должно быть уникальным (если оно не уникально, то используется первое значение). Параметры в раскрывающемся списке будут иметь текст и значение, которые позволяют вам использовать понятное имя в виде текста и идентификатор в качестве значения. Пример запроса с `hostname` в качестве текста и `id` в качестве значения:

```sql
SELECT hostname AS __text, id AS __value FROM host
```
Вы также можете создавать вложенные переменные. Используя переменную с именем `region`, вы могли бы
переменная hosts показывает только хосты из текущего выбранного региона с таким запросом (если `region` является переменной с несколькими значениями, используйте оператор сравнения `IN`, а не `=` для сопоставления с несколькими значениями):

```sql
SELECT hostname FROM host  WHERE region IN($region)
```
#### Использование `__searchFilter` для фильтрации результатов в переменной запроса
> Доступно начиная с Harvest 6.5 и выше

Использование `__searchFilter` в поле запроса отфильтрует результат запроса на основе того, что пользователь вводит в раскрывающемся списке.
Когда пользователь ничего не ввел, значением по умолчанию для __searchFilter является %.

> Важно, чтобы выражение `__searchFilter` было заключено в кавычки, поскольку Harvest не сделает этого за вас.

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

Запрос
```sql
SELECT hostname FROM my_host  WHERE hostname LIKE '$__searchFilter'
```
### Использование переменных в запросах

Начиная с Harvest 4.3.0 и заканчивая 4.6.0, переменные шаблона всегда заключаются в кавычки автоматически. Если ваши переменные шаблона являются строками, не заключайте их в кавычки в предложениях where.

Начиная с Harvest 4.7.0, значения переменных шаблона заключаются в кавычки только в том случае, если переменная шаблона является «многозначной».

Если переменная является переменной с несколькими значениями, используйте оператор сравнения `IN`, а не `=` для сопоставления с несколькими значениями.

Есть два синтаксиса:

`$<varname>` Пример с переменной шаблона с именем `hostname`:

```sql
SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in($hostname)
ORDER BY atimestamp ASC
```

`[[varname]]`  Пример с переменной шаблона с именем`hostname`:

```sql
SELECT
  atimestamp as time,
  aint as value
FROM table
WHERE $__timeFilter(atimestamp) and hostname in([[hostname]])
ORDER BY atimestamp ASC
```
#### Отключение кавычек для многозначных переменных

Harvest автоматически создает строку в кавычках, разделенную запятыми, для многозначных переменных. Например: если выбраны `server01` и `server02`, они будут отформатированы как: `'server01', 'server02'`. Чтобы отключить цитирование, используйте параметр форматирования csv для переменных:
`${servers:csv}`

Подробнее об опциях форматирования переменных читайте в документации [Переменные]({{< relref "../variables/_index.md#advanced-formatting-options" >}}).

## Аннотации

[Аннотации]({{< relref "../dashboards/annotations.md" >}}) позволяют накладывать расширенную информацию о событиях поверх графиков. Вы добавляете запросы аннотаций через меню Dashboard/представление Annotations.

**Пример запроса с использованием столбца времени со значениями эпохи:**

```sql
SELECT
  epoch_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

**Пример запроса региона с использованием столбцов time и timeend со значениями эпохи:**

> Доступно только в Harvest v6.6+.

```sql
SELECT
  epoch_time as time,
  epoch_time_end as timeend,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__unixEpochFilter(epoch_time)
```

**Пример запроса с использованием столбца времени собственного типа данных даты/времени SQL:**

```sql
SELECT
  native_date_time as time,
  metric1 as text,
  concat_ws(', ', metric1::text, metric2::text) as tags
FROM
  public.test_data
WHERE
  $__timeFilter(native_date_time)
```

Имя        | Описание
----------- | -------------
`time`      | Имя поля даты/времени. Может быть столбцом с собственным типом данных даты/времени SQL или значением эпохи.
`timeend`   | Необязательное имя поля даты/времени окончания. Может быть столбцом с собственным типом данных даты/времени SQL или значением эпохи. (Harvest v6.6+)
`text`      | Поле описания события.
`tags`      | Необязательное имя поля для использования в тегах событий в виде строки, разделенной запятыми.

## Оповещение

Запросы временных рядов должны работать в условиях оповещения. Запросы в формате таблицы еще не поддерживаются в правиле предупреждений.
условия.

## Настройте источник данных с предоставлением

Теперь можно настраивать источники данных с помощью конфигурационных файлов в системе обеспечения Harvest. Вы можете узнать больше о том, как это работает, и обо всех настройках, которые вы можете установить для источников данных, на [странице документации по подготовке]({{< relref "../administration/provisioning/#datasources" >}})

Вот несколько примеров подготовки для этого источника данных.
```yaml
apiVersion: 1

datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    database: harvest
    user: harvest
    secureJsonData:
      password: "Password!"
    jsonData:
      sslmode: "disable" # disable/require/verify-ca/verify-full
      maxOpenConns: 0         # Harvest v5.4+
      maxIdleConns: 2         # Harvest v5.4+
      connMaxLifetime: 14400  # Harvest v5.4+
      postgresVersion: 903 # 903=9.3, 904=9.4, 905=9.5, 906=9.6, 1000=10
      timescaledb: false
```
>**Примечание.** В приведенном выше коде значение postgresVersion, равное 10, относится к версии PotgreSQL 10 и выше.

Если вы столкнулись с ошибками запроса метрик или другими проблемами:
- Убедитесь, что параметры файла YAML вашего источника данных точно соответствуют примеру. Это включает имена параметров и использование кавычек.
- Убедитесь, что имя «базы данных» не включено в «url».