HandlerSocket gives you direct access to InnoDB and SPIDER. It is included in MariaDB as a ready-to use plugin.

HandlerSocket is a NoSQL plugin for MariaDB. It works as a daemon inside the mariadbd process, accepting TCP connections, and executing requests from clients. HandlerSocket does not support SQL queries. Instead, it supports simple CRUD operations on tables.

HandlerSocket can be much faster than mysqld/libmysql in some cases because it has lower CPU, disk, and network overhead:

1. To lower CPU usage it does not parse SQL.

2. Next, it batch-processes requests where possible, which further reduces CPU usage and lowers disk usage.

3. Lastly, the client/server protocol is very compact compared to mysql/libmysql, which reduces network usage.

In order to make use of the HandlerSocket plugin in your applications, you will need to use the appropriate client library. The following client libraries are available:

• C++

  • libhsclient (included with the HandlerSocket plugin source)

• Perl

  • perl-Net-HandlerSocket (included with the HandlerSocket plugin source)

• PHP

  • Net_HandlerSocket

  • HSPHP

  • php-ext-handlersocketi

• Java

  • hs4j

  • handlersocketforjava

• Python

  • python-handler-socket

  • pyhandlersocket

• Ruby

  • ruby-handlersocket

  • handlersocket

• JavaScript

  • node-handlersocket

• Scala

  • hs2client

• Haskell

  • HandlerSocket-Haskell-Client

_{This page is licensed: CC BY-SA / Gnu FDL}

The HandlerSocket plugin has the following options.

See also the Full list of MariaDB options, system and status variables.

Add the options to the [mysqld] section of your my.cnf file.

handlersocket_accept_balance

• Description: When set to a value other than zero ('0'), handlersocket will try to balance accepted connections among threads. Default is 0 but if you use persistent connections (for example if you use client-side connection pooling) then a non-zero value is recommended.

• Commandline: --handlersocket-accept-balance="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 0 to 10000

• Default Value: 0

handlersocket_address

• Description: Specify the IP address to bind to.

• Commandline: --handlersocket-address="value"

• Scope: Global

• Dynamic: No

• Type: IP Address

• Default Value: Empty, previously 0.0.0.0

handlersocket_backlog

• Description: Specify the listen backlog length.

• Commandline: --handlersocket-backlog="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 5 to 1000000

• Default Value: 32768

handlersocket_epoll

• Description: Specify whether to use epoll for I/O multiplexing.

• Commandline: --handlersocket-epoll="value"

• Scope: Global

• Dynamic: No

• Type: number

• Valid values:

  • Min: 0

  • Max: 1

• Default Value: 1

handlersocket_plain_secret

• Description: When set, enables plain-text authentication for the listener for read requests, with the value of the option specifying the secret authentication key.

• Commandline: --handlersocket-plain-secret="value"

• Dynamic: No

• Type: string

• Default Value: Empty

handlersocket_plain_secret_wr

• Description: When set, enables plain-text authentication for the listener for write requests, with the value of the option specifying the secret authentication key.

• Commandline: --handlersocket-plain-secret-wr="value"

• Dynamic: No

• Type: string

• Default Value: Empty

handlersocket_port

• Description: Specify the port to bind to for reads. An empty value disables the listener.

• Commandline: --handlersocket-port="value"

• Scope: Global

• Dynamic: No

• Type: number

• Default Value: Empty, previously 9998

handlersocket_port_wr

• Description: Specify the port to bind to for writes. An empty value disables the listener.

• Commandline: --handlersocket-port-wr="value"

• Scope: Global

• Dynamic: No

• Type: number

• Default Value: Empty, previously 9999

handlersocket_rcvbuf

• Description: Specify the maximum socket receive buffer (in bytes). If '0' then the system default is used.

• Commandline: --handlersocket-rcvbuf="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 0 to 1677216

• Default Value: 0

handlersocket_readsize

• Description: Specify the minimum length of the request buffer. Larger values consume available memory but can make handlersocket faster for large requests.

• Commandline: --handlersocket-readsize="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 0 to 1677216

• Default Value: 0 (possibly 4096)

handlersocket_sndbuf

• Description: Specify the maximum socket send buffer (in bytes). If '0' then the system default is used.

• Commandline: --handlersocket-sndbuf="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 0 to 1677216

• Default Value: 0

handlersocket_threads

• Description: Specify the number of worker threads for reads. Recommended value = ((

CPU cores) * 2).

• Commandline: --handlersocket-threads="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 1 to 3000

• Default Value: 16

handlersocket_threads_wr

• Description: Specify the number of worker threads for writes. Recommended value = 1.

• Commandline: --handlersocket-threads-wr="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 1 to 3000

• Default Value: 1

handlersocket_timeout

• Description: Specify the socket timeout in seconds.

• Commandline: --handlersocket-timeout="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 30 to 3600

• Default Value: 300

handlersocket_verbose

• Description: Specify the logging verbosity.

• Commandline: --handlersocket-verbose="value"

• Scope: Global

• Dynamic: No

• Type: number

• Valid values:

  • Min: 0

  • Max: 10000

• Default Value: 10

handlersocket_wrlock_timeout

• Description: The write lock timeout in seconds. When acting on write requests, handlersocket locks an advisory lock named 'handlersocket_wr' and this option sets the timeout for it.

• Commandline: --handlersocket-wrlock-timeout="value"

• Scope: Global

• Dynamic: No

• Type: number

• Range: 0 to `3600```

_{This page is licensed: CC BY-SA / Gnu FDL}

Some resources and documentation about HandlerSocket.

• The home of HandlerSocket is here.

• The story of handlersocket can be found here.

• Comparison of HANDLER and HandlerSocket can be found here.

• HandlerSocket plugin for MySQL presentation by Akira Higuchi of DeNA - June 29 2010 - DeNA Technology Seminar

• HandlerSocket plugin for MySQL presentation by Akira Higuchi of DeNA - June 29 2011 - in Japanese

_{This page is licensed: CC BY-SA / Gnu FDL}

After MariaDB is installed, use the INSTALL PLUGIN command (as the root user) to install the HandlerSocket plugin. This command only needs to be run once, like so:

INSTALL PLUGIN handlersocket SONAME 'handlersocket.so';

After installing the plugin, SHOW PROCESSLIST you first need to configure some settings. All HandlerSocket configuration options are placed in the [mysqld] section of your my.cnf file.

At least the handlersocket_address, handlersocket_port and handlersocket_port_wr options need to be set. For example:

handlersocket_address="127.0.0.1"
handlersocket_port="9998"
handlersocket_port_wr="9999"

After updating the configuration options, restart MariaDB.

On the client side, to make use of the plugin you will need to install the appropriate client library (i.e. libhsclient for C++ applications and perl-Net-HandlerSocket for perl applications).

_{This page is licensed: CC BY-SA / Gnu FDL}

MariaDB 5.5

In MariaDB 5.5, which is built using cmake, Makefile.PL is not generated automatically. If you want to run the perl tests, you will need to create it manually from Makefile.PL.in. It is fairly easy to do by replacing LIB and INC values with the correct ones. Also, libhsclient.so is not built by default; libhsclient.a can be found in plugin/handler_socket folder.

MariaDB 5.3

If you want to test or use handlersocket with a source installation of MariaDB 5.3, here is one way to do this:

1. Compile with one of the build scripts that has the -max option, like BUILD/compile-pentium64-max or BUILD/compile-pentium64-debug-max

2. Start mysqld with the test framework

cd mysql-test
LD_LIBRARY_PATH=../plugin/handler_socket/libhsclient/.libs \
MTR_VERSION=1 perl mysql-test-run.pl --start-and-exit 1st \
--mysqld=--plugin-dir=../plugin/handler_socket/handlersocket/.libs \
--mysqld=--loose-handlersocket_port=9998 \
--mysqld=--loose-handlersocket_port_wr=9999 \
--master_port=9306 --mysqld=--innodb

1. This will end with:

Servers started, exiting

1. Load handlersocket

client/mysql -uroot --protocol=tcp --port=9306 \
-e 'INSTALL PLUGIN handlersocket soname "handlersocket.so"'

1. Configure and compile the handlersocket perl module

cd plugin/handler_socket/perl-Net-HandlerSocket
perl Makefile.PL
make

1. If you would like to install the handlersocket perl module permanently, you should do:

make install

If you do this, you don't have to set PERL5LIB below.

1. Run the handlersocket test suite

cd plugin/handler_socket/regtest/test_01_lib
MYHOST=127.0.0.1 MYPORT=9306 LD_LIBRARY_PATH=../../libhsclient/.libs/ \
PERL5LIB=../common:../../perl-Net-HandlerSocket/lib:../../perl-Net-HandlerSocket/blib/arch/auto/Net/HandlerSocket/ ./run.sh

_{This page is licensed: CC BY-SA / Gnu FDL}