diff options
Diffstat (limited to 'plugin/handler_socket/docs-ja')
| -rw-r--r-- | plugin/handler_socket/docs-ja/about-handlersocket.ja.txt | 51 | ||||
| -rw-r--r-- | plugin/handler_socket/docs-ja/installation.ja.txt | 88 | ||||
| -rw-r--r-- | plugin/handler_socket/docs-ja/perl-client.ja.txt | 126 | ||||
| -rw-r--r-- | plugin/handler_socket/docs-ja/protocol.ja.txt | 180 |
4 files changed, 445 insertions, 0 deletions
diff --git a/plugin/handler_socket/docs-ja/about-handlersocket.ja.txt b/plugin/handler_socket/docs-ja/about-handlersocket.ja.txt new file mode 100644 index 00000000..2a152e87 --- /dev/null +++ b/plugin/handler_socket/docs-ja/about-handlersocket.ja.txt @@ -0,0 +1,51 @@ + + +----------------------------------------------------------------- +ソースコードの利用にあたっての免責事項 + +本ソフトウェアの開発者および株式会社ディー・エヌ・エーは、本フト +ウェアの不稼動、稼動不良を含む法律上の瑕疵担保責任、その他保証責 +任を負わないものとします。また、本ソフトウエアの開発者および株式 +会社ディー・エヌ・エーは、本ソフトウェアの商品性、またはお客様の +特定の目的に対する適合性について、いかなる保証も負わないものとし +ます。 + +----------------------------------------------------------------- +handlersocket pluginについて + +mysqlサーバに常駐し、innodb等のストレージエンジンへの直接のアクセ +スを提供するプラグインです。handlersocketプラグインは自前のリス +ナーを持ち、専用のクライアントライブラリ(libhsclient)を使ってそれ +にアクセスします。 + +mysqlの標準クライアントライブラリ(libmysql)を使ったアクセスと比べ +て、以下のような利点があります。 +・接続あたりに消費するリソースが少ないため、同時接続数が事実上無 + 制限。したがって接続数を気にせず持続接続を使えます。 +・高速(単純な参照クエリで3倍〜10倍程度)。 +・通信プロトコルがコンパクト。libmysqlを使うとデータ転送時にレ + コード名などが付随するために通信内容が冗長ですが、libhsclientで + はデータのみが転送されるため、帯域消費が少なくなります。場合に + よっては10倍以上libmysqlのほうが冗長になります。 + +現在のバージョンでは以下のような処理をサポートしています。 +・指定された索引について、指定された値と完全一致するようなレコー + ドを取得。(SELECT ??? FROM tbl WHERE k1 = v1 AND k2 = v2...)。 + 索引を使わない検索はサポートしていません。 +・指定された索引について、指定された値の位置の前後のレコードを取 + 得。(SELECT ??? FROM tbl WHERE k1 >= v1 LIMIT 100) +・前述のような手段で取得したレコードに対するUPDATEとDELETE +・レコードのINSERT + +以下のような言語をサポートします。 +・C++。libhsclientをリンクします。 +・Perl。Net::HandlerSocketをuseします。 + +現在のバージョンではGNU/Linuxでのみ動作します。 + +----------------------------------------------------------------- +既知の問題 + +・killでhandlersocketスレッドを殺すと、スレッド数が減ったまま回復 + しません。 + diff --git a/plugin/handler_socket/docs-ja/installation.ja.txt b/plugin/handler_socket/docs-ja/installation.ja.txt new file mode 100644 index 00000000..0e8f3513 --- /dev/null +++ b/plugin/handler_socket/docs-ja/installation.ja.txt @@ -0,0 +1,88 @@ + +----------------------------------------------------------------- +HandlerSocketプラグインのビルド方法(RPMを使わない方法) + +以下のようにしてconfigureを実行します。 + + $ ./autogen.sh + $ ./configure --with-mysql-source=/work/mysql-5.1.50 --with-mysql-bindir=/work/mysql-5.1.50-linux-x86_64-glibc23/bin --with-mysql-plugindir=/work/mysql-5.1.50-linux-x86_64-glibc23/lib/plugin + +ここで--with-mysql-sourceにはMySQLのソースコードのトップディレク +トリを指定します(そこにVERSIONファイルかconfigure.inファイルがなく +てはなりません)。--with-mysql-bindirにはインストール済みのMySQL +のmysql_configコマンドが有るディレクトリを指定します。 +その後以下のようにビルド・インストールします。 + + $ make + $ sudo make install + +----------------------------------------------------------------- +クライアントライブラリのビルド方法(RPMを使わない方法) + +クライアントライブラリをビルドする際には、MySQLのソースコードは +必要ありません。またMySQLがインストールされている必要もありません。 + + $ ./autogen.sh + $ ./configure --disable-handlersocket-server + $ make + $ sudo make install + $ cd perl-Net-HandlerSocket + $ perl Makefile.PL + $ make + $ sudo make install + +----------------------------------------------------------------- +ビルド方法(RPM) + +以下のように実行すれば、rpmパッケージがビルド＆インストールされま +す。 + +(MySQLサーバ側、HandlerSocketプラグインをインストールする) + $ ./autogen.sh + $ ./configure --with-mysql-source=/work/mysql-5.1.50 --with-mysql-bindir=/work/mysql-5.1.50-linux-x86_64-glibc23/bin --with-mysql-plugindir=/work/mysql-5.1.50-linux-x86_64-glibc23/lib/plugin + $ make rpm_cli + $ sudo rpm -U dist/RPMS/*/libhsclient*.rpm + $ make rpm_c + $ sudo rpm -U dist/RPMS/*/handlersocket*.rpm + +(クライアント側、クライアントライブラリをインストールする) + $ ./autogen.sh + $ ./configure --disable-handlersocket-server + $ make rpm_cli + $ sudo rpm -U dist/RPMS/*/libhsclient*.rpm + $ make rpm_perl + $ sudo rpm -U dist/RPMS/*/perl-Net-HandlerSocket*.rpm + +----------------------------------------------------------------- +起動 + +mysqlを起動した状態で、mysqlの設定ファイル(my.cnf等)に以下の内容を +追加します。 + + [mysqld] + handlersocket_port = 9998 + # handlersocketが接続を受け付けるポート(参照系リクエスト用) + handlersocket_port_wr = 9999 + # handlersocketが接続を受け付けるポート(更新系リクエスト用) + handlersocket_address = + # handlersocketがバインドするアドレス(空のままでOK) + handlersocket_verbose = 0 + # デバッグ用 + handlersocket_timeout = 300 + # 通信タイムアウト(秒) + handlersocket_threads = 16 + # handlersocketのワーカースレッド数 + thread_concurrency = 128 + # handlersocketが幾つかのスレッドを占有するため、大きめの + # 値を指定してください + open_files_limit = 65535 + # ソケットを大量に開けるようにするため、大きめの値を指定し + # てください + +以下のクエリを実行します。 + + mysql> install plugin handlersocket soname 'handlersocket.so'; + Query OK, 0 rows affected (0.06 sec) + +以上でhandlersocketへクライアントからアクセスできるようになります。 + diff --git a/plugin/handler_socket/docs-ja/perl-client.ja.txt b/plugin/handler_socket/docs-ja/perl-client.ja.txt new file mode 100644 index 00000000..90b7e4d6 --- /dev/null +++ b/plugin/handler_socket/docs-ja/perl-client.ja.txt @@ -0,0 +1,126 @@ + +----------------------------------------------------------------- +handlersocketプラグインへの接続を開くには、Net::HandlerSocketオブ +ジェクトを作成します。 + + use Net::HandlerSocket; + my $args = { host => 'localhost', port => 9998 }; + my $hs = new Net::HandlerSocket($args); + +----------------------------------------------------------------- +検索などの命令を実行する前に、処理対象となる索引を開く必要があり +ます。 + + my $err = $hs->open_index(3, 'database1', 'table1', 'PRIMARY', + 'f1,f2'); + die $hs->get_error() if $res->[0] != 0; + +最初の引数は開く索引に付ける番号です。付けた番号は同一の +Net::HandlerSocketオブジェクトについてのみ有効です。第4引数は開く +索引の名前で、「PRIMARY」が指定され場合はプライマリキーが開かれま +す。第5引数は「,」で区切られた列名のリストです。 + +----------------------------------------------------------------- +テーブルから索引を使って行を取得するには、execute_singleメソッド +を呼びます。 + + my $res = $hs->execute_single(3, '=', [ 'foo' ], 1, 0); + die $hs->get_error() if $res->[0] != 0; + shift(@$res); + +最初の引数は索引の番号で、同じNet::HandlerSocketオブジェクトへ +open_indexで付けたものでなければなりません。第2引数には操作を指定 +します。現在のバージョンでは、「=」、「>=」、「<=」、「>」、「<」 +の操作が利用可能です。第3引数は配列への参照で、これは探すべき行の +キー値を指定します。配列の長さは索引のキーの個数と同じか少ない数 +でなければなりません。第4引数と第5引数はそれぞれ、取得する最大行 +数、取得前に読み飛ばす行数を指定します。取得される列は対応する +open_index呼び出しの第5引数で指定されたものになります。 + +execute_singleメソッドは常に配列への参照を返します。最初の要素は +エラーコードで、これが0ならば成功を表します。残りの要素は列の値で +す。もし取得されたデータが複数行の場合は、それが一つの配列へ連結 +された形で格納されています。例えば、5行3列のデータの場合、次のよ +うなコードによってその内容を取得できます。 + + die $hs->get_error() if $res->[0] != 0; + shift(@$res); + for (my $row = 0; $row < 5; ++$row) { + for (my $col = 0; $col < 3; ++$col) { + my $value = $res->[$row * 5 + $col]; + # ... + } + } + +----------------------------------------------------------------- +行を更新または削除するには、更に多くの引数を指定して +execute_singleメソッドを呼び出します。書き込み処理をするには、 +対象のNet::HandlerSocketオブジェクトは更新用handlersocketワーカ(既 +定ではポート9999)へ接続されたものでなくてはなりません。 +(安全のため、ポート9998は参照処理だけを受け付け、ポート9999は更新 +処理も受け付けるようになっています。ポート9999は参照処理も受け付 +けますが、レコードロック等の影響で遅くなります。ポート番号は +mysqldの「handlersocket_port」と「handlersocket_port_wr」の設定項 +目で変更できます。) + + my $args = { host => 'localhost', port => 9999 }; + my $hs = new Net::HandlerSocket($args); + + my $res = $hs->execute_single(3, '=', [ 'bar' ], 1, 0, 'U', + [ 'fubar', 'hoge' ]); + die $hs->get_error() if $res->[0] != 0; + my $num_updated_rows = $res->[1]; + + my $res = $hs->execute_single(3, '=', [ 'baz' ], 1, 0, 'D'); + die $hs->get_error() if $res->[0] != 0; + my $num_deleted_rows = $res->[1]; + +execute_singleの第6引数は変更処理の種類を指定します。現在のバー +ジョンでは「U」と「D」が利用可能です。「U」については、第7引数で +新しい値を指定します。更新される列は、対応するopen_index呼び出し +の第5引数で指定されたものになります。「D」については第7引数は省 +略できます。 + +----------------------------------------------------------------- +execute_singleメソッドは列の挿入にも使用できます。 + + my $res = $hs->execute_single(3, '+', [ 'foo', 'bar', 'baz' ]); + die $hs->get_error() if $res->[0] != 0; + +第3引数は、対応するopen_index呼び出しの第5引数の列リストと同じだ +けの長さの配列への参照でなければなりません。open_index呼び出しの +第5引数に指定されていない列については、その列の既定値がセットされ +ます。 + +----------------------------------------------------------------- +execute_multiメソッドを使えば、複数のリクエストを一つの呼び出しで +実行することができます。これはリクエストを個別に実行するより高速 +です。 + + my $rarr = $hs->execute_multi([ + [ 0, '>=', [ 'foo' ], 5, 0 ], + [ 2, '=', [ 'bar' ], 1, 0 ], + [ 4, '<', [ 'baz' ], 10, 5 ], + ]); + for my $res (@$rarr) { + die $hs->get_error() if $res->[0] != 0; + shift(@$res); + # ... + } + +----------------------------------------------------------------- +もしhandlersocketが接続を認証するように設定されている +(handlersocket_plain_secret又はhandlersocket_plain_secret_wrがセッ +トされている)ならば、クライアントは他のメソッド呼び出しの前にauth +メソッドを呼び出す必要があります。 + + my $res = $hs->auth('password'); + die $hs->get_error() if $res->[0] != 0; + +----------------------------------------------------------------- +エラーが起こると返値の配列参照の最初の要素が0以外になります。負の +数の場合はI/Oエラーが起こったことを示し、その場合はその +Net::HandlerSocketオブジェクトは破棄するべきです。正の値の場合は +接続は維持されているため、そのオブジェクトはそれ以後も再利用でき +ます。 + diff --git a/plugin/handler_socket/docs-ja/protocol.ja.txt b/plugin/handler_socket/docs-ja/protocol.ja.txt new file mode 100644 index 00000000..46cc9932 --- /dev/null +++ b/plugin/handler_socket/docs-ja/protocol.ja.txt @@ -0,0 +1,180 @@ + +---------------------------------------------------------------------------- +handlersocketの通信プロトコル + +---------------------------------------------------------------------------- +基本的な構文 + +・HandlerSocketのプロトコルは行ベース。各行は改行文字(0x0a)で終わる。 +・各行は複数のトークンからなり、トークン間はTAB文字(0x09)で区切られる。 +・トークンはNULLトークンか、文字列トークンのいずれか。 +・NULLトークンは単一のNUL文字(0x00)であらわされる。 +・文字列トークンは、0バイト以上の文字列であらわされる。ただし0x10未満の文字 + については0x01を前置し、0x40を加えたコードであらわされる。それ以外の文字は + その文字自身のコードであらわされる。 + +---------------------------------------------------------------------------- +リクエストとレスポンス + +・HandlerSocketのプロトコルは単純なリクエスト・レスポンスプロトコルになって + いる。接続が確立した後は、まずクライアントがリクエストを送る。 +・サーバは、クライアントが送ったリクエストと丁度同じ数の行(レスポンス)を返 + す。 +・リクエストはパイプライン化してよい。つまりクライアントは前に送ったリクエス + トに対する返事(レスポンス)を待たずに次のリクエストを送ってもよい。 + +---------------------------------------------------------------------------- +インデックスを開く + +open_index命令は次のような構文を持つ。 + + P <indexid> <dbname> <tablename> <indexname> <columns> [<fcolumns>] + +- <indexid>は数字で、同一接続上で後に実行する命令の、対象索引を指定するため + に使われる。 +- <dbname>, <tablename>, <indexname>は文字列で、それぞれDB名、テーブル名、 + 索引の名前を指定する。<indexname>として「PRIMARY」を指定するとプライマリ + キーが開かれる。 +- <columns>はカンマ区切りの列名のリスト。 +- <fcolumns>はカンマ区切りの列名のリスト。これは省略することができる。 + +このopen_index命令が実行されると、HandlerSocketプラグインは指定されたDB、 +テーブル、索引を開く。開かれた索引は接続が閉じられるまで開かれたままになる。 +開かれた索引は<indexid>の数字で識別される。もし既に<indexid>に指定された番号 +の索引が既に開かれている場合は古いほうが閉じられる。この<indexid>はなるべく +小さな数字を使ったほうが効率が良い。 + +---------------------------------------------------------------------------- +データ取得 + +find命令は次のような構文を持つ。 + + <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...] + +LIMは次のようなパラメータの並び + + <limit> <offset> + +INは次のようなパラメータの並び + + @ <icol> <ivlen> <iv1> ... <ivn> + +FILTERは次のようなパラメータの並び + + <ftyp> <fop> <fcol> <fval> + +- <indexid>は数字で、これは同じ接続上で過去に実行したopen_index命令に指定さ + れた数字でなければならない。 +- <op>は比較演算子で、現在のバージョンでは '=', '>', '>=', '<', '<=' をサ + ポートしている。 +- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。この値は対応するopen_index + 命令の<indexname>パラメータで指定された索引のキー列の数と同じか小さいもの + でなければならない。 +- <v1> ... <vn>は取得するべきキーの値を指定するパラメータ。 +- LIMは省略できる。<limit>と<offset>は数字で、これはSQLのLIMITと同じように + はたらく。省略した場合は1と0を指定した場合と同じ動作をする。FILTERによっ + て読み飛ばされたレコードは<limit>と<offset>にカウントされない。 +- INは省略できる。指定されると、これはSQLの WHERE ... IN のように動作する。 + <icol>は対応するopen_index命令の<indexname>パラメータで指定された索引の + キー列の数より小さいものでなければならない。INが指定されたときは、find命 + 令の<v1> ... <vn>のうち<icol>番目の値は無視される。 +- FILTERは省略できる。これは行取得の際のフィルタを指定する。<ftyp>は + 'F'(filter)か'W'(while)のいずれかでなければならない。<fop>は比較演算子。 + <fcol>は数字で、これは対応するopen_index命令の<fcolumns>で指定された列の + 数より小さいものでなければならない。複数のフィルタを指定することもでき、 + その場合は各フィルタのANDと解釈される。'F'と'W'の違いは、条件にあてはま + らない行があったときに'F'は単にそれをスキップするが、'W'はその時点でルー + プを抜けるという点。 + +---------------------------------------------------------------------------- +更新と削除 + +find_modify命令は次のような構文を持つ。 + + <indexid> <op> <vlen> <v1> ... <vn> [LIM] [IN] [FILTER ...] MOD + +MODは次のようなパラメータの並び + + <mop> <m1> ... <mk> + +- <mop>は'U', '+', '-', 'D', 'U?', '+?', '-?', 'D?'のいずれか。'?'が付いた + ものは付いていないものとほぼ同じ動作をするが、付いていないものがレスポン + スとして更新された行の数を返すのに対し、付いているものは更新される前の行 + の内容を返す点のみが異なる。'U'は更新、'D'は削除、'+'はインクリメント、 + '-'はデクリメントを実行する。 +- <m1> ... <mk>はセットされる各列の値。<m1> ... <mk>の長さは対応する + open_index命令の<columns>の長さと等しいか小さくなければならない。<mop>が + 'D'のときはこれらのパラメータは無視される。<mop>が'+'か'-'のときは、これら + の値は数値でなければならない。<mop>が'-'で、それが負数から正数、または正数 + から負数へ列の値を変更するようなものであった場合は、値は変更されない。 + +---------------------------------------------------------------------------- +行の挿入 + +insert命令は次のような構文を持つ。 + + <indexid> + <vlen> <v1> ... <vn> + +- <vlen>は後に続くパラメータ<v1> ... <vn>の長さ。これは対応するopen_indexの + <columns>の長さに等しいか小さくなければならない。 +- <v1> ... <vn>はセットされる各列の値。指定されないかった列についてはその列 + のデフォルト値がセットされる。 + +---------------------------------------------------------------------------- +認証 + +auth命令は次のような構文を持つ。 + + A <atyp> <akey> + +- <atyp>は現在のバージョンでは'1'のみが有効。 +- 指定された<akey>が、サーバの設定の'handlersocket_plain_secret'や + 'handlersocket_plain_secret_wr'に指定された文字列と一致した場合にのみ認証 + は成功する。 +- HandlerSocketの認証が有効になっているときは、この'auth'が成功しない限りそ + れ以外の命令は全て失敗する。 + +---------------------------------------------------------------------------- +open_indexに対するレスポンス + +open_index命令が成功したとき、レスポンスは次の構文を持つ。 + + 0 1 + +---------------------------------------------------------------------------- +findに対するレスポンス + +find命令が成功したとき、レスポンスは次の構文を持つ。 + + 0 <numcolumns> <r1> ... <rn> + +- <numcolumns>はfind命令の対応するopen_index命令に指定した<columns>の長さに + 一致する。 +- <r1> ... <rn>は結果セット。もしN行がfind命令で見つかったなら、<r1> ... + <rn>の長さは ( <numcolumns> * N )になる。 + +---------------------------------------------------------------------------- +find_modifyに対するレスポンス + +find_modify命令が成功したとき、レスポンスは次の構文を持つ。 + + 0 1 <nummod> + +- <nummod>は変更された行の数。 +- 例外として、<mop>が'?'の付いたものであった場合には、find命令に対するレスポ + ンスと同じ構文のレスポンスを返す。 + +---------------------------------------------------------------------------- +insertに対するレスポンス + +insert命令が成功したとき、レスポンスは次の構文を持つ。 + + 0 1 + +---------------------------------------------------------------------------- +authに対するレスポンス + +auth命令が成功したとき、レスポンスは次の構文を持つ。 + + 0 1 + |