4.2. Remote access#
You can use Groonga as a server which allows remote access. Groonga supports the original protocol (GQTP), the memcached binary protocol and HTTP.
4.2.1. Hypertext transfer protocol (HTTP)#
4.2.1.1. How to run an HTTP server#
Groonga supports the hypertext transfer protocol (HTTP). The following form shows how to run Groonga as an HTTP server daemon.
Form:
groonga [-p PORT_NUMBER] -d --protocol http DB_PATH
The –protocol option and its argument specify the protocol of the server. “http” specifies to use HTTP. If the -p option is not specified, Groonga uses the default port number 10041.
The following command runs an HTTP server that listens on the port number 80.
Execution example:
% sudo groonga -p 80 -d --protocol http /tmp/groonga-databases/introduction.db
%
Note
You must have root privileges if you listen on the port number 80 (well known port). There is no such a limitation about the port number 1024 or over.
4.2.1.2. How to send a command to an HTTP server#
You can send a command to an HTTP server by sending a GET request to /d/COMMAND_NAME. Command parameters can be passed as parameters of the GET request. The format is “?NAME_1=VALUE_1&NAME_2=VALUE_2&…”.
The following example shows how to send commands to an HTTP server.
Execution example:
http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/d/status
Executed command:
status
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# {
# "alloc_count": 29,
# "starttime": 1696558618,
# "start_time": 1696558618,
# "uptime": 0,
# "version": "2.9.1",
# "n_queries": 0,
# "cache_hit_rate": 0.0,
# "command_version": 1,
# "default_command_version": 1,
# "max_command_version": 3,
# "n_jobs": 0,
# "features": {
# "nfkc": true,
# "mecab": true,
# "message_pack": true,
# "mruby": true,
# "onigmo": true,
# "zlib": true,
# "lz4": true,
# "zstandard": true,
# "kqueue": false,
# "epoll": true,
# "poll": false,
# "rapidjson": false,
# "apache_arrow": true,
# "xxhash": true,
# "blosc": true,
# "bfloat16": true,
# "h3": true,
# "simdjson": true,
# "llama.cpp": true,
# "back_trace": true,
# "reference_count": false
# },
# "apache_arrow": {
# "version_major": 2,
# "version_minor": 9,
# "version_patch": 1,
# "version": "2.9.1"
# },
# "memory_map_size": 2929,
# "n_workers": 0,
# "default_n_workers": 0,
# "os": "Linux",
# "cpu": "x86_64"
# }
# ]
http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/d/select?table=Site&query=title:@this
Executed command:
select --table Site --query title:@this
# [
# [
# 0,
# 1337566253.89858,
# 0.000355720520019531
# ],
# [
# [
# [
# 1
# ],
# [
# [
# "_id",
# "UInt32"
# ],
# [
# "_key",
# "ShortText"
# ],
# [
# "country",
# "SiteCountry"
# ],
# [
# "domain",
# "SiteDomain"
# ],
# [
# "link",
# "Site"
# ],
# [
# "links",
# "Site"
# ],
# [
# "location",
# "WGS84GeoPoint"
# ],
# [
# "title",
# "ShortText"
# ]
# ],
# [
# 1,
# "http://example.org/",
# "japan",
# ".org",
# "http://example.net/",
# [
# "http://example.net/",
# "http://example.org/",
# "http://example.com/"
# ],
# "128452975x503157902",
# "This is test record 1!"
# ]
# ]
# ]
# ]
4.2.2. Administration tool (HTTP)#
An HTTP server of Groonga provides a browser based administration tool that makes database management easy. After starting an HTTP server, you can use the administration tool by accessing http://HOST_NAME_OR_IP_ADDRESS[:PORT_NUMBER]/. Note that JavaScript must be enabled for the tool to work properly.
4.2.3. Security issues#
Groonga servers don’t support user authentication. Everyone can view and modify databases hosted by Groonga servers. You are recommended to restrict IP addresses that can access Groonga servers. You can use iptables or similar for this purpose.