S-JIS[2025-12-25]

udf-plugin-builder

TsurugiのSQLのユーザー定義関数（UDF）をTsurugiに登録するツールのメモ。

概要

udf-plugin-builderは、TsurugiのUDFをTsurugiに登録するツール。

UDFの定義が書かれたprotoファイルをgRPCクライアントとしてビルドし、soファイルとiniファイルを生成する。
このため、Tsurugiと同じサーバー上で実行する。

Python製なので、実行環境にPython 3.10以降が必要。
（TsurugiのDockerイメージはPython 3.10が入っている）

また、udf-plugin-viewerというツールもある。

udf-plugin-builderによって生成されたsoファイルの中身（UDFの定義）を表示する。

Tsurugi Dockerイメージへのインストール

TsurugiのDockerイメージにudf-plugin（udf-plugin-builderとudf-plugin-viewer）をインストールする方法。

実行ファイルは提供されていないので、ソースからビルドする必要がある。
ビルドするためには、依存ライブラリーをインストールしておく必要がある（が、Tsurugi 1.8.0のDockerイメージにはほとんど入っている）。

1. rootユーザーでDockerコンテナ―に入る。

   docker container exec -u 0 -it tsurugi bash

2. 依存ライブラリーをインストールする。

   apt update -y
   apt install -y python3-pip
   pip3 install --upgrade pip    # Ubuntu 22.04のpipは古いので、バージョンアップする必要がある

3. 一般ユーザーでDockerコンテナ―に入る。

   docker container exec -it tsurugi bash

4. tsurugi-udfのソースアーカイブをダウンロードし、展開する。

   TSURUGI_UDF_VERSION="0.1.0"
   curl -OL https://github.com/project-tsurugi/tsurugi-udf/archive/refs/tags/${TSURUGI_UDF_VERSION}.tar.gz
   tar xf ${TSURUGI_UDF_VERSION}.tar.gz
   ls -l tsurugi-udf-${TSURUGI_UDF_VERSION}

5. udf-pluginをインストールする。

   cd tsurugi-udf-${TSURUGI_UDF_VERSION}/udf-plugin
   pip install .
   ls -l $HOME/.local/bin/

インストールが成功すると、$HOME/.local/bin/の下にudf-plugin-builderとudf-plugin-viewerが出来ている。

実行例

udf-plugin-builderおよびudf-plugin-viewerを実行する例。

まず、UDFを定義したprotoファイルを用意する。

cd $HOME
mkdir udf-example
cd udf-example
vi example.proto 

$HOME/udf-example/example.proto：

syntax = "proto3";

message MyFunctionRequest {
  int32 value = 1;
}

message MyFunctionResponse {
  int32 value = 1;
}

service ExampleService {
  rpc my_function(MyFunctionRequest) returns (MyFunctionResponse);
}

udf-plugin-builderでprotoファイルをビルドする。

~/.local/bin/udf-plugin-builder --proto-file example.proto --output-dir $TSURUGI_HOME/var/plugins/

tsurugi@7cf3f77edb28:~/udf-example$ ls $TSURUGI_HOME/var/plugins/
libexample.ini libexample.so

iniファイル（プラグイン設定ファイル）の中には、gRPCサーバーの接続先が書かれている。
接続先はudf-plugin-builderの--grpc-endpointオプションで指定できる。デフォルトはdns:///localhost:50051。

udf-plugin-viewerでUDFを確認できる。

~/.local/bin/udf-plugin-viewer $TSURUGI_HOME/var/plugins/libexample.so

udf-plugin-viewerの引数には、udf-plugin-builderで生成されたsoファイルのパスを指定する。