[comment]: # ({cd592738-68c88a1c})
# 8 数据库监控

[comment]: # ({/cd592738-68c88a1c})

[comment]: # ({52947967-b5170fd3})
#### 概述

Zabbix 前端中的 *Database monitor* 监控项类型用于 ODBC 监控（ODBC 检查）。

ODBC 是一种用于访问数据库管理系统（DBMS）的 C 编程语言中间件 API。
ODBC 概念由 Microsoft 开发，后来移植到其他平台。

Zabbix 可以查询任何受 ODBC 支持的数据库。
为此，Zabbix 不会直接连接到数据库，而是使用 ODBC 接口以及在 ODBC 中配置的驱动程序。
这使得可以更高效地对不同数据库进行多种用途的监控（例如，检查特定数据库队列、使用统计信息等）。

Zabbix 支持 unixODBC，它是最常用的开源 ODBC API 实现之一。

::: noteimportant
另请参见：ODBC 检查的[已知问题](/manual/installation/known_issues#odbc-checks)。
:::

[comment]: # ({/52947967-b5170fd3})

[comment]: # ({47a0f71f-bf6fd8ba})
#### 安装 unixODBC

推荐的 unixODBC 安装方式是使用 Linux 操作系统默认的软件包仓库。
在大多数常见的 Linux 发行版中，unixODBC 默认已包含在软件包仓库中。
如果没有可用的软件包，可以从 unixODBC 主页获取源文件：<http://www.unixodbc.org/download.html>。

要安装 unixODBC，请使用所选系统的软件包管理器：

```bash
# 对于 Ubuntu/Debian 系统：
apt install unixodbc unixodbc-dev

# 对于基于 RedHat/Fedora 的系统：
dnf install unixODBC unixODBC-devel

# 对于基于 SUSE 的系统：
zypper in unixODBC-devel
```

::: noteimportant
`unixodbc-dev` 或 `unixODBC-devel` 软件包是将 Zabbix 编译为支持 unixODBC 所必需的。
要启用 ODBC 支持，应使用以下[配置选项](/manual/installation/install/sources#configure-the-sources)编译 Zabbix：
<br><br>

    --with-unixodbc[=ARG] # Use ODBC driver against unixODBC package.

:::

[comment]: # ({/47a0f71f-bf6fd8ba})

[comment]: # ({07af6a39-eea09ed7})
#### 安装 unixODBC 驱动程序

unixODBC 数据库驱动程序应该为将要监控的数据库安装。 要查看支持的数据库和驱动程序列表，请访问 unixODBC 主页：: <http://www.unixodbc.org/drivers.html>.

::: noteclassic
在某些 Linux 发行版中，数据库驱动程序包含在软件包库中。
:::

[comment]: # ({/07af6a39-eea09ed7})

[comment]: # ({d49fdb52-e1911043})
##### MySQL

要安装 MySQL 的 unixODBC 数据库驱动程序，请使用您所选择的系统的软件包管理工具：

```bash
# 对于 Ubuntu/Debian 系统:
apt install odbc-mariadb

# 对于 RedHat/Fedora-based 系统:
dnf install mariadb-connector-odbc

# 对于 SUSE-based 系统:
zypper install mariadb-connector-odbc
```

如果不使用包管理器安装数据库驱动程序，请参考`mysql-connector-odbc`[MySQL 文档](https://dev.mysql.com/downloads/connector/odbc/) , 或  `mariadb-connector-odbc`[MariaDB 文档](https://mariadb.com/kb/en/mariadb-connector-odbc/) 。

[comment]: # ({/d49fdb52-e1911043})

[comment]: # ({1b513583-0842efba})
##### PostgreSQL

要安装 PostgreSQL 的 unixODBC 数据库驱动程序，请使用您所选择的系统的软件包管理工具:

```bash
# 对于 Ubuntu/Debian 系统:
apt install odbc-postgresql

# 对于 RedHat/Fedora-based 系统:
dnf install postgresql-odbc

# 对于 SUSE-based 系统:
zypper install psqlODBC
```

如果不使用包管理器安装数据库驱动程序，请参考[PostgreSQL 文档](https://www.postgresql.org/download/linux/).

[comment]: # ({/1b513583-0842efba})

[comment]: # ({b4e6cb7e-88097de9})
##### Oracle

要安装 unixODBC 数据库驱动程序，请参考 [Oracle documentation](https://www.oracle.com/database/technologies/releasenote-odbc-ic.html).

[comment]: # ({/b4e6cb7e-88097de9})

[comment]: # ({0a04e88d-f1ce859d})
##### MSSQL

要安装 MSSQL unixODBC 数据库驱动，请使用所选系统的软件包管理器：

```bash
# 对于 Ubuntu/Debian 系统：
apt install tdsodbc

# 对于基于 RedHat/Fedora 的系统（EPEL 软件包：https://docs.fedoraproject.org/en-US/epel/）：
dnf install epel-release
dnf install freetds

# 对于基于 SUSE 的系统：
zypper install libtdsodbc0
```

如果不使用软件包管理器安装数据库驱动，请参阅 [FreeTDS 用户指南](http://www.freetds.org/userguide/)。

[comment]: # ({/0a04e88d-f1ce859d})

[comment]: # ({f24fde2e-b15e771b})
#### 配置 unixODBC

要对 unixODBC 进行配置，需编辑 `odbcinst.ini` 和 `odbc.ini` 文件。 可通过执行如下命令来确认这些文件的位置：

```bash
odbcinst -j
```

命令的输出应该包含类似于以下内容信息：

```bash
unixODBC 2.3.9
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
```

[comment]: # ({/f24fde2e-b15e771b})

[comment]: # ({72609b6e-d99c28e7})
##### odbcinst.ini

`odbcinst.ini` 文件列出已安装的 ODBC 数据库驱动程序。 如果缺少 `odbcinst.ini` 文件，则需手动创建它。

```ini
[TEST_MYSQL]
Description=ODBC for MySQL
Driver=/usr/lib/libmyodbc5.so
FileUsage=1
```

|参数|描述|
|--|--------|
|TEST_MYSQL|数据库驱动名称.|
|Description|数据库驱动描述.|
|Driver|数据库驱动库位置.|
|FileUsage|确定数据库驱动是否支持在没有访问本地文件支持的情况下连接到数据库服务器（0）；支持从文件读取数据（1）；支持将数据写入文件（2）。|
|Threading|线程串行化级别。PostgreSQL 支持此功能。<br>自 1.6 版本起，如果驱动管理器构建时包含了线程支持，您可能可以添加另一个驱动程序条目。|

[comment]: # ({/72609b6e-d99c28e7})

[comment]: # ({f10754c8-207ccff7})
##### odbc.ini

`odbc.ini` 文件用于配置数据源。
请注意，支持的参数列表取决于数据库驱动程序（例如，Oracle 数据库可能使用 ServerName 而不是 Server，等等）。

```ini
[TEST_MYSQL]
Description=MySQL Test Database
Driver=mysql
Server=127.0.0.1
User=root
Password=
Port=3306
Socket=
Database=zabbix
```

|Parameter|Description|
|--|--------|
|TEST_MYSQL|数据源名称（DSN）。|
|Description|数据源描述。|
|Driver|数据库驱动程序名称（如 `odbcinst.ini` 中所指定）。|
|Server|数据库服务器 IP/DNS。|
|User|用于连接的数据库用户。|
|Password|数据库用户密码。|
|Port|数据库连接端口。|
|Socket|数据库连接套接字。|
|Database|数据库名称。|

有关其他可能的配置参数选项，请参见 [MySQL documentation](https://dev.mysql.com/doc/connector-odbc/en/connector-odbc-configuration-connection-parameters.html)。

[comment]: # ({/f10754c8-207ccff7})

[comment]: # ({e0fd367c-fed5e483})
PostgreSQL 的 `odbc.ini` 文件可能包含其他参数：

```ini
[TEST_PSQL]
Description=PostgreSQL Test Database
Driver=postgresql
Username=zbx_test
Password=zabbix
Servername=127.0.0.1
Database=zabbix
Port=5432
ReadOnly=No
Protocol=8.0+
ShowOidColumn=No
FakeOidIndex=No
RowVersioning=No
ShowSystemTables=No
Fetch=Yes
BoolsAsChar=Yes
SSLmode=Require
ConnSettings=
```

|参数|描述|
|--|--------|
|ReadOnly|指定数据库连接是否仅允许读取操作（`SELECT` 查询）并限制修改操作（`INSERT`、`UPDATE` 和 `DELETE` 语句）；适用于数据应保持不变的场景。|
|Protocol|PostgreSQL 后端协议版本（使用 SSL 连接时将被忽略）。|
|ShowOidColumn|指定是否在 SQLColumns 中包含对象 ID（OID）。|
|FakeOidIndex|指定是否在 OID 上创建一个伪唯一索引。|
|RowVersioning|指定是否启用应用程序在尝试更新某一行时检测数据是否已被其他用户修改。请注意，此参数可以加快更新过程，因为更新一行时，不需要在 `WHERE` 子句中指定每一个列。|
|ShowSystemTables|指定数据库驱动程序是否应在 SQLTables 中将系统表视为常规表；这有助于提高可访问性，使系统表可见。|
|Fetch|指定驱动程序是否应自动使用 declare cursor/fetch 来处理 `SELECT` 语句并维护一个包含 100 行的缓存。|
|BoolsAsChar|控制布尔类型的映射。<br>如果设置为 “Yes”，布尔值将映射为 `SQL_CHAR`；否则将映射为 `SQL_BIT`。|
|SSLmode|指定连接的 SSL 模式。|
|ConnSettings|连接时发送到后端的其他设置。|

[comment]: # ({/e0fd367c-fed5e483})

[comment]: # ({2e87263e-93c68b7f})
要检验 ODBC 连接是否成功建立，您可以使用 `isql` 工具（包含在 `unixODBC` 软件包内）：

```bash
isql test
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+
```

[comment]: # ({/2e87263e-93c68b7f})

[comment]: # ({458da043-ca784f43})
#### 在 Zabbix 前端中配置监控项

配置一个 **数据库监控** [监控项](/manual/config/items/item#overview)。

![](../../../../../assets/en/manual/config/items/itemtypes/db_monitor.png){width="600"}

所有必填输入字段都以红色星号标记。

对于数据库监控监控项，您必须指定：

|   |   |
|--|--------|
|*Type*|在此选择“Database monitor”。|
|*Key*|输入以下受支持的监控项键之一：<br>[**db.odbc.select[]**](#db.odbc.select) - 此监控项返回一个值（SQL 查询结果第一行第一列的值）；<br>[**db.odbc.get[]**](#db.odbc.get) - 此监控项以 JSON 格式返回多行/多列；<br>[**db.odbc.discovery[]**](#db.odbc.discovery) - 此监控项返回低级别发现数据。|
|*User name*|输入数据库用户名（最多 255 个字符）。<br>如果数据库用户名已在 `odbc.ini` 文件中指定，则此参数为可选。<br>如果使用连接字符串，且 *User name* 字段不为空，则会将其作为 `UID=<user>` 追加到连接字符串中。|
|*Password*|输入数据库用户密码（最多 255 个字符）。<br>如果密码已在 `odbc.ini` 文件中指定，则此参数为可选。<br>如果使用连接字符串，且 *Password* 字段不为空，则会将其作为 `PWD=<password>` 追加到连接字符串中。<br>此字段支持特殊字符。<br>密码将追加在用户名之后，例如 `UID=<username>;PWD=P?;)*word`。<br>要测试生成的字符串，您可以运行以下命令：<br>`isql -v -k 'Driver=libmaodbc.so;Database=zabbix;UID=zabbix;PWD=P?;)*word'`|
|*SQL query*|输入 SQL 查询。<br>请注意，对于 `db.odbc.select[]`，查询必须只返回一个值。|
|*Type of information*|在此选择查询将返回的信息类型。<br>如果信息类型选择不正确，该监控项将变为不受支持。|

[comment]: # ({/458da043-ca784f43})

[comment]: # ({b2cf88bb-06f9d2eb})
**重要说明**

-   如果在服务器或 proxy 配置中未启动任何 *odbc poller* 进程，数据库监控项将变为不受支持。
    要启用 ODBC poller，请在 Zabbix [服务器](/manual/concepts/server/server_params) 配置文件中设置 `StartODBCPollers` 参数；对于由 proxy 执行的检查，请在 Zabbix [proxy](/manual/concepts/proxy/proxy_params) 配置文件中设置该参数。
-   [监控项配置](/manual/config/items/item#configuration) 表单中的 *Timeout* 参数值将用作 ODBC 登录超时和查询执行超时。
    请注意，如果已安装的 ODBC 驱动程序不支持这些超时设置，则它们可能会被忽略。
-   SQL 命令必须返回结果集，就像任何使用 `select` 语句的查询一样。
    查询语法将取决于处理它们的 RDBMS。
    对存储过程的请求语法必须以 `call` 关键字开头。

[comment]: # ({/b2cf88bb-06f9d2eb})

[comment]: # ({99bf7f73-0188aaa2})
#### 监控项键值详细信息

不带尖角括号的参数必填项。用尖角括号 **<**  **>** 标记的参数是可选的。

[comment]: # ({/99bf7f73-0188aaa2})

[comment]: # ({1a75e5c0-13edfcd4})
##### db.odbc.select[<唯一简短描述>,<配置dsn>,<连接字符串>] {#db.odbc.select}

<br>
返回一个值，即 SQL 查询结果中第一行的第一列。
<br>
返回值：根据 SQL 查询而定。

参数:

-   **unique short description** -一个唯一简短的描述来标识监控项（用于触发器等）；
-   **dsn** - 数据源名称（如在 `odbc.ini` 中指定的）；
-   **connection string** - 连接字符串（可能包含特定于驱动程序的参数）。

注释：

-   `dsn` will be ignored.尽管 `dsn` 和  `connection string`是可选参数，但至少需要其中一个；如果两个都被定义了，`dsn` 将被忽略。
-   如果查询返回多个列，只有第一列会被读取。如果查询返回多行，只有第一行会被读取。

[comment]: # ({/1a75e5c0-13edfcd4})

[comment]: # ({77183579-ebf5d449})
##### db.odbc.get[<unique short description>,<dsn>,<connection string>] {#db.odbc.get}

<br>
将 SQL 查询结果转换为 JSON 数组。<br>
返回值：*JSON object*。

参数：

-   **unique short description** - 用于标识监控项的唯一简短描述（供触发器等使用）；
-   **dsn** - 数据源名称（按 `odbc.ini` 中的定义）；
-   **connection string** - 连接字符串（可包含特定驱动程序的参数）。

注释：

-   尽管 `dsn` 和 `connection string` 是可选参数，但至少需要提供其中一个；如果两者都定义了，则会忽略 `dsn`。
-   可以返回 JSON 格式的多行/多列数据。
    此监控项可用作主监控项，在一次系统调用中收集所有数据，而在依赖监控项中可使用 JSONPath 预处理提取单个值。
    有关返回格式的更多信息，请参见低级别发现中使用的返回格式的[示例](/manual/discovery/low_level_discovery/examples/sql_queries#using-db-odbc-get)。

示例：

    # MySQL ODBC 驱动程序 5 的连接：
    db.odbc.get[MySQL example,,"Driver=/usr/local/lib/libmyodbc5a.so;Database=master;Server=127.0.0.1;Port=3306"]

[comment]: # ({/77183579-ebf5d449})

[comment]: # ({f6dfe740-c8148c95})
##### db.odbc.discovery[<唯一简短描述>,<配置dsn>,<连接字符串>] {#db.odbc.discovery}

<br>
将 SQL 查询结果转换为 JSON 数组，用于 [低级别自动发现](/manual/discovery/low_level_discovery/examples/sql_queries).
查询结果中的列名被转换为与发现字段值配对的低级发现宏名称。 
这些宏可以在创建监控项、触发器等原型时使用。<br>
返回值：*JSON object*。

参数:

-   **unique short description** - 一个唯一简短的描述来标识监控项（用于触发器等）。
-   **dsn** - 数据源名称（如在 `odbc.ini` 文件中指定的）。
-   **connection string** - 连接字符串（可能包含特定于驱动程序的参数）。

注释:

-   尽管 `dsn` 和 `connection string` 是可选参数，但至少需要其中一个；如果两个都被定义了，`dsn` 将被忽略。

[comment]: # ({/f6dfe740-c8148c95})

[comment]: # ({87547b91-718edfdc})
#### 错误消息

ODBC 错误消息按字段组织，以提供详细信息。
例如，一条错误消息可能如下所示：

    无法执行 ODBC 查询：[SQL_ERROR]:[42601][7][ERROR: syntax error error at or near ";"; Error while executing the query]

-   "`无法执行 ODBC 查询`" - Zabbix 消息
-   "`[SQL_ERROR]`" - ODBC 返回代码
-   "`[42601]`" - SQLState
-   "`[7]`" - 本地错误代码
-   "`[ERROR: syntax error at or near ";"; Error while executing the query]`" - 本地错误消息

请注意，错误消息长度限制为 2048 字节，因此消息可能会被截断。
如果存在多条 ODBC 诊断记录，Zabbix 会尝试将它们连接起来（使用 `|` 分隔），直到达到长度限制为止。

[comment]: # ({/87547b91-718edfdc})