[comment]: # ({68c88a1c-68c88a1c})
# 14 ODBC 監視

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

[comment]: # ({3fce4dab-b5170fd3})
#### 概要

ODBC監視は、Zabbixフロントエンドの**Database monitor**アイテムタイプに対応しています。

ODBCは、データベース管理システム（DBMS）にアクセスするためのCプログラミング言語のミドルウェアAPIです。
ODBCのコンセプトはMicrosoftによって開発され、その後他のプラットフォームにも移植されました。

Zabbixは、ODBCでサポートされている任意のデータベースにクエリを実行できます。
そのために、Zabbixはデータベースに直接接続するのではなく、ODBCで設定されたODBCインターフェースとドライバーを使用します。
これにより、さまざまな目的（たとえば、特定のデータベースキューのチェック、使用統計の取得など）で複数のデータベースをより効率的に監視できます。

Zabbixは、最も一般的に使用されているオープンソースのODBC API実装の1つであるunixODBCをサポートしています。

::: noteimportant
ODBCチェックの[既知の問題](/manual/installation/known_issues#odbc_checks)も参照してください。
:::

[comment]: # ({/3fce4dab-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`パッケージは、unixODBCサポート付きでZabbixをコンパイルするために必要です。
ODBCサポートを有効にするには、Zabbixを以下の[設定オプション](/manual/installation/install/sources#configure-the-sources)でコンパイルする必要があります:
<br><br>

    --with-unixodbc[=ARG] # unixODBCパッケージに対してODBCドライバを使用します。

:::

[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ベースのシステムの場合:
dnf install mariadb-connector-odbc

# SUSEベースのシステムの場合:
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 ベースのシステムの場合:
dnf install postgresql-odbc

# SUSE ベースのシステムの場合:
zypper install psqlODBC
```

パッケージマネージャーを使用せずにデータベースドライバーをインストールするには、[PostgreSQL ドキュメント](https://www.postgresql.org/download/linux/)を参照してください。

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

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

unixODBCデータベースドライバーのインストールについては、[Oracleドキュメント](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データベースではServerの代わりにServerNameを使用する場合があります）。

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

|パラメータ|説明|
|--|--------|
|TEST_MYSQL|データソース名（DSN）。|
|Description|データソースの説明。|
|Driver|データベースドライバ名（`odbcinst.ini`で指定されたもの）。|
|Server|データベースサーバのIP/DNS。|
|User|接続用のデータベースユーザー。|
|Password|データベースユーザーのパスワード。|
|Port|データベース接続ポート。|
|Socket|データベース接続ソケット。|
|Database|データベース名。|

その他の設定パラメータのオプションについては、[MySQLドキュメント](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にObject ID（OID）を含めるかどうかを指定します。|
|FakeOidIndex|OIDに偽の一意インデックスを作成するかどうかを指定します。|
|RowVersioning|他のユーザーによってデータが変更された場合に、行を更新しようとしたときにアプリケーションがそれを検出できるようにするかどうかを指定します。このパラメータを有効にすると、`WHERE`句で全てのカラムを指定する必要がなくなるため、更新処理が高速化される場合があります。|
|ShowSystemTables|データベースドライバがシステムテーブルをSQLTablesで通常のテーブルとして扱うかどうかを指定します。システムテーブルへのアクセス性を高めるために有用です。|
|Fetch|ドライバが`SELECT`ステートメントを自動的にdeclare cursor/fetchで処理し、100行のキャッシュを維持するかどうかを指定します。|
|BoolsAsChar|Boolean型のマッピングを制御します。<br>「Yes」に設定すると、Boolは`SQL_CHAR`にマッピングされ、それ以外の場合は`SQL_BIT`にマッピングされます。|
|SSLmode|接続のSSLモードを指定します。|
|ConnSettings|接続時にバックエンドに送信される追加設定。|

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

[comment]: # ({2e87263e-93c68b7f})
##### ODBC接続のテスト

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/ja/manual/config/items/itemtypes/db_monitor.png){width="600"}

必須入力フィールドには赤いアスタリスクが付いています。

データベース監視アイテムの場合、以下を指定する必要があります。

|   |   |
|--|--------|
|*タイプ*|ここで「データベース監視」を選択します。|
|*キー*|サポートされているアイテムキーのいずれかを入力します:<br>[**db.odbc.select[]**](#db.odbc.select) - このアイテムはSQLクエリ結果の最初の行の最初の列の値を返します;<br>[**db.odbc.get[]**](#db.odbc.get) - このアイテムは複数の行/列をJSON形式で返します;<br>[**db.odbc.discovery[]**](#db.odbc.discovery) - このアイテムはローレベルディスカバリーデータを返します。|
|*ユーザー名*|データベースのユーザー名（255文字まで）を入力します。<br>このパラメータは、`odbc.ini`ファイルでデータベースのユーザー名が指定されている場合は省略可能です。<br>接続文字列が使用されていて、*ユーザー名*フィールドが空でない場合は、`UID=<user>`として接続文字列に追加されます。|
|*パスワード*|データベースのユーザーパスワード（255文字まで）を入力します。<br>このパラメータは、`odbc.ini`ファイルでパスワードが指定されている場合は省略可能です。<br>接続文字列が使用されていて、*パスワード*フィールドが空でない場合は、`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クエリ*|SQLクエリを入力します。<br>`db.odbc.select[]`の場合、クエリは1つの値のみを返す必要があることに注意してください。|
|*情報の型*|ここでクエリによって返される情報の型を選択します。<br>情報の型が正しく選択されていない場合、アイテムはサポート対象外になります。|

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

[comment]: # ({db5ed945-06f9d2eb})
**重要な注意事項**

-   サーバーまたはプロキシの設定で *odbc poller* プロセスが開始されていない場合、データベース監視アイテムはサポートされなくなります。
    ODBCポーラーを有効にするには、Zabbix [サーバー](/manual/appendix/config/zabbix_server)の設定ファイル、またはプロキシによって実行されるチェックの場合はZabbix [プロキシ](/manual/appendix/config/zabbix_proxy)の設定ファイルで `StartODBCPollers` パラメータを設定します。
-   [アイテム設定](/manual/config/items/item#configuration)フォームの *Timeout* パラメータ値は、ODBCログインタイムアウトおよびクエリ実行タイムアウトとして使用されます。
    インストールされているODBCドライバーがこれらのタイムアウト設定をサポートしていない場合、これらのタイムアウト設定が無視されることがあるので注意してください。
-   SQLコマンドは、`select`ステートメントを使用するクエリのように、結果セットを返す必要があります。
    クエリの構文は、それらを処理するRDBMSによって異なります。
    ストアドプロシージャへのリクエストの構文は、`call`キーワードで始める必要があります。

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

[comment]: # ({99bf7f73-0188aaa2})
#### アイテムキーの詳細

山括弧のないパラメータは必須です。山括弧 **<** **>** で囲まれたパラメータはオプションです。

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

[comment]: # ({1a75e5c0-13edfcd4})
##### db.odbc.select[<unique short description>,<dsn>,<connection string>] {#db.odbc.select}

<br>
SQLクエリ結果の最初の行の最初の列、つまり1つの値を返します。<br>
戻り値: SQLクエリに依存します。

パラメータ:

-   **unique short description** - アイテムを識別するための一意の短い説明 (トリガーなどで使用);
-   **dsn** - データソース名 (`odbc.ini`で指定されたもの);
-   **connection string** - 接続文字列 (ドライバー固有の引数を含めることができます)。

コメント:

-   `dsn`と`connection string`は省略可能なパラメータですが、少なくともどちらか一方は必須です。両方が定義されている場合は、`dsn`は無視されます。
-   クエリが複数の列を返す場合、最初の列のみが読み取られます。クエリが複数の行を返す場合、最初の行のみが読み取られます。

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

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

<br>
SQLクエリの結果をJSON配列に変換します。<br>
戻り値：*JSONオブジェクト*。

パラメータ:

-   **unique short description** - アイテムを識別するための一意の短い説明（トリガーなどで使用）;
-   **dsn** - データソース名（`odbc.ini`で指定）;
-   **connection string** - 接続文字列（ドライバ固有の引数を含む場合があります）。

コメント:

-   `dsn`と`connection string`はどちらも省略可能なパラメータですが、少なくともどちらか一方が必要です。両方が定義されている場合は、`dsn`は無視されます。
-   JSON形式で複数の行/列が返される場合があります。
    このアイテムは、1回のシステムコールですべてのデータを収集するマスターアイテムとして使用でき、依存アイテムでは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]: # ({/a6ace17e-ebf5d449})

[comment]: # ({f6dfe740-c8148c95})
##### db.odbc.discovery[<unique short description>,<dsn>,<connection string>] {#db.odbc.discovery}

<br>
SQLクエリの結果をJSON配列に変換し、[ローレベルディスカバリ](/manual/discovery/low_level_discovery/examples/sql_queries)で使用します。
クエリ結果のカラム名は、ディスカバリされたフィールド値とペアになったローレベルディスカバリマクロ名に変換されます。
これらのマクロは、アイテム、トリガーなどのプロトタイプ作成時に使用できます。<br>
戻り値: *JSONオブジェクト*。

パラメータ:

-   **unique short description** - アイテムを識別するための一意の短い説明（トリガーなどで使用）;
-   **dsn** - データソース名（`odbc.ini`で指定）;
-   **connection string** - 接続文字列（ドライバ固有の引数を含めることができます）。

コメント:

-   `dsn`と`connection string`はどちらも省略可能なパラメータですが、少なくともどちらか一方は必須です。両方が定義されている場合は、`dsn`は無視されます。

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

[comment]: # ({87547b91-718edfdc})
#### エラーメッセージ

ODBCエラーメッセージは、詳細な情報を提供するためにフィールドに構造化されています。
例えば、エラーメッセージは次のようになります。

    Cannot execute ODBC query: [SQL_ERROR]:[42601][7][ERROR: syntax error at or near ";"; Error while executing the query]

-   "`Cannot execute ODBC query`" - Zabbixメッセージ
-   "`[SQL_ERROR]`" - ODBCリターンコード
-   "`[42601]`" - SQLState
-   "`[7]`" - ネイティブエラーコード
-   "`[ERROR: syntax error at or near ";"; Error while executing the query]`" - ネイティブエラーメッセージ

エラーメッセージの長さは2048バイトに制限されているため、メッセージが切り捨てられる場合があることに注意してください。
ODBC診断レコードが複数ある場合、Zabbixは長さ制限の範囲内でそれらを（`|`で区切って）連結しようとします。

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