Grafana 的 Sqlyze 数据源

Grafana Sqlyze 数据源

此插件尚未在 Grafana Cloud 中得到支持。

Grafana Sqlyze Data Source 插件是一个多功能的插件，允许您使用单一查询语言：SQL，连接到数百个数据源。无论您的数据是存储在传统 SQL 数据库、NoSQL 数据库还是其他非 SQL 数据源中，此插件都可以让您使用 SQL 查询它们。

概览

Sqlyze 插件利用 ODBC (Open Database Connectivity) 接口连接到各种数据库。ODBC 是一种用于访问数据库管理系统 (DBMS) 的标准 API。下图说明了插件如何与数据连接堆栈中的不同组件交互。

+-----------------------------------+
|           Sqlyze plugin           |
| +-----------------+               |
| |   Plugin        |               |
| +-----------------+               |
|         |                         |
|         | ODBC API Calls          |
|         v                         |
| +-------------------------+       |
| | unixODBC Driver Manager |       |
| +-------------------------+       |
|         |                         |
|         | Directs ODBC Calls      |
|         v                         |
+-----------------------------------+
          |
          v
+----------------+
|  ODBC Driver   |
| (e.g., MySQL,  | (ODBC Drivers that are needed to be installed for your specific DBMS / DB)
| PostgreSQL)    |
+----------------+
          |
          | Translates ODBC Calls to DB-Specific Commands
          v
+-----------------+
|      DBMS       | (Database Management System)
+-----------------+
          |
          | Manages Data Access
          v
+-----------------+
|    Database     |
+-----------------+

配置

驱动配置

插件需要配置两个基本字段：Driver 和 Timeout。

Driver: 这是系统上 ODBC 驱动的绝对路径。ODBC 驱动特定于您要连接的数据库管理系统 (DBMS)，必须单独安装。
Timeout: 此字段设置数据库连接的超时时间（秒）。

连接字符串设置

ODBC 在底层使用连接字符串来连接 DBMS。此连接字符串由驱动路径、超时以及设置 UI 中驱动设置部分提供的任何其他键值组合串联而成。以下是 IBM DB2 数据库的连接字符串示例：

Driver=/home/ibm/db2/V11.5/lib64/libdb2o.so;Timeout=0;Hostname=db2.server.com;Port=50000;Uid=testUserUID;Pwd=Testing123;DB=testdb

连接字符串格式可能因您连接的数据库而异。有关特定的连接字符串，您可以参考 ConnectionStrings.com 等资源。

Driver 字段还可以包含对 odbc.ini 文件中驱动配置的引用，而不是直接引用驱动，例如：

`Driver={MyDB2Database};Timeout=0;Hostname=db2.server.com;Port=50000;Uid=testUserUID;Pwd=Testing123;DB=testdb

测试和排查 ODBC 连接

正确设置 ODBC 连接对于确保数据库通信按预期工作至关重要。本节涵盖了 ODBC 所需的关键配置文件，以及帮助您测试和排查设置的工具和命令。

下面提到的 CLI 工具可能未安装在您的系统上，您很可能需要安装 unixodbc 和/或 unixodbc-dev（如果您使用的是 ubuntu），使用以下命令：

apt-get install unixodbc unixodbc-dev

ODBC 配置文件

odbcinst -j

odbcinst -j 命令用于显示重要 ODBC 配置文件的位置。这有助于验证您的系统设置是否正确。

$ odbcinst -j
unixODBC 2.3.7
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
USER DATA SOURCES..: /home/username/.odbc.ini

`odbc.ini` 文件示例

odbc.ini 文件用于定义 DSN（数据源名称），DSN 代表单个数据库连接。每个 DSN 都指定了特定数据库的连接参数。

[ODBC Data Sources]
MyDB2Database=IBM DB2 ODBC Driver

[MyDB2Database]
Description=IBM DB2 Database
Driver=/home/ibm/db2/V11.5/lib64/libdb2o.so
Database=testdb
Hostname=db2.server.com
Port=50000
Uid=testUserUID
Pwd=Testing123

[ODBC]
Trace=Yes
TraceFile=/tmp/sql.log

`odbcinst.ini` 文件示例

odbcinst.ini 文件用于定义系统上安装的 ODBC 驱动。每个部分都代表一个不同的驱动。

[Db2]
Description = Db2 Driver
Driver = <instance_path>/lib/libdb2o.so
fileusage=1
dontdlclose=1

使用 `odbc_cli` 验证配置文件

odbc_cli 是一个用于检查 ODBC 配置文件的工具，例如确保正确的驱动路径和 DSN 配置。

$ odbc_cli verify
Configuration file(s) verified:
- /etc/odbcinst.ini
- /etc/odbc.ini

使用 `isql` 验证连接

isql 工具是一个交互式 SQL shell，可用于通过 ODBC 测试与数据库的连接。在启用 Grafana 插件之前，它特别有助于诊断 ODBC 配置问题。它与 unixodbc/unixodbc-dev 软件包一起安装。

$ isql MyDB2Database
+---------------------------------------+
| Connected!                            |
|                                       |
| SQL>                                  |
+---------------------------------------+

时间序列

要在 Grafana 中格式化时间序列数据的 SQL 查询，请在 SQL 查询中使用别名 as time。这允许 Grafana 识别时间戳并正确渲染时间序列数据。

查询示例

select date_start as time, foo, avg(bar) as bar
from foo_bar

平台支持

此插件依赖 ODBC 连接各种数据库。它包含 unixODBC 库，该库促进了 ODBC 通信，但不包含实用程序（如命令行工具）。由于 ODBC 在 Windows、Linux 和 macOS 等操作系统上得到广泛支持，因此该插件是跨平台的。然而，在非 Linux 系统上可能需要安装一些额外的依赖项。

在 Linux ARM 或 macOS 上使用 ODBC

安装 unixODBC

要在 Linux ARM 或 macOS 上使用 ODBC，必须安装 unixODBC。此库对于这些平台上的 ODBC 操作至关重要。安装说明可在 IBM 文档中找到，了解如何安装 unixODBC Driver Manager。

已知驱动和设置简要列表

DB2

可以从 IBM Fix Central 下载，您可以在其中选择 DB2 版本和平台：https://www.ibm.com/support/fixcentral/swg/selectFixes?parent=ibm%7EInformation%20Management&product=ibm/Information+Management/IBM+Data+Server+Client+Packages&release=11.5.*&platform=Mac+OSX&function=all
驱动设置 - 设置驱动安装路径并添加所需设置（以下是 MacOS 示例）

设置	示例值
Driver	/Applications/dsdriver/lib/libdb2o.dylib
Timeout (seconds)	10
host	127.0.0.1
port	50000
uid	db2inst1
pwd	••••••••••••
database	sample

Impala

Databricks

第三方驱动

其他第三方驱动的设置各不相同，但 Sqlyze 插件设计为接受 ODBC 驱动所需的任何键值对。始终参考驱动供应商提供的文档以获取最准确的配置设置。

常见错误

unixODBC 错误将以错误的形式显示在 UI 中。以下是配置插件时可能遇到的一些常见错误列表。

SQLDriverConnect: {08001} [IBM][CLI Driver] SQL1024N A database connection does not exist. SQLSTATE=08003

当 ODBC 驱动无法启动与数据库的连接时，可能会发生此错误。

SQLDriverConnect: {01000} [unixODBC][Driver Manager]Can't open lib '/home/driver/odbc_cli/clidriver/lib/libdb2.so' : file not found

当驱动文件（本例中为 libdb2.so）缺少关联的依赖项时，可能会发生此错误。您可以通过运行 ldd CLI 工具来验证，例如在 grafana 容器内运行：ldd /home/driver/odbc_cli/clidriver/lib/libdb2.so。请确保将此错误以及您的 Linux 版本报告给我们的团队，以便我们可以包含所有必要的依赖项。