Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Источники данныхbreadcrumb arrow PostgreSQLbreadcrumb arrow Устранение неполадок
Последнее обновление: августа 10, 2026

Устранение неполадок источника данных PostgreSQL

В этом документе приведена информация по устранению распространённых ошибок, с которыми вы можете столкнуться при использовании источника данных PostgreSQL в Grafana.

Ошибки подключения

Следующие ошибки возникают, когда Grafana не может установить или поддерживать подключение к PostgreSQL.

Не удалось подключиться к PostgreSQL

Сообщение об ошибке: failed to connect to ... : connect: connection refused или dial tcp: connect: connection refused

Причина: Grafana не может установить сетевое подключение к серверу PostgreSQL.

Решение:

  1. Убедитесь, что Host URL верен в конфигурации источника данных.
  2. Проверьте, что PostgreSQL запущен и доступен с сервера Grafana.
  3. Убедитесь, что порт верен (порт PostgreSQL по умолчанию — 5432).
  4. Убедитесь, что нет правил брандмауэра, блокирующих подключение.
  5. Проверьте, что PostgreSQL настроен на приём подключений с сервера Grafana в pg_hba.conf.
  6. Для Grafana Cloud убедитесь, что вы настроили Private data source connect, если ваш экземпляр PostgreSQL не является общедоступным.

Grafana Cloud не может достичь приватной базы данных

Сообщение об ошибке: dial tcp: connect: connection refused, i/o timeout или context deadline exceeded при использовании Grafana Cloud с базой данных в приватной сети.

Причина: Grafana Cloud работает в хостинговой среде и не может напрямую достичь базы данных на localhost, 127.0.0.1 или в приватных диапазонах IP (10.x, 172.16.x, 192.168.x). Это самая распространённая проблема при переходе с самостоятельно размещённой Grafana на Grafana Cloud.

Решение:

  1. Настройте Private data source connect (PDC), чтобы создать защищённый туннель между Grafana Cloud и вашей приватной сетью.
  2. Установите агент PDC на машине, имеющей сетевой доступ к вашему экземпляру PostgreSQL.
  3. Если вы сталкиваетесь с периодическими разрывами соединения с агентом PDC на базе Docker, попробуйте вместо него агент на базе бинарного файла. Это решило проблемы стабильности в некоторых средах.
  4. Обновите Host URL в настройках источника данных, чтобы использовать имя хоста, как оно видно из сети агента PDC (а не localhost).

Тайм-аут запроса

Сообщение об ошибке: «context deadline exceeded» или «i/o timeout»

Причина: Подключение к PostgreSQL истекло по тайм-ауту до получения ответа.

Решение:

  1. Проверьте сетевую задержку между Grafana и PostgreSQL.
  2. Убедитесь, что PostgreSQL не перегружен и не испытывает проблем с производительностью.
  3. Увеличьте настройку Max lifetime в конфигурации источника данных в разделе Connection limits.
  4. Уменьшите диапазон времени или сложность вашего запроса.
  5. Проверьте, не истекает ли по тайм-ауту подключение на каких-либо сетевых устройствах (балансировщиках нагрузки, прокси).

Хост не найден

Сообщение об ошибке: failed to connect to ... : hostname resolving error или lookup hostname: no such host

Причина: Имя хоста, указанное в конфигурации источника данных, не может быть разрешено.

Решение:

  1. Убедитесь, что имя хоста написано правильно.
  2. Проверьте, что разрешение DNS работает на сервере Grafana.
  3. Попробуйте использовать публичный IP-адрес базы данных вместо имени хоста. Это полезный шаг диагностики и может служить обходным решением, если проблема в разрешении DNS.
  4. Убедитесь, что сервер PostgreSQL доступен из сети сервера Grafana.
  5. Для Grafana Cloud поведение разрешения DNS может различаться в зависимости от региона стека и облачного провайдера. Если имя хоста разрешается из одного стека, но не из другого, попробуйте прямой IP-адрес и свяжитесь с поддержкой Grafana.

Ошибки аутентификации

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

Не указано имя пользователя PostgreSQL

Сообщение об ошибке: FATAL: no PostgreSQL user name specified in startup packet (SQLSTATE 28000)

Причина: Подключение к PostgreSQL было предпринято без имени пользователя. Обычно это означает, что поле Username в конфигурации источника данных пустое или было очищено.

Решение:

  1. Откройте настройки источника данных и убедитесь, что поле Username содержит допустимого пользователя PostgreSQL.
  2. Нажмите Save & test и подтвердите, что подключение успешно.
  3. Если имя пользователя исчезает после сохранения, проверьте вашу версию Grafana. Ошибка в Grafana v13.1 на канале fast release приводила к очистке поля имени пользователя при сохранении. Обновление до исправленного релиза или переключение на канал steady release решает эту проблему.

Ошибка аутентификации по паролю

Сообщение об ошибке: failed to connect to ... : server error: FATAL: password authentication failed for user "username" (SQLSTATE 28P01)

Причина: Имя пользователя или пароль неверны.

Решение:

  1. Убедитесь, что имя пользователя и пароль верны в конфигурации источника данных.
  2. Проверьте, что пользователь существует в PostgreSQL.
  3. Убедитесь, что пароль не истёк.
  4. Если пароль не указан, убедитесь, что настроен файл паролей PostgreSQL.

Доступ запрещён

Сообщение об ошибке: ERROR: permission denied for table table_name (SQLSTATE 42501) или ERROR: permission denied for schema schema_name (SQLSTATE 42501)

Причина: У пользователя базы данных нет разрешения на доступ к запрошенной таблице или схеме.

Решение:

  1. Убедитесь, что у пользователя есть разрешения SELECT на требуемых таблицах.

  2. Предоставьте необходимые разрешения:

    SQL 
    GRANT USAGE ON SCHEMA schema_name TO grafanareader;
GRANT SELECT ON schema_name.table_name TO grafanareader;

  3. Проверьте, что у пользователя есть доступ к правильной базе данных.

  4. Убедитесь, что путь поиска включает схему, содержащую ваши таблицы.

Нет записи pg_hba.conf

Сообщение об ошибке: failed to connect to ... : server error: FATAL: no pg_hba.conf entry for host "ip_address", user "username", database "database_name" (SQLSTATE 28000)

Причина: PostgreSQL не настроен на приём подключений с сервера Grafana.

Решение:

  1. Отредактируйте файл pg_hba.conf на сервере PostgreSQL.

  2. Добавьте запись, разрешающую подключения с сервера Grafana:

    text 
    host    database_name    username    grafana_ip/32    md5

  3. Перезагрузите конфигурацию PostgreSQL: SELECT pg_reload_conf();

  4. Если используется SSL, убедитесь, что указан правильный метод аутентификации (например, hostssl вместо host).

Ошибки TLS и сертификатов

Следующие ошибки возникают при проблемах с конфигурацией TLS.

Не удалось проверить сертификат

Сообщение об ошибке: «x509: certificate signed by unknown authority» или «certificate verify failed»

Причина: Grafana не может проверить TLS-сертификат, предоставленный PostgreSQL.

Решение:

  1. Установите TLS/SSL Mode в соответствующий уровень (require, verify-ca или verify-full).
  2. Если используется самоподписанный сертификат, добавьте сертификат CA в TLS/SSL Auth Details.
  3. Убедитесь, что цепочка сертификатов полна и действительна.
  4. Убедитесь, что срок действия сертификата не истёк.
  5. Только для тестирования установите TLS/SSL Mode в disable (не рекомендуется для продакшена).

SSL не поддерживается

Сообщение об ошибке: failed to connect to ... : server refused TLS connection или server does not support SSL

Причина: Сервер PostgreSQL не настроен для SSL-подключений, но источник данных требует SSL.

Решение:

  1. Установите TLS/SSL Mode в disable, если SSL не требуется.
  2. В качестве альтернативы включите SSL на сервере PostgreSQL, настроив ssl = on в postgresql.conf.
  3. Убедитесь, что на сервере настроены действительные SSL-сертификаты.

Ошибка клиентского сертификата

Сообщение об ошибке: «TLS: failed to find any PEM data in certificate input» или «could not load client certificate»

Причина: Клиентский сертификат или ключ недействителен или имеет неверный формат.

Решение:

  1. Убедитесь, что сертификат и ключ имеют формат PEM.
  2. Убедитесь, что путь к файлу сертификата верен и файл доступен для чтения процессом Grafana.
  3. Проверьте, что сертификат и ключ соответствуют друг другу (принадлежат одной паре ключей).
  4. Если используется содержимое сертификата, убедитесь, что вы вставили полный сертификат, включая заголовки.

Ошибки базы данных

Следующие ошибки возникают при проблемах с конфигурацией базы данных.

База данных не существует

Сообщение об ошибке: failed to connect to ... : server error: FATAL: database "database_name" does not exist (SQLSTATE 3D000)

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

Решение:

  1. Убедитесь в правильности имени базы данных в конфигурации источника данных.
  2. Проверьте, что база данных существует: \l в psql или SELECT datname FROM pg_database;
  3. Убедитесь, что имя базы данных чувствительно к регистру и совпадает точно.
  4. Убедитесь, что у пользователя есть разрешение на подключение к базе данных.

Отношение не существует

Сообщение об ошибке: ERROR: relation "table_name" does not exist (SQLSTATE 42P01)

Причина: Указанная таблица или представление не существует, или пользователь не может получить к ним доступ.

Решение:

  1. Убедитесь, что имя таблицы верно и существует в базе данных.
  2. Проверьте имя схемы, если таблица находится не в схеме public.
  3. Используйте полные имена: schema_name.table_name.
  4. Убедитесь, что у пользователя есть разрешение SELECT на таблицу.
  5. Проверьте путь поиска: SHOW search_path;

Ошибки запросов

Следующие ошибки возникают при проблемах с синтаксисом SQL или выполнением запроса.

Запрос усечён двойным дефисом в строковых литералах

Сообщение об ошибке: неожиданные синтаксические ошибки или усечённые результаты, когда строковые значения содержат -- (двойной дефис).

Причина: В более старых версиях Grafana парсер удаления SQL-комментариев некорректно обрабатывал -- внутри строк в одинарных кавычках. Запрос вида WHERE name = 'value--suffix' усекался на --, из-за чего остальная часть запроса молча отбрасывалась. Это также затрагивало строки с последовательными дефисами (например, '10YDE-VE-------2' усекалось до '10YDE-VE).

Это было исправлено с помощью парсера удаления комментариев, учитывающего кавычки (PR #121772). Исправление также обрабатывает строки PostgreSQL в долларовых кавычках ($$...$$). Оно доступно в Grafana 13.1 и более поздних версиях, Grafana 13.0.2 и более поздних версиях, а также в следующих патч-релизах линии 12.x: 12.1.11, 12.2.9, 12.3.7 и 12.4.3.

Решение:

  1. Обновитесь до релиза Grafana, включающего исправление (13.1+, 13.0.2+ или один из патч-релизов линии 12.x, перечисленных выше).

  2. Если вы не можете обновиться немедленно, обойдите проблему, используя конкатенацию строк PostgreSQL, чтобы избежать литерала -- в ваших запросах:

    SQL 
    WHERE name = 'value' || '--' || 'suffix'

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

Синтаксическая ошибка запроса

Сообщение об ошибке: ERROR: syntax error at or near "keyword" (SQLSTATE 42601)

Причина: SQL-запрос содержит недопустимый синтаксис.

Решение:

  1. Проверьте синтаксис вашего запроса на предмет опечаток или недопустимых ключевых слов.
  2. Убедитесь, что имена столбцов и таблиц правильно заключены в кавычки, если они содержат специальные символы или являются зарезервированными словами.
  3. Используйте двойные кавычки для идентификаторов: "column_name".
  4. Протестируйте запрос напрямую в клиенте PostgreSQL, таком как psql.

Столбец не существует

Сообщение об ошибке: ERROR: column "column_name" does not exist (SQLSTATE 42703)

Причина: Указанное имя столбца неверно или не существует в таблице.

Решение:

  1. Убедитесь, что имя столбца написано правильно.
  2. Учтите, что имена столбцов в PostgreSQL чувствительны к регистру, когда заключены в кавычки.
  3. Используйте правильное заключение в кавычки для имён столбцов: "Column_Name" для имён, чувствительных к регистру.
  4. Убедитесь, что столбец существует в таблице: \d table_name в psql.

Не найден столбец времени

Сообщение об ошибке: «no time column found» или визуализация временного ряда не показывает данных

Причина: Результат запроса не содержит правильно отформатированного столбца времени.

Решение:

  1. Убедитесь, что ваш запрос включает столбец с именем time, возвращающий временную метку или значение epoch.
  2. Используйте псевдоним, чтобы переименовать ваш столбец времени: SELECT created_at AS time.
  3. Убедитесь, что столбец времени имеет тип timestamp, timestamptz или числовое значение epoch.
  4. Упорядочьте результаты по столбцу времени: ORDER BY time ASC.

Ошибка разворачивания макроса

Сообщение об ошибке: «macro ‘$__timeFilter’ not found» или некорректные результаты запроса с макросами

Причина: Макросы Grafana не разворачиваются должным образом.

Решение:

  1. Убедитесь, что синтаксис макроса верен, например $\_\_timeFilter(time_column).
  2. Убедитесь, что имя столбца, переданное макросу, существует в вашей таблице.
  3. Проверьте, что макрос не находится внутри SQL-комментария (-- или /* */). Grafana удаляет комментарии перед разворачиванием макросов, поэтому макросы внутри комментариев молча игнорируются.
  4. Используйте переключатель Preview в режиме Builder, чтобы увидеть развёрнутый запрос.
  5. Откройте Query inspector, чтобы просмотреть точный SQL, отправленный в PostgreSQL после разворачивания макросов.
  6. Для макросов, основанных на времени, убедитесь, что столбец содержит данные временных меток.

Проблемы производительности

Следующие проблемы связаны с медленным выполнением запросов или ограничениями ресурсов.

Тайм-аут запроса

Сообщение об ошибке: «canceling statement due to statement timeout» или «query timeout»

Причина: Запрос выполнялся дольше настроенного тайм-аута.

Решение:

  1. Уменьшите диапазон времени вашего запроса.
  2. Добавьте индексы на столбцы, используемые в предложениях WHERE и соединениях.
  3. Используйте макрос $\_\_timeFilter, чтобы ограничить данные диапазоном времени дашборда.
  4. Увеличьте тайм-аут инструкции в PostgreSQL, если у вас есть административный доступ.
  5. Оптимизируйте ваш запрос, чтобы уменьшить сложность.

Слишком много подключений

Сообщение об ошибке: failed to connect to ... : server error: FATAL: too many connections for role "username" (SQLSTATE 53300) или connection pool exhausted

Причина: Достигнуто максимальное количество подключений к PostgreSQL.

Решение:

  1. Уменьшите настройку Max open подключений в конфигурации источника данных.
  2. Увеличьте max_connections в postgresql.conf PostgreSQL, если у вас есть административный доступ.
  3. Проверьте наличие утечек подключений в других приложениях, подключающихся к той же базе данных.
  4. Включите Auto max idle, чтобы автоматически управлять простаивающими подключениями.

Медленная производительность запросов

Причина: Запросы выполняются долго.

Решение:

  1. Уменьшите диапазон времени вашего запроса.
  2. Добавьте подходящие индексы в ваши таблицы.
  3. Используйте макрос $\_\_timeFilter, чтобы ограничить сканируемые данные.
  4. Увеличьте настройку Min time interval, чтобы уменьшить количество точек данных.
  5. Используйте EXPLAIN ANALYZE в PostgreSQL, чтобы выявить узкие места запроса.
  6. Рассмотрите использование материализованных представлений для сложных агрегаций.

Ошибки провижининга

Следующие ошибки возникают при провижининге источника данных через YAML.

Недопустимая конфигурация провижининга

Сообщение об ошибке: «metric request error» или проверка источника данных завершается неудачно после провижининга

Причина: Файл YAML провижининга содержит некорректную конфигурацию.

Решение:

  1. Убедитесь, что имена параметров точно соответствуют ожидаемому формату.
  2. Убедитесь, что имя базы данных не включено в URL.
  3. Используйте правильный формат для URL: hostname:port.
  4. Проверьте, что строковые значения правильно заключены в кавычки в файле YAML.
  5. Обратитесь к примеру провижининга за правильным форматом.

Пример правильной конфигурации:

YAML 
datasources:
  - name: Postgres
    type: postgres
    url: localhost:5432
    user: grafana
    secureJsonData:
      password: 'Password!'
    jsonData:
      database: grafana
      sslmode: 'disable'

Другие распространённые проблемы

Следующие проблемы не выдают конкретных сообщений об ошибках, но встречаются часто.

Пустые результаты запроса

Причина: Запрос не возвращает данных.

Решение:

  1. Убедитесь, что диапазон времени включает данные в вашей базе данных.
  2. Проверьте, что имена таблиц и столбцов верны.
  3. Протестируйте запрос напрямую в PostgreSQL.
  4. Убедитесь, что фильтры не исключают все данные.
  5. Убедитесь, что макрос $\_\_timeFilter использует правильный столбец времени.

Функции TimescaleDB недоступны

Причина: Специфичные для TimescaleDB функции, такие как time_bucket, недоступны в конструкторе запросов.

Решение:

  1. Включите переключатель TimescaleDB в конфигурации источника данных в разделе PostgreSQL Options.
  2. Убедитесь, что TimescaleDB установлен и включён в вашей базе данных PostgreSQL.
  3. Проверьте, что расширение timescaledb создано: CREATE EXTENSION IF NOT EXISTS timescaledb;

Данные выглядят задержанными или отсутствуют последние точки

Причина: Визуализация не показывает самые последние данные.

Решение:

  1. Проверьте диапазон времени дашборда и настройки обновления.
  2. Убедитесь, что Min time interval не установлен слишком высоко.
  3. Убедитесь, что данные зафиксированы в базе данных (а не находятся в незафиксированной транзакции).
  4. Проверьте наличие проблем синхронизации часов между Grafana и PostgreSQL.

Получение дополнительной помощи

Если проблемы сохраняются после следования этому руководству по устранению неполадок:

  1. Обратитесь к документации PostgreSQL за рекомендациями, специфичными для базы данных.
  2. Просмотрите форумы сообщества Grafana на предмет похожих проблем.
  3. Свяжитесь с поддержкой Grafana, если вы пользователь Cloud Pro, Cloud Contracted или Enterprise.
  4. При сообщении о проблемах указывайте:
    • Версию Grafana
    • Версию PostgreSQL
    • Сообщения об ошибках (удалите конфиденциальную информацию)
    • Шаги для воспроизведения
    • Соответствующую конфигурацию, такую как настройки источника данных, режим TLS и лимиты подключений (удалите пароли и другие учётные данные)