BLOB Usage and Notes (ja)

[akirakw]

BLOB の利用方法と注意点

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

なお、本機能は試験的なものであり、今後のバージョンで仕様が変更される可能性があります。

BLOB, CLOB 型の特徴

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

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

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

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

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

現状における BLOB, CLOB 型のサポート状況

現状の Tsurugi では、BLOB, CLOB 型のデータ (以下、BLOBデータ) をクライアント・サーバ間で交換する際に、ローカルファイルシステムを経由して行います。
これを「特権モード (privileged mode)」とよび、以下のような制約があります。

• クライアントからサーバに BLOB データを送る場合、クライアントが作成した BLOB データのファイルを、サーバの tsurugidb プロセスが読み出し可能でなければならない
• クライアントがサーバから BLOB データを受け取る場合、 tsurugidb プロセスが作成した BLOB データのファイルを、クライアントが読み出し可能でなければならない
  • tsurugi.ini の datastore セクション、 log_location で指定したディレクトリ配下に blob というフォルダを作成し、その配下に個別のファイルを配置します

また、上記のファイルをやり取りする際、クライアント・サーバそれぞれから見て同一のファイルシステム上の、同一のパスでファイルにアクセスできなければなりません。
例えば、TCP接続 (tcp://host:port) でリモートのサーバに接続する場合、ファイルシステムが異なるため、 BLOB データのやり取りに失敗します。
また、IPC 接続であっても Docker などを利用している場合、クライアントとサーバでファイルパスの解釈が異なるため、同様に失敗する可能性があります。

特権モードの制約を満たしていない状況では、以下のようなエラーメッセージが表示されます:

• クライアントから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}}
  

なお、上記のような問題を解決するため、以下の2点の改善を計画しています:

1. 非特権モードによる BLOB データの授受
   • ファイルシステム上で BLOB データを交換するのではなく、TCP などの通信路を介して BLOB データを交換する方式を予定しています
   • 性能的には特権モードよりもかなり見劣りすることが予想されますが、ポータビリティやセキュリティが大幅に強化されます
2. 特権モードにおけるファイルパスの変換
   • [FROM Tsurugi 1.4.0] Tsurugi 1.4.0 でファイルパスの変換機能とAPIが提供されました。後述の「ファイルパスの変換」項を参照してください。

また、特権モードには注意すべきセキュリティ上の問題があります。
詳しくは 特権モードのセキュリティ を参照してください。

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

SQL コンソールから BLOB, CLOB 型の列を参照する

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 型のデータをテーブルに登録する仕組みは提供していません。

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

• Tsurugi SQL console BLOB/CLOB

アプリケーションから BLOB, CLOB 型の列にデータを挿入する (Iceaxe)

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)) {
        List<Path> fileList;
        try (var stream = Files.list(Path.of("dir"))) {
            fileList = stream.collect(Collectors.toList());
        }

        tm.execute(transaction -> {
            int i = 0;
            for (Path path : fileList) {
                var blob = TgBlob.of(path); // TgBlobインスタンスの生成

                var parameter = TgBindParameters.of()
                    .addInt("pk", i++)
                    .addBlob("value", blob);
                transaction.executeAndGetCountDetail(ps, parameter);
            }
        });
    }
}

アプリケーションから BLOB, CLOB 型の列を参照する (Iceaxe)

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使用方法

低レベルJava APIの利用方法 (Tsubakuro)

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

var stmt = sqlClient.prepare(
    "insert into t_blob values(:pk, :blob, :clob)",
    List.of(
        Placeholders.of("pk", AtomType.INT4),
        Placeholders.of("c1", AtomType.BLOB),
        Placeholders.of("c2", AtomType.CLOB)
    ).await();
);

var params = List.of(
    Parameters.of("pk", 1),
    Parameters.blobOf("c1", Path.of("/path/to/blobdata1.bin")),
    Parameters.clobOf("c2", Path.of("/path/to/clobdata1.txt"))
);

transaction.executeStatement(stmt, params).await();

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

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

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

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

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

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

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

BLOB, CLOB 型の型変換

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

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

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

• Available SQL features in Tsurugi / Explicit conversion

ファイルパスの変換

[FROM Tsurugi 1.4.0] Tsurugi 1.4.0 でファイルパスの変換機能とAPIが提供されました。

• クライアントとサーバ間でファイルの交換を行う際、ファイルパスを自動的に変換する機能です。これにより、クライアントとサーバで異なるファイルシステム構成となっている場合でも、特権モードを利用して BLOB データの交換が可能になります
  • 例えばWindowsクライアントを利用している場合に、サーバ上で /opt/tsurugi/var/logs/blob 上に BLOB ファイルが配備されている際、それをクライアントは C:\Users\dba\AppData\Local\Tsurugi\logs\blob に読み替えてアクセスすることが可能です
• ファイルパスの変換ルールはIceaxe、またはTsubakuroのAPIを利用して各セッションに対して設定することが可能です
  • 今後のバージョンで、APIの他にファイルパスの変換ルールを定義ファイルに設定し、これをアプリケーションに自動適用する機能を検討しています

Iceaxe

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

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

Tsubakuro

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

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

高度な話題

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

現状の Tsurugi では、特権モード (privileged mode) により、クライアント・サーバ間において BLOB データの交換を行っています。

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

このため、 TCP 接続ではデフォルトで特権モードの利用が無効になっています。
有効にするには、 tsurugi.ini の stream_endpoint セクションにおいて allow_privileged_mode を true に設定します。
(Tsurugi Dockerコンテナでは stream_endpoint.allow_privileged_mode はデフォルトで true に設定されています)

また、上記に対応するため、「許可リスト」の導入を予定しています。
これは、サーバが 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 ファイルもリストアされます。