Tsubakuro KVSクライアント

TsurugiのTsubakuro（Java通信ライブラリー）のKvsClientのメモ。

概要

Tsurugiサーバーの内部はKVS（Key Value Store）でデータを管理している。
TsurugiのSQL実行エンジンは、SQL文を「KVSアクセスする処理」に変換して実行する。
Tsubakuroでは（SQLを介さずに）KVSアクセスすることが出来る。
（元々は、JavaからKVSアクセスする機能は予定に入っておらず、C++でKVSアクセスする処理を書けるようになる予定だった）

KVSアクセスではput/get/remove/scanなど、テーブル単位での読み書きの機能しか無い。
SQLより単純だが、その分速いはず。

TsubakuroでKVSアクセスするにはKvsClientクラスを使用する。
ただし、Tsurugi 1.0.0-BETA1ではまだ正式公開されておらず、限定的な機能しか使用できない。
（なお、Tsurugiサーバーのバージョン付けとTsubakuro（クライアント）のバージョンは一致していない）

KvsClientはtsubakuro-kvsにあるので、biuld.gradleのdependenciesに追加する必要がある。

biuld.gradle：

dependencies {
    def tsubakuroVersion = '1.0.1'
    implementation "com.tsurugidb.tsubakuro:tsubakuro-session:${tsubakuroVersion}"
    implementation "com.tsurugidb.tsubakuro:tsubakuro-connector:${tsubakuroVersion}"
    implementation "com.tsurugidb.tsubakuro:tsubakuro-kvs:${tsubakuroVersion}"
}

KvsClientを生成する例

KvsClientインスタンスはSessionをアタッチして生成する。

import com.tsurugidb.tsubakuro.kvs.KvsClient;

    try (var kvsClient = KvsClient.attach(session)) {
        〜
    }

KvsClientはクローズする必要があるが、クローズしてもアタッチされたSessionはクローズされない。

トランザクションを実行する例

import com.tsurugidb.tsubakuro.kvs.TransactionHandle;
import com.tsurugidb.tsubakuro.kvs.TransactionOption;

    try (var kvsClient = KvsClient.attach(session)) {

        // トランザクション開始
        TransactionOption option = TransactionOption.forShortTransaction().build();
        try (TransactionHandle transactionHandle = kvsClient.beginTransaction(option).await(3, TimeUnit.SECONDS)) {
            〜

            // コミット
            kvsClient.commit(transactionHandle).await(10, TimeUnit.SECONDS);
        }
    }

KvsClientのメソッド

getやremoveメソッドにおける「キー」は、基本的にプライマリキー。
ただしインデックスが作られているテーブルでは、インデックスも指定できるようになるらしい？

putの例

KvsClientのputメソッドは、テーブルに1行書き込む。

import com.tsurugidb.tsubakuro.kvs.PutResult;
import com.tsurugidb.tsubakuro.kvs.PutType;
import com.tsurugidb.tsubakuro.kvs.RecordBuffer;

    var record = new RecordBuffer();
    record.add("pk", 1);       // int
    record.add("value", 456L); // bigint
    PutResult result = kvsClient.put(transactionHandle, "test", record, PutType.OVERWRITE).await(3, TimeUnit.SECONDS);

    System.out.printf("put.size=%d%n", result.size());

RecordBufferでテーブルの1行分のデータを設定する。（全カラムのデータが必須）
それをテーブル名と共にputメソッドに渡す。

putメソッドの引数PutTypeの意味は以下の通り。

putでは、SQLのinsert文と異なり、プライマリキーの一意制約違反が発生することは無い。

putメソッドの実行結果として、PutResultが返る。

PutResultにはsizeメソッドがあり、実際に書き込んだ件数が返る。

getの例

KvsClientのgetメソッドは、キーを指定してテーブルから1行取得する。

import com.tsurugidb.tsubakuro.kvs.GetResult;
import com.tsurugidb.tsubakuro.kvs.Record;
import com.tsurugidb.tsubakuro.kvs.RecordBuffer;

    var key = new RecordBuffer();
    key.add("pk", 1);
    GetResult result = kvsClient.get(transactionHandle, "test", key).await(3, TimeUnit.SECONDS);

    if (result.isSingle()) {
        Record record = result.asRecord();
        int pk = record.getInt("pk");
        Long value = record.isNull("value") ? null : record.getLong("value");
        System.out.printf("%d, %d%n", pk, value);
    } else {
        System.out.println("get nothing");
    }

RecordBufferでテーブルのキーのデータを設定する。（複合キーの場合、それら全てのデータが必須）
それをテーブル名と共にgetメソッドに渡す。

getメソッドの実行結果として、GetResultが返る。

指定したキーのデータがあったかどうかはGetResultのisSingleメソッドで判別できる。
trueの場合、GetResultのasRecordメソッドで1レコード分のデータが取得できる。

removeの例

KvsClientのremoveメソッドは、キーを指定してテーブルから1行削除する。

import com.tsurugidb.tsubakuro.kvs.RecordBuffer;
import com.tsurugidb.tsubakuro.kvs.RemoveResult;
import com.tsurugidb.tsubakuro.kvs.RemoveType;

    var key = new RecordBuffer();
    key.add("pk", 1);
    RemoveResult result = kvsClient.remove(transactionHandle, "test", key, RemoveType.COUNTING).await(3, TimeUnit.SECONDS);

    System.out.printf("remove.size=%d%n", result.size());

RecordBufferでテーブルのキーのデータを設定する。（複合キーの場合、それら全てのデータが必須）
それをテーブル名と共にremoveメソッドに渡す。

removeメソッドの引数RemoveTypeの意味は以下の通り。

removeメソッドの実行結果として、RemoveResultが返る。

RemoveTypeがCOUNTINGの場合、RemoveResultのsizeメソッドで実際に削除した件数が分かる。（と言っても、キーを指定するので、削除件数は1か0のどちらかだろう）
RemoveTypeがINSTANTの場合は、RemoveResultのsizeメソッドは常に1を返す。