groonga - An open-source fulltext search engine and column store.

4.2. How to use groonga with network

You can use groonga with network. When you run groonga by using the groonga original protocol or HTTP, groonga accepts connection for network.

4.2.1. Connect with groonga's original protocol

4.2.1.1. Run groonga daemon

Form:

groonga [-p PORT_NUMBER] -d DB_PATH_NAME

The DB_PATH_NAME is set the full-path of existing database. With this form, you can run groonga as a daemon and connect by with groonga original protocol on PORT_NUMBER. (The port number is 10041 when you don't specify PORT_NUMBER.)

Execution example:

% groonga -d /tmp/groonga-databases/introduction.db
12345
%

Groonga shows its process ID on daemon mode.

4.2.1.2. Connect to groonga server

Form:

groonga [-p PORT_NUMBER] -c [HOST_NAME_OR_IP_ADDRESS]

This command connects to groonga server running at specified HOST_NAME_OR_IP_ADDRESS.

When you don't specify HOST_NAME_OR_IP_ADDRESS, this command connects to groonga server running at localhost. When you don't specify PORT_NUMBER, 10041 is used.

Groonga runs in interactive mode after connect to groonga server successfully. Groonga reads command from standard input and evaluates it repeatedly.

Execution example:

% groonga -c
> status
[[0,1317212813.13814,0.000102148],{"alloc_count":184,"starttime":1317212806,"uptime":7,"version":"1.2.5-84-g5c190df","n_queries":14,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}]
> ctrl-d
%

4.2.1.3. Terminate groonga daemon

You can terminate groonga daemon with shutdown command.

Execution example:

% groonga -c
> shutdown
%

4.2.2. Connect with HTTP

You need to run groonga in HTTP protocol mode when you want to use groonga via HTTP.

Form:

groonga [-p PORT_NUMBER] -d --protocol http DB_PATH_NAME

--protocol option specifies a protocol of groonga server. http means that groonga accepts connections via HTTP.

4.2.2.1. Administration tool based on HTML

You can access administration tool based on HTML at http://[HOST_NAME_OR_IP_ADDRESS]:[PORT_NUMBER]/ after the above command is ran. Your browser must enables JavaScript.

4.2.2.2. Run command with HTTP

You can run command at /d/COMMAND_NAME when groonga is ran in HTTP protocol mode.

Command options are passed as HTTP's GET parameters. They are in ?OPTION=VALUE&OPTION=VALUE&... form.

Execution example:

http://[IPまたはホスト名]:[ポート番号]/d/status
実行される処理:
> status
[[0,1317212813.33982,0.000109691],{"alloc_count":184,"starttime":1317212806,"uptime":7,"version":"1.2.5-84-g5c190df","n_queries":14,"cache_hit_rate":0.0,"command_version":1,"default_command_version":1,"max_command_version":2}]

http://[IPまたはホスト名]:[ポート番号]/d/select?table=Site&query=title:@this
実行される処理:
> select --table Site --query title:@this
[[0,1317212813.54112,6.7993e-05],[[[1],[["_id","UInt32"],["_key","ShortText"],["title","ShortText"]],[1,"http://example.org/","This is test record 1!"]]]]

4.2.3. Security

Network service of groonga doesn't support authentication. Everyone can view and modify the database. We recommend that you restrict client accesses by IP address. You can use iptables or any similar tool for it.