BLOB (GA version) Usage and Notes (ja)

[akirakw]

BLOB, CLOB 型の利用方法

Tsurugi 1.11.0 より、正式機能として BLOB, CLOB 型のカラムをサポートしました。
このドキュメントでは、BLOB, CLOB 型の利用方法と注意点について解説します。

Note

Tsurugi 1.10.0 およびそれ以前のバージョンでは、BLOB, CLOB 型は試験的機能 (Experimental Feature) として提供されていました。
試験的機能 における BLOB, CLOB 型の利用方法については、以下のドキュメントを参照してください。

• BLOB (Experimental Feature version) Usage and Notes (ja)

用語について

本書では BLOB, CLOB 型の両方を扱う用語について、単に「BLOB...」と表記することがあります。
たとえば、以下のような用語が該当します:

• BLOBデータ
• BLOB転送モード
• BLOB中継サービス
• BLOBのライフサイクル

これらの用語については、基本的には BLOB, CLOB 型の両方を扱う概念や機能として使用しています。
その他の用語についても、文中で特記しない限りは BLOB, CLOB 型の両方を扱うものとします。

BLOB, CLOB 型の特徴

BLOB, CLOB 型は、バイナリデータやサイズが大きな文字列データを格納するためのデータ型です。

Tsurugi はインメモリ型のデータベースであり、基本的には小さなデータを大量に処理することに最適化してデザインしています。
対して、BLOB, CLOB 型のデータ（以下「BLOBデータ」）は基本的に大きなデータであるため、Tsurugi はそれらのデータをメモリ上には保持せず、ファイルシステム上に保存することでメモリの使用量を削減しています。

上記のような関係で、BLOB, CLOB 型はほかのデータ型と比べて利用時の特性が異なる場合があります。
以下に例を挙げます:

• 読み出し時にファイルシステムへのアクセスが発生する可能性がある
• クエリー発行時に、結果セットに BLOB, CLOB 型の実データは直接含まれず、実データの取得時に別途サーバと通信するためほかのデータ型に比べて問い合わせ性能が低下する場合がある
• 等価比較 (=, <>, IN, GROUP BY, DISTINCT など) や順序比較 (<, >, ORDER BY, インデックスキーとしての利用など) ができない

なお、Tsurugi 上に記録した BLOBデータのファイルは、BLOBデータを含む行が参照されなくなった後に自動的に削除されます。
Tsurugi ではマルチバージョン並列性制御 (MVCC) 方式を採用しているため、 DELETE 文等で行を削除しても即座にそのファイルが削除されるわけではありません。
詳しくは BLOBのライフサイクル を参照してください。

BLOB, CLOB 型のデータ交換方法

BLOB, CLOB 型は上記の特徴から、クライアント・サーバ間でデータを交換する方法もほかのデータ型とは異なります。

Tsurugiでは、BLOBデータの交換方法として以下2つの転送モード(以下、BLOB転送モード) を提供しています:

• リレーモード (relay mode) : Tsurugiが提供するgRPCサービス「BLOB中継サービス」を介してBLOBデータを交換する方式。
• 特権モード (privileged mode) : ローカルファイルシステムを介してBLOBデータを交換する方式。

Tsurugiが提供する各種クライアントは、Tsurugiに対するセッションの接続時にBLOB転送モードを指定することができます。

以下に、それぞれのBLOB転送モードの特徴を説明します。

リレーモード (relay mode)

リレーモードは、Tsurugiに組み込まれているgRPCサービス「BLOB中継サービス」を介してBLOBデータを交換する方式です。
リレーモードは、Tsurugiが提供する各種クライアントのデフォルトのBLOB転送モードとなっています。

BLOB中継サービスは、Tsurugiがファイルシステムとして保存して管理するBLOBデータをgRPCプロトコル上でクライアントに受け渡しするgRPCサービスです。
Tsurugiが提供する各種クライアントライブラリは、BLOB中継サービスと通信してBLOBデータをやりとりするAPI群を提供しており、アプリケーションはこれらのクライアントAPIを利用してBLOB, CLOB型を利用することができます。

リレーモードを利用する場合、その利用環境に応じて Tsurugiの設定 やクライアントの接続設定を適切に指定し、クライアント・サーバ間でBLOB中継サービスに対して通信が行えるようにする必要があります。

Important

Tsurugiの初期設定では、Tsurugiに組み込まれているgRPCサーバが無効となっているため、リレーモードが利用できないようになっています。
リレーモードを利用する場合には Tsurugiの設定 の説明に従いgRPCサーバを有効化した上で、必要に応じてその他の設定項目を適切に指定してください。

特権モード (privileged mode)

特権モードは、Tsurugiサーバが管理するファイルシステム上のBLOBデータをクライアントが直接読み書きする方式です。
実行環境に強い制約を受けるが性能が高く、通常はIPC接続を利用するクライアントから利用することを想定しています。

特権モードは、ローカルファイルシステムを介してBLOBデータを交換する方式であり、以下のような特徴があります:

• クライアントはローカルのTsurugiサーバに対してのみ、BLOBデータを交換できる
• クライアントはTsurugiサーバがファイルシステムとして管理するBLOBデータのファイルに直接アクセスできる権限が必要となるため、セキュリティ上のリスクがある
  • 詳しくは後述の 特権モードのセキュリティ を参照してください。
• データ転送に関するオーバーヘッドが少なく、多くの場合にリレーモードに比べて性能が優れる

特権モードを利用するには、その利用環境や権限に強い制約が生じます。具体的には、以下の条件を満たす必要があります:

• クライアントからサーバに BLOBデータを送る場合、クライアントが作成した BLOBデータのファイルを、サーバの tsurugidb プロセスが読み出し可能でなければならない
• クライアントがサーバから BLOBデータを受け取る場合、 tsurugidb プロセスが作成した BLOBデータのファイルを、クライアントが読み出し可能でなければならない
  • tsurugi.ini の datastore セクション、 log_location で指定したディレクトリ配下に blob というフォルダを作成し、その配下に個別のファイルを配置します
• BLOBデータのファイルをやり取りする際、クライアント・サーバそれぞれから見て同一のファイルシステム上の、同一のパスでファイルにアクセスできる必要がある
  • Docker などを利用する場合、クライアントとサーバでファイルパスが異なることが多いため、特に注意が必要です。
  • これを解決するための機能として、ファイルパスの変換機能とAPIを提供しています。詳しくは後述の 特権モードにおけるファイルパスの変換 を参照してください。

特権モードを利用する場合、上記の条件を満たすようなクライアントアプリケーションの実装や実行環境の構築を行う必要があります。

Tsurugiの設定

BLOB, CLOB 型の利用に関連する Tsurugiの構成定義ファイル (tsurugi.ini) の設定項目のうち、ここでは特に初期設定として重要な項目について説明します。すべての構成定義ファイルの設定項目については、以下のドキュメントを参照してください。

• https://github.com/project-tsurugi/tsurugidb/blob/master/docs/config-parameters.md

リレーモードに関連する設定項目

• [grpc_server] セクション
  • enabled (デフォルト値: false)
    • BLOB中継サービスを提供するgRPCサーバを起動するかどうかを指定します。
    • リレーモードを利用する場合、この項目を true に設定する必要があります。
  • listen_address (デフォルト値: 0.0.0.0:52345)
    • BLOB中継サービスを提供するgRPCサーバの待ち受けアドレスを指定します。
    • この値を変更した場合、後述の endpoint の値を合わせて適切に設定する必要があります。
  • endpoint (デフォルト値: dns:///localhost:52345)
    • Tsurugiがセッション接続時にクライアントへ提供する、BLOB中継サービスのエンドポイントです。リレーモードを使用するクライアントは、このエンドポイント上のBLOB中継サービスに接続します。
    • リモートのクライアントからBLOB中継サービスに接続する際は、この値をネットワーク構成に応じて適切に設定する必要があります。
    • この値はセッション接続時に各種クライアントAPIから指定することも可能です。複数のクライアントが異なるネットワーク環境にある場合などではサーバ側が提供する単一のエンドポイントでは不十分な場合があります。その場合はクライアントAPIから適切なエンドポイントを指定してください。
  • secure (デフォルト値: false)
    • BLOB中継サービスのエンドポイントに対してTLS認証を有効にするかどうかを指定します。
    • この値を true に設定した場合、さらに設定項目 fullchain_crt と server_key に適切なフルチェイン証明書とサーバ秘密鍵のファイルパスを指定する必要があります。
    • TLS認証を有効にした場合、クライアントはBLOB中継サービスのエンドポイントに対してTLS認証を行うための設定を適切に指定する必要があります。
      • Javaクライアントの場合、JSSEの設定を利用してTLS認証を行います。詳しくは Java Secure Socket Extension (JSSE) Reference Guide などを参照してください。
      • その他のクライアントについては、各種クライアントAPIのドキュメントを参照してください。
• [blob_relay] セクション
  • BLOB中継サービスの動作に関連する設定項目です。通常はデフォルト値のままで問題ありません。

特権モードに関連する設定項目

Note

以下の設定は通常変更する必要はありません。

• [stream_endpoint] セクション
  • allow_blob_privileged (デフォルト値: false)
    • TCPエンドポイントから特権モードの利用を許可するかどうかを指定します。
    • セキュリティ上の理由から、TCPエンドポイントから特権モードの利用はデフォルトで無効になっています。
• [ipc_endpoint] セクション
  • allow_blob_privileged (デフォルト値: true)
    • IPCエンドポイントから特権モードの利用を許可するかどうかを指定します。

Docker環境での利用

Tsurugi Dockerイメージでは、リレーモードを利用するための設定項目がデフォルトで有効になっています。

Tsurugi Dockerイメージのデフォルト設定でリレーモードを利用する場合は、Docker上で動作するBLOB中継サービスの待ち受けポート 52345 をホスト側にマッピングしてDockerコンテナを起動します。

詳しくは、以下のドキュメントを参照してください。

• https://github.com/project-tsurugi/tsurugidb/blob/master/docs/docker-tsurugi_ja.md#blob中継サービスの利用

SQL

SQLからBLOB, CLOB 型を利用する方法について説明します。

BLOB, CLOB 型の列を定義する

BLOB, CLOB 型の列を定義するには、 CREATE TABLE 文のカラム定義に、それぞれ BLOB または CLOB を指定します。

CREATE TABLE t (
  id BIGINT PRIMARY KEY,
  message CLOB
);

なお、 BLOB, CLOB 型にはそれぞれ別名があります:

• BINARY LARGE OBJECT
• CHARACTER LARGE OBJECT
• CHAR LARGE OBJECT

BLOB, CLOB 型の型変換

BLOB, CLOB 型はCASTにより以下の型変換が可能です。

• BLOB型: BINARY, VARBINARY 型との相互変換
• CLOB型: CHAR, VARCHAR 型との相互変換

型変換に詳しくは、以下のドキュメントを参照してください。

• Available SQL features in Tsurugi / Explicit conversion

クライアントツール・API

各種クライアントツール・APIを利用して BLOB, CLOB 型を操作する方法について説明します。

tgsql (SQLコンソール)

tgsql コマンドを利用して BLOB, CLOB 型のデータを取得するには、以下のように記述します:

tgsql> begin;
transaction started. option=[
  type: OCC
]

tgsql> select * from blob_example;
[pk: INT4, value: BLOB]
[1, null]
[2, blob@0]
[3, blob@1]
(3 rows)

tgsql> \store blob@0 /tmp/blob-0.bin

tgsql> commit;
transaction commit(DEFAULT) finished.

注意点として、 SELECT 文の結果セットに含まれる BLOB, CLOB 型のデータを取得するには、その SELECT 文を実行したトランザクションが終了するまでの間に実施する必要があります。
トランザクションが終了すると、その結果セットに含まれる BLOB, CLOB 型のデータは利用不可能になります。

tgsql のBLOB, CLOB 型に対する機能の詳細については、以下のドキュメントを参照してください。

• Tsurugi SQL console BLOB/CLOB

Tip

現時点では tgsql コマンド経由でファイルを入力として BLOB, CLOB 型のデータを直接登録する機能は提供していません。
リテラルによるBLOB, CLOB 型のデータ登録や、他のデータ型からキャストしてBLOB, CLOB 型のデータを登録することは可能です。

tgsql でのBLOB転送モードの指定

tgsql コマンドでBLOB転送モードを指定するには、 --lob-transfer-type オプションを利用します。

$ tgsql -c ipc:tsurugi --lob-transfer-type PRIVILEGED

--lob-transfer-type オプションの詳細については、以下のドキュメントを参照してください。

• tgsql DB接続

Iceaxe (高レベル Java API)

Iceaxe で BLOB転送モードを設定する

Iceaxe では、セッション接続時のオプションでBLOB転送モードに関する設定を行います。

リレーモードの設定例:

var connector = TsurugiConnector.of("tcp://tsurugi-server:12345");
var sessionOption = TgSessionOption.of()
    .setLobTransferType(TgLobTransferType.RELAY)
    .setBlobRelayServiceEndpoint(URI.create("dns:///tsurugi-server:52345"));
try (var session = connector.createSession(sessionOption)) {
}

Iceaxe で BLOB, CLOB 型の列にデータを挿入する

Iceaxe が提供するAPIを利用して BLOB, CLOB 型の列にデータを挿入するには、以下のようなプログラムを作成します:

void insert(TsurugiTransactionManager tm) throws IOException, InterruptedException {
    var sql = "insert into blob_example values(:pk, :value)";
    var variables = TgBindVariables.of().addInt("pk").addBlob("value");
    var parameterMapping = TgParameterMapping.of(variables);

    try (var ps = tm.getSession().createStatement(sql, parameterMapping)) {
        var lobFactory = tm.getSession().getLobFactory();
        tm.execute(transaction -> {
            var value = new byte[] { 1, 2, 3 };
            try (TgRemoteBlob blob = lobFactory.uploadBlob(value)) {
                var parameter = TgBindParameters.of()
                    .addInt("pk", 1)
                    .addBlob("value", blob);
                transaction.executeAndGetCountDetail(ps, parameter);
            }
        });
    }
}

Iceaxe で BLOB, CLOB 型の列を参照する

Iceaxe が提供するAPIを利用して BLOB, CLOB 型の列を参照するには、以下のようなプログラムを作成します:

void select(TsurugiTransactionManager tm) throws IOException, InterruptedException {
    var sql = "select pk, value from blob_example order by pk";
    var resultMapping = TgResultMapping.of(record -> record);

    try (var ps = tm.getSession().createQuery(sql, resultMapping)) {
        tm.execute(transaction -> {
            transaction.executeAndForEach(ps, record -> { // TsurugiResultRecord
                try (TgBlobReference blob = record.getBlob("value")) {
                    try (InputStream is = blob.openInputStream()) {
                        // isからデータを読む
                    }
                }
            });
        });
    }
}

Iceaxe の BLOB, CLOB 型に対する機能の詳細については、以下のドキュメントを参照してください。

• Iceaxe BLOB, CLOB使用方法

Tsubakuro/Java (低レベル Java API)

Tsubakuro/Java で BLOB転送モードを設定する

Tsubakuro/Java では、接続セッションに対してBLOB転送モードに関する設定を行います。

リレーモードの設定例:

var session = SessionBuilder
    .connect("tcp://tsurugi-server:12345")
    .withBlobTransfer(BlobTransferType.RELAY)
    .withBlobRelayEndpoint("dns:///tsurugi-server:52345")
    .create();

特権モードの設定例:

var session = SessionBuilder
    .connect("ipc:tsurugi")
    .withBlobTransfer(BlobTransferType.PRIVILEGED)
    .create();

Tsubakuro/Java で BLOB, CLOB 型の列にデータを挿入する

Tsubakuro/Java が提供するAPIを利用して BLOB, CLOB 型の列にデータを挿入するには、以下のようなプログラムを作成します:

var sql = "insert into blob_example values(:pk, :value)";
var placeholders = List.of(
    Placeholders.of("pk", AtomType.INT4),
    Placeholders.of("value", AtomType.BLOB)
);
var ps = sqlClient.prepare(sql, placeholders).await();

var path = Path.of("/tmp/blobdata.bin");
Files.write(path, new byte[] { 1, 2, 3 });
var lobClient = session.getLargeObjectClient();
var blob = lobClient.upload(path).await();

var parameters = List.of(
    Parameters.of("pk", 1),
    Parameters.blobOf("value", blob)
);
transaction.executeStatement(ps, parameters).await();

Tsubakuro/Java で BLOB, CLOB 型の列を参照する

Tsubakuro/Java が提供するAPIを利用して BLOB, CLOB 型の列を参照するには、以下のようなプログラムを作成します:

var blobReference = resultSet.fetchBlob();
try (InputStream is = transaction.openInputStream(blobReference).await()) {
    ...
}

var clobReference = resultSet.fetchClob();
try (Reader r = new BufferedReader(transaction.openReader(clobReference).await())) {
    ...
}

ユーティリティメソッド

Transaction インターフェースではBLOBを扱ういくつかのユーティリティメソッドも提供しています。

var blobReference = resultSet.fetchBlob();
transaction.copyTo(blobReference, Path.of("/path/to/dest/blobdata.bin")).get();

Tsubakuro/Java のAPI詳細については、以下のJavadocを参照してください。

• https://javadoc.io/doc/com.tsurugidb.tsubakuro/tsubakuro-session/latest/index.html

Tsurugi JDBC

Tsurugi JDBC で BLOB転送モードを設定する

Tsurugi JDBC では、JDBC URLやプロパティー等でBLOB転送モードに関する設定を行います。

リレーモードの設定例:

var url = "jdbc:tsurugi:tcp://tsurugi-server:12345?lobTransferType=RELAY&blobRelayServiceEndpoint=dns%3A%2F%2F%2Ftsurugi-server%3A52345";
try (var connection = DriverManager.getConnection(url)) {
}

Note

JDBC URLのクエリー文字列では、: や / はURLエンコードする必要があります。

var url = "jdbc:tsurugi:tcp://tsurugi-server:12345";
var info = new Properties();
info.setProperty("lobTransferType", "RELAY");
info.setProperty("blobRelayServiceEndpoint", "dns:///tsurugi-server:52345");
try (var connection = DriverManager.getConnection(url, info)) {
}

Tsurugi JDBC で BLOB, CLOB 型の列にデータを挿入する

Tsurugi JDBCで BLOB, CLOB 型の列にデータを挿入するための特別なAPIはありません。一般的なJDBCと同様に、以下のようなプログラムを作成します:

var sql = "insert into blob_example values (?, ?)";
try (var ps = connection.prepareStatement(sql)) {
    try (var is = new ByteArrayInputStream(new byte[] { 1, 2, 3 })) {
        ps.setInt(1, 1);
        ps.setBlob(2, is);
        ps.executeUpdate();
    }
}

Tsurugi JDBC で BLOB, CLOB 型の列を参照する

Tsurugi JDBCで BLOB, CLOB 型の列を参照するための特別なAPIはありません。一般的なJDBCと同様に、以下のようなプログラムを作成します:

try (var statement = connection.createStatement()) {
    var sql = "select * from blob_example order by pk";
    try (var rs = statement.executeQuery(sql)) {
        while (rs.next()) {
            int pk = rs.getInt("pk");
            byte[] value;
            {
                Blob blob = rs.getBlob("value");
                if (blob == null) {
                    value = null;
                } else {
                    try (var is = blob.getBinaryStream()) {
                        value = is.readAllBytes();
                    }
                }
            }
        }
    }
}

Tsurugi JDBC のBLOB, CLOB 型に対する機能の詳細については、以下のドキュメントを参照してください。

• Tsurugi JDBC BLOB, CLOB使用方法

Tsubakuro/Rust (Rust API)

Tsubakuro/Rust で BLOB転送モードを設定する

Tsubakuro/Rust では、セッション接続時のオプションでBLOB転送モードに関する設定を行います。

リレーモードの設定例:

let mut connection_option = ConnectionOption::new();
connection_option.set_endpoint_url("tcp://tsurugi-server:12345")?;
connection_option.set_lob_transfer_type(LobTransferType::Relay);
connection_option.set_blob_relay_service_endpoint("http://tsurugi-server:52345");

let session = Session::connect(&connection_option).await?;

Note

Tsubakuro/Rust ではBLOB中継サービスのエンドポイントで dns:/// は使用できません。http:// に置き換えてください。

Tsubakuro/Rust で BLOB, CLOB 型の列にデータを挿入する

Tsubakuro/Rust が提供するAPIを利用して BLOB, CLOB 型の列にデータを挿入するには、以下のようなプログラムを作成します:

let client: SqlClient = session.make_client();

let sql = "insert into blob_example values(:pk, :value)";
let placeholders = vec![
    SqlPlaceholder::of::<i32>("pk"),
    SqlPlaceholder::of::<TgBlob>("value"),
];
let ps = client.prepare(sql, placeholders).await?;

let value = vec![0x01_u8, 0x02_u8, 0x03_u8];
let blob = client.upload_blob(&value).await?;

let parameters = vec![
    SqlParameter::of("pk", 1_i32),
    SqlParameter::of("value", blob),
];
let execute_result = client.prepared_execute(transaction, ps, parameters).await?;

Tsubakuro/Rust で BLOB, CLOB 型の列を参照する

Tsubakuro/Rust が提供するAPIを利用して BLOB, CLOB 型の列を参照するには、以下のようなプログラムを作成します:

let blob: TgBlobReference = query_result.fetch().await?;
let value = client.read_blob(transaction, &blob).await?; // Vec<u8>

Tsubakuro/Rust の BLOB, CLOB 型に対する機能の詳細については、以下のドキュメントを参照してください。

• tsubakuro-rust-core BLOB, CLOB使用方法

Tsurugi Python DB-API

Tsurugi Python DB-API は、BLOB中継サービスのみ利用できます。

したがって、BLOB転送モードを設定することはできません。

リレーモードの設定例:

BLOB中継サービスのエンドポイントを指定する場合は、セッション接続時のConfigで指定します。

config = tsurugi.Config()
config.endpoint = "tcp://tsurugi-server:12345"
config.blob_relay_service_endpoint = "http://tsurugi-server:52345"

with tsurugi.connect(config) as connection:
    pass

Note

Tsurugi Python DB-API ではBLOB中継サービスのエンドポイントで dns:/// は使用できません。http:// に置き換えてください。

Tsurugi Python DB-API で BLOB, CLOB 型の列にデータを挿入する

Tsurugi Python DB-API が提供するAPIを利用して BLOB, CLOB 型の列にデータを挿入するには、以下のようなプログラムを作成します:

with connection.cursor() as cursor:
    sql = "insert into blob_example values (?, ?)"
    blob = cursor.upload_blob(b'\x01\x02\x03')
    parameters = (1, blob)
    cursor.execute(sql, parameters)

Tsurugi Python DB-API で BLOB, CLOB 型の列を参照する

Tsurugi Python DB-API で BLOB, CLOB 型の列を参照するための特別なAPIはありません。

with connection.cursor() as cursor:
    cursor.execute("select pk, value from blob_example order by pk")
    for row in cursor:
        print("row:", row)

Tsurugi Python DB-API の BLOB, CLOB 型に対する機能の詳細については、以下のドキュメントを参照してください。

• Tsurugi Python DB-API BLOB, CLOB使用方法

その他の機能

特権モードにおけるファイルパスの変換

Iceaxe, Tsubakuro/Java 等のクライアントライブラリでは、特権モードでクライアントとサーバ間でファイルの交換を行う際にファイルパスを自動的に変換する機能を提供しています。これにより、クライアントとサーバで異なるファイルシステム構成となっている場合でも、特権モードを利用して BLOBデータの交換が可能になります。

• 例えばWindowsクライアントを利用している場合に、サーバ上で /opt/tsurugi/var/data/log/blob 上に BLOB ファイルが配備されている際、それをクライアントは C:\tmp\tsurugi\blob に読み替えてアクセスすることが可能です。
• ファイルパスの変換ルールはクライアントライブラリのAPIを利用して各セッションに対して設定することが可能です。
  • 今後のバージョンで、APIの他にファイルパスの変換ルールを定義ファイルに設定し、これをアプリケーションに自動適用する機能を検討しています。

Iceaxe

Iceaxe では以下のようにファイルパスの変換ルールを指定します。

var connector = TsurugiConnector.of("tcp://localhost:12345");
var sessionOption = TgSessionOption.of()
    .setLobTransferType(TgLobTransferType.PRIVILEGED)
    .addLargeObjectPathMappingOnSend(Path.of("C:/tmp/client"), "/mnt/client")
    .addLargeObjectPathMappingOnReceive("/opt/tsurugi/var/data/log", Path.of("C:/tmp/tsurugi"));
try (var session = connector.createSession(sessionOption)) {
}

Tsubakuro/Java

Tsubakuro/Java では以下のようにファイルパスの変換ルールを指定します。

var session = SessionBuilder
    .connect("tcp://localhost:12345")
    .withBlobTransfer(BlobTransferType.PRIVILEGED)
    .withBlobPathMapping(
        BlobPathMapping.newBuilder()
            .onSend(Path.of("C:/tmp/client"), "/mnt/client")
            .onReceive("/opt/tsurugi/var/data/log", Path.of("C:/tmp/tsurugi"))
            .build()
    )
    .create();

Tsurugi JDBC

Tsurugi JDBC では以下のようにファイルパスの変換ルールを指定します。

var config = new TsurugiConfig();
config.setLobTransferType(TsurugiJdbcLobTransferType.PRIVILEGED);
config.addLobPathMappingOnSend(Path.of("C:/tmp/client"), "/mnt/client");
config.addLobPathMappingOnReceive(Path.of("C:/tmp/tsurugi"), "/opt/tsurugi/var/data/log");
try (var connection = TsurugiDriver.getTsurugiDriver().connect(config)) {
}

Tsubakuro/Rust

Tsubakuro/Rust では以下のようにファイルパスの変換ルールを指定します。

let mut connection_option = ConnectionOption::new();
connection_option.set_endpoint_url("tcp://localhost:12345")?;

connection_option.set_lob_transfer_type(LobTransferType::Privileged);
connection_option.add_large_object_path_mapping_on_send("C:/tmp/client", "/mnt/client");
connection_option.add_large_object_path_mapping_on_recv("/opt/tsurugi/var/data/log", "C:/tmp/tsurugi");

let session = Session::connect(&connection_option).await?;

Tsurugi Python DB-API

Tsurugi Python DB-API は特権モードに対応していないため、ファイルパスの変換ルールを指定することはできません。

トラブルシューティング

ここではBLOB, CLOB 型の利用時に発生する代表的なエラーについて説明します。

リレーモード利用時のエラー

CoreServiceException: the requested blob transfer method (RELAY) is unavailable

リレーモードの利用時に以下のエラーが発生する:

com.tsurugidb.tsubakuro.exception.CoreServiceException:
SCD-00101: the requested blob transfer method (RELAY) is unavailable

この場合、以下の点を確認してください。

• Tsurugiの構成定義ファイル (tsurugi.ini) の [grpc_server] セクションのパラメータ enabled が true に設定されているか
• Tsurugiの構成定義ファイル (tsurugi.ini) の [blob_relay] セクションのパラメータ enabled が true に設定されているか

IOException: Blob relay service is unavailable on dns:...

リレーモードの利用時に以下のようなエラーが発生する:

java.io.IOException: Blob relay service is unavailable on dns:///localhost:52345
due to io.grpc.netty.shaded.io.netty.channel.AbstractChannel$AnnotatedConnectException:
finishConnect(..) failed with error(-111): Connection refused: localhost/127.0.0.1:52345

この場合、様々なネットワーク構成に起因する問題が考えられます。例外メッセージを参考に、以下の点などを確認してください。

• Tsurugiの構成定義ファイル (tsurugi.ini) の [grpc_server] セクションのパラメータ endpoint が クライアントから接続可能な値に設定されているか。
  • リモートのクライアントからTsurugiに接続する場合、ホスト名にクライアントから見たTsurugiサーバのリモートホスト名を指定する必要があります。
  • ネットワーク構成によって、複数のクライアント毎にTsurugiのサーバアドレスが異なる場合、クライアント毎に適切なサーバアドレスを指定する必要があります。

特権モード利用時のエラー

CoreServiceException: the requested blob transfer method (PRIVILEGED) is unavailable

特権モードの利用時に以下のエラーが発生する:

com.tsurugidb.tsubakuro.exception.CoreServiceException:
SCD-00101: the requested blob transfer method (PRIVILEGED) is unavailable

この場合、以下の点を確認してください。

• (TCP接続時) Tsurugiの構成定義ファイル (tsurugi.ini) の [stream_endpoint] セクションの allow_blob_privileged が true に設定されているか
• (IPC接続時) Tsurugiの構成定義ファイル (tsurugi.ini) の [ipc_endpoint] セクションの allow_blob_privileged が true に設定されているか

BlobException: Privileged upload from [InputStream|Reader] is not supported

特権モードの利用時に以下のエラーが発生する:

com.tsurugidb.tsubakuro.common.exception.BlobException:
Privileged upload from InputStream is not supported.

特権モード利用時に、クライアントAPIによっては固有の制約が設定されている場合があります。

上記のエラーは Tsubakuroを利用して特権モードでBLOBデータをサーバに送信する際に、 InputStream や Reader インターフェースを利用して送信しようとした場合に発生します。Tsubakuroでは、特権モードでBLOBデータをサーバに送信する際にはローカルファイルシステム上のファイルを指定して送信する必要があります。

[CoreServiceException|BlobException]: tsurugidb failed to receive BLOB file in privileged mode ...

特権モードの制約である、クライアント・サーバそれぞれから見て同一のファイルシステム上の、同一のパスでファイルにアクセスできるという条件が満たされない場合に発生します。

クライアントからBLOB データの登録(INSERT文など)に失敗する例 - クライアントが指定したBLOB データのファイルパスがサーバ上で見つからなかった場合:

com.tsurugidb.tsubakuro.exception.CoreServiceException:
SCD-00404: tsurugidb failed to receive BLOB file in privileged mode (file not found): "/path/to/blobdata.bin"

クライアントからBLOB データを参照(SELECT文実行後、BLOB データの取得)に失敗する例 - サーバが管理するBLOB データのファイルパスがクライアント上で見つからなかった場合:

com.tsurugidb.tsubakuro.sql.io.BlobException:
error occurred while receiving BLOB data: {client failed to receive BLOB file in privileged mode:
{NoSuchFile:/opt/tsurugi/var/data/log/blob/dir_01/0000000000000001.blob}}

また、クライアントから指定するファイルパスにはディレクトリやシンボリックリンクを指定することはできません:

com.tsurugidb.tsubakuro.exception.CoreServiceException:
SCD-00404: tsurugidb failed to receive BLOB file in privileged mode (not regular file): "/path/to/blobdata.bin.link"

高度な話題

特権モードのセキュリティ

特権モードは、ファイルシステムを介して BLOBデータを交換するため、「サーバの tsurugidb プロセスの権限を利用して、本来アクセスできないはずのファイルを読めてしまう」というセキュリティ上の問題があります。

上記に対応するため、特権モードに対して「許可リスト」の導入を予定しています。
これは、サーバが BLOBデータのファイルパスを受け取った際、許可リストに含まれないディレクトリの配下であれば、それを拒否するという仕組みです。

これにより、「本来アクセスできないはずのファイルを読めてしまう」という問題の大半を解消します。

なお、リレーモードではサーバ側のファイルシステムを直接操作することはないため、この問題は発生しません。

BLOBのライフサイクル

BLOBデータは、クライアントからの要請 (例: SQLのプレースホルダに対する指定) によって作成され、Tsurugi 内に保存します。
このとき、ログ (WAL) データを格納しているディレクトリ (datastore.log_location) の下に blob というディレクトリを作成し、その配下に BLOB ごとに個別のファイルを作成します。

BLOBデータは、不要になった際にガベージコレクション機構によって自動的に削除されます。
これはつまり、 DELETE 文や DROP TABLE 文を実行しても、即座に BLOBデータが削除されるわけではありません。

具体的には、次の 3 つのステップで削除が行われます:

1. BLOBデータを含むテーブル上の行 R に対し、削除を行うバージョン V を追加する (DELETE 文等を実行)
2. バージョン V 以前の行 R を参照可能なすべてのトランザクションが終了し、ガベージコレクションの境界が V 以上に到達する
3. ガベージコレクションが行われ、行 R のバージョン V 以前の行が物理的に削除され、その際に関連する BLOB ファイルが削除される

上記のような仕組みで BLOBデータを管理しているため、BLOBデータを取得するには、その行を取得したトランザクション内で、 BLOBデータを取り出す必要があります。
なぜなら、当該トランザクションが終了すると、2番目の手順によってガベージコレクションの境界が替わり、当該 BLOBデータが削除される可能性があるためです。

なお、ガベージコレクションを実際に実行するには、以下のいずれかの操作が必要です:

• データベースの再起動
• コンパクションツールの実行

バックアップ・リストアについて

バックアップ・リストアにおいて BLOB, CLOB を含むテーブルデータを対象とする場合、上述の blob ディレクトリの配下で管理している BLOB ファイルもバックアップ・リストアの対象となります。

• tgctl backup create コマンドでバックアップを作成する際、BLOB, CLOB ファイルもバックアップに含まれます。
• tgctl restore backup コマンドでバックアップをリストアする際、バックアップに含まれる BLOB, CLOB ファイルもリストアされます。