7.1.4. groonga-httpd¶
7.1.4.1. 概要¶
groonga-httpdはGroongaサーバーとHTTPプロトコルで通信するプログラムです。 機能的には、 groonga HTTPサーバー と同じです。 groonga HTTPサーバー はHTTPサーバーとしては最小限の機能しか持ちませんが、groonga-httpdは nginx を組み込むことでnginxが準拠しているHTTPの仕様と機能をすべて利用できます。
groonga-httpdにはHTML + JavaScriptで実装された管理ツールが標準で付属しています。ウェブブラウザでhttp://hostname:port/にアクセスすると、管理ツールを利用できます。
7.1.4.2. 書式¶
groonga-httpd [nginx options]
7.1.4.3. 使い方¶
7.1.4.3.1. 設定をする¶
まずは、データベースを指定するためにgroonga-httpdの設定ファイルを編集する必要があります。次のように/etc/groonga/httpd/groonga-httpd.confを編集して groonga_database
ディレクティブを有効にしてます。
# Match this to the file owner of groonga database files if groonga-httpd is
# run as root.
#user groonga;
...
http {
...
# Don't change the location; currently only /d/ is supported.
location /d/ {
groonga on; # <= This means to turn on groonga-httpd.
# Specify an actual database and enable this.
groonga_database /var/lib/groonga/db/db;
}
...
}
次に、groonga-httpdを実行してください。すぐにターミナルに制御が戻ってきます。これはgroonga-httpdはデフォルトでデーモンプロセスになるからです。
% groonga-httpd
7.1.4.3.2. クエリーを実行する¶
動作を確認するため、簡単なクエリー( status )をリクエストしてみます。
実行例:
% curl http://localhost:10041/d/status
[
[
0,
1337566253.89858,
0.000355720520019531
],
{
"uptime": 0,
"max_command_version": 2,
"n_queries": 0,
"cache_hit_rate": 0.0,
"version": "4.0.1",
"alloc_count": 161,
"command_version": 1,
"starttime": 1395806036,
"default_command_version": 1
}
]
7.1.4.3.3. Loading data by POST¶
The feature of groonga-httpd in contrast to groonga is supporting POST method.
You can load data by POST JSON data.
Here is an example curl command line that loads two users alice and bob to Users table:
% curl --data-binary '[{"_key": "alice"}, {"_key": "bob"}]' -H "Content-Type: application/json" "http://localhost:10041/d/load?table=Users"
If you loads users from JSON file, prepare JSON file like this:
[
{"_key": "alice"},
{"_key": "bob"}
]
Then specify JSON file in curl command line:
% curl -X POST 'http://localhost:10041/d/load?table=Users' -H 'Content-Type: application/json' -d @users.json
7.1.4.3.4. 管理ツールを使う¶
補足ですが、 http://localhost:10041/ にアクセスすると管理ツールを利用できます。
7.1.4.4. 設定ディレクティブ¶
このセクションでは重要なディレクティブのみ説明します。重要なディレクティブとはgroonga-http特有のディレクティブと性能に関するディレクティブです。
以下のディレクティブはgroonga-httpdの設定ファイル中で使用することができます。デフォルトでは、設定ファイルは/etc/groonga/httpd/groonga-httpd.confに置かれています。
7.1.4.4.1. groonga-httpd特有のディレクティブ¶
以下のディレクティブはnginxが提供しているものではなく、groonga-httpd関連の設定をするためにgroonga-httpdが提供しているディレクティブです。
7.1.4.4.1.1. groonga
¶
書式:
groonga on | off;
- Default
groonga off;
- Context
location
この location
ブロックでGroongaを使うかどうかを指定します。デフォルトは off
です。Groongaを使うためには on
を指定してください。
例:
location /d/ {
groonga on; # Enables groonga under /d/... path
}
location /d/ {
groonga off; # Disables groonga under /d/... path
}
7.1.4.4.1.2. groonga_database
¶
書式:
groonga_database /path/to/groonga/database;
- Default
groonga_database /usr/local/var/lib/groonga/db/db;
- Context
http
,server
,location
Groongaデータベースのパスを指定します。このディレクティブは必須です。
7.1.4.4.1.3. groonga_database_auto_create
¶
書式:
groonga_database_auto_create on | off;
- Default
groonga_database_auto_create on;
- Context
http
,server
,location
Groongaのデータベースを自動で作成するかどうかを指定します。もし、この値が on
で groonga_database に指定したGroongaのデータベースが存在しない場合は自動でGroongaのデータベースを作成します。Groongaのデータベースが存在している場合は何もしません。
もし、親ディレクトリが存在しな場合は再帰的に親ディレクトリも作成します。
デフォルト値は on
です。通常、この値を変更する必要はありません。
7.1.4.4.1.4. groonga_base_path
¶
書式:
groonga_base_path /d/;
- Default
location
の名前と同じ値。- Context
location
URIのベースパスを指定します。Groongaは command
を実行するために /d/command?parameter1=value1&...
というパスを使います。groonga-httpdでもこのパスの形式を使いますが、groonga-httpdは /other-prefix/command?parameter1=value1&...
というように /d/
ではなく別のプレフィックスを使った形式もサポートしています。この別の形式もサポートするために、groonga-httpdはリクエストURIの先頭からベースパスを削除し、先頭に /d/
を追加します。このパスの変換をすることにより、ユーザーはプレフィックスをカスタムできるようになりますが、Groongaは常に /d/command?parameter1=value1&...
という形式で処理できます。
通常、このディレクティブを使う必要はありません。このディレクティブはコマンド毎に設定をしたい場合に使います。
以下は shutdown コマンドに認証をかける設定例です。:
groonga_database /var/lib/groonga/db/db;
location /d/shutdown {
groonga on;
# groonga_base_path is needed.
# Because /d/shutdown is handled as the base path.
# Without this configuration, /d/shutdown/shutdown path is required
# to run shutdown command.
groonga_base_path /d/;
auth_basic "manager is required!";
auth_basic_user_file "/etc/managers.htpasswd";
}
location /d/ {
groonga on;
# groonga_base_path doesn't needed.
# Because location name is the base path.
}
7.1.4.4.1.5. groonga_log_path
¶
書式:
groonga_log_path path | off;
- Default
/var/log/groonga/httpd/groonga.log
- Context
http
,server
,location
Groongaのログ保存先を http
、server
もしくは location
ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga.log
です。ログを無効にするには off
を指定します。
例:
location /d/ {
groonga on;
# You can disable log for groonga.
groonga_log_path off;
}
7.1.4.4.1.6. groonga_log_level
¶
書式:
groonga_log_level none | emergency | alert | ciritical | error | warning | notice | info | debug | dump;
- Default
notice
- Context
http
,server
,location
Groongaのログレベルを http
、 server
もしくは location
ブロックで指定します。デフォルトは notice
です。 none
を指定することでログを無効にできます。
例:
location /d/ {
groonga on;
# You can customize log level for groonga.
groonga_log_level notice;
}
7.1.4.4.1.7. groonga_query_log_path
¶
書式:
groonga_query_log_path path | off;
- Default
/var/log/groonga/httpd/groonga-query.log
- Context
http
,server
,location
Groongaのクエリーログの保存先を http
、server
もしくは location
ブロックで指定します。デフォルトは /var/log/groonga/httpd/groonga-query.log
です。ログを無効にするには off
を指定します。
例:
location /d/ {
groonga on;
# You can disable query log for groonga.
groonga_query_log_path off;
}
クエリーログは以下のようなケースで有用です:
スロークエリーを見つける。
デバッグ。
groonga-query-log パッケージ でクエリーログを解析できます。このパッケージは有用なツールを提供しています。
例えば、クエリーログを解析するツールがあります。これを使えば、スロークエリーを見つけることができます。クエリーログ内のすべてのクエリーを再生するツールもあります。これを使えば、新しいGroongaをプロダクション環境にデプロイする前に網羅的にテストすることができます。
7.1.4.5. 利用可能なnginxモジュール¶
全てのHTTPの標準モジュールが利用可能です。PCRE(Perl Compatible Regular Expressions)がない場合はHttpRewriteModuleは無効になります。標準モジュールの一覧は、 http://wiki.nginx.org/Modules を参照してください。