PythonでTsurugi（劔）に接続してみる

前回の「Tsurugi（劔）を試す！インストール〜起動手順」で、Tsurugiを実際に起動してtgsqlからSQLを叩けるところまで確認しました。今回はその続き。

コンソールで動かせても、業務システムから使えなければ意味がありません。Tsurugiの接続手段、今のところはJava向けクライアントが中心。とはいえPython向けの選択肢もちゃんと用意されていて、今回はPython DB-API（データベース接続の標準的な作法を定めた仕様）に準拠した「tsurugi-dbapi」を使い、接続からSQL実行までを一気に動かします。

Tsurugiへの接続方法は1つじゃない
tsurugi-dbapiをインストールする
接続してSQLを実行するサンプルコード
よくあるつまずきポイント
まとめ

Tsurugiへの接続方法は1つじゃない

Tsurugi公式が用意しているクライアントは、いくつかの種類に分かれます。まず整理しておきましょう。

Tsubakuro：低レベルのJava通信ライブラリ。Tsurugiの機能をほぼそのまま扱える分、コード量は多くなりがちです
Iceaxe：Tsubakuroの上に作られた、より書きやすい高レベルJava API
tsurugi-jdbc：JavaのDB接続の標準規格であるJDBCでTsurugiにアクセスするドライバ
tsurugi-dbapi：今回使うPython向けクライアント。Python DB-API 2.0（PEP 249という仕様）に準拠

ご覧の通り、現状はJava系のラインナップが手厚い印象です。TsurugiはNECとノーチラス・テクノロジーズが主導する国産OSSで、開発リソースの都合上どうしてもJava系が先行しているのだと思います。Pythonでのデータ分析やAI活用がメインの方からすると、少し寂しく感じるかもしれません。それでもtsurugi-dbapiがあれば、pandasなどPythonのデータ処理エコシステムと組み合わせる道はきちんと開けています。

今回はこのtsurugi-dbapiに絞って、実際に手を動かしていきます。

tsurugi-dbapiをインストールする

必要なのは次の2つだけです。

Tsurugiサーバーが起動していること（前回のtgctl startを実行済みの状態）
Python 3.10以上の実行環境

バージョン要件は意外と厳しめ。tsurugi-dbapiはPython 3.10以上、Tsurugi本体もv1.11.0以上を求めます。古めの環境を使い回している方は、先にバージョンを確認しておいてください。

インストールはpipで一発です。

pip install tsurugi-dbapi

uvを使っている方は、こちらでも問題ありません。

uv add tsurugi-dbapi

続いて、接続先の指定方法を確認しておきます。前回のtgsqlではipc:tsurugiという書き方で、同一マシン内の接続（IPC接続。プロセス間通信を使う方式）をしていました。ですがtsurugi-dbapiが対応しているのは、執筆時点ではTCP接続（tcp://）のみ。ipc:形式は、今のところ使えません。

tcp://localhost:12345

12345の部分は、Tsurugi側の設定（tsurugi.iniのstream_endpointのポート番号）と一致させる必要があります。前回Dockerで-p 12345:12345を指定していたなら、ポート番号はそのままで大丈夫でしょう。

接続してSQLを実行するサンプルコード

お待たせしました。ここからが本題です。まずは基本の形から見ていきます。

import tsurugi_dbapi as tsurugi

connection = tsurugi.connect(
    endpoint="tcp://localhost:12345",
    user="tsurugi",
    password="password",
    default_timeout=30,
)

cursor = connection.cursor()

cursor.execute(
    "CREATE TABLE customer (id INT PRIMARY KEY, name VARCHAR(20), age INT)"
)
connection.commit()

cursor.execute(
    "INSERT INTO customer (id, name, age) VALUES (1, 'Sato', 34)"
)
print("登録件数:", cursor.rowcount)
connection.commit()

cursor.execute("SELECT id, name, age FROM customer")
for row in cursor:
    print(row)
connection.commit()

cursor.close()
connection.close()

1つずつ、何をしているか見ていきます。

tsurugi.connect(...)：Tsurugiサーバーへの接続を作ります。userとpasswordは引数として必須です。ただし現状のTsurugiはデフォルトで認証機能が無効になっており、値そのものは厳しくチェックされません（詳しくは後述します）
connection.cursor()：カーソル（SQLを実行し結果をやり取りする窓口）を取得します
cursor.execute(...)：SQLを1文実行。CREATE TABLEもINSERTもSELECTも、同じexecuteメソッドに文字列として渡すだけです
connection.commit()：ここまでの変更を確定します。Tsurugiはトランザクション（一連の処理をひとまとまりとして扱う仕組み）前提のDBなので、commitを忘れると変更が反映されません
for row in cursor:：SELECT実行後、カーソルをそのままイテレータ（順番に値を取り出せるもの）として扱い、結果行を1件ずつ取り出せます
cursor.close() / connection.close()：使い終わったら明示的に閉じます

SELECTのように読み取るだけの操作でも、Tsurugiは内部的にトランザクションを開始しています。読み終わったらcommit（またはrollback）でそのトランザクションを閉じておくのが作法です。うっかり忘れがちなので、注意してください。

このコードは、公式ドキュメント（tsurugi-dbapi.readthedocs.io）に掲載されているサンプルの記法に沿って組み立てたものです。公開前には手元の検証環境で一通り動作確認する予定です。DB-API 2.0という枯れた仕様に沿っているだけあって、psycopg2（PostgreSQL用のPythonライブラリ）などを触ったことがある人には違和感が少ないはずです。

毎回close()を書くのが面倒、あるいは書き忘れが心配という方には、with文を使う書き方をおすすめします。接続もカーソルも、ブロックを抜けるタイミングで自動的に閉じてくれます。先ほど作成したcustomerテーブルをそのまま使います。

import tsurugi_dbapi as tsurugi

with tsurugi.connect(
    endpoint="tcp://localhost:12345",
    user="tsurugi",
    password="password",
    default_timeout=30,
) as connection:
    with connection.cursor() as cursor:
        cursor.execute("SELECT id, name, age FROM customer")
        for row in cursor:
            print(row)
        connection.commit()

正直、こちらの書き方のほうが実用上は安全です。例外が起きたときの閉め忘れが発生しにくく、私も普段はこちらを使う派。公式のサンプルコードもこのwith文の形で紹介されています。

よくあるつまずきポイント

ここまでの手順、実際にやってみると細かいところで引っかかりがちです。

エンドポイントの不一致：Tsurugi側のポート設定（tsurugi.ini）とPythonコード側のtcp://localhost:XXXXXが食い違っていると接続エラーになります。前回Dockerで起動した場合は、-pで指定したポート番号と合わせてください
認証情報まわりの誤解：先ほど触れた通り、Tsurugiはデフォルトだと認証機能そのものが無効です。userやpasswordを適当に入れても接続できてしまいます。認証を効かせるには認証サービス「Harinoki」を起動し、tsurugi.iniの[authentication]セクションを設定する必要がありますが、この設定は次回のセキュリティ編で扱います
サーバーが起動していない：地味に一番多いミスです。tgctl statusで「RUNNING」になっているか、まず確認してください
仕様がまだ変わりやすい：tsurugi-dbapiはできて間もないOSS。引数名やデフォルト値が今後のバージョンで変わる可能性は十分にあります。迷ったら公式ドキュメント（tsurugi-dbapi.readthedocs.io）の最新版を確認する習慣をつけておくと安心です

まとめ

今回はPythonからTsurugiに接続する方法を見てきました。

Tsurugiへの接続手段はJava系（Tsubakuro、Iceaxe、tsurugi-jdbc）が中心だが、Python DB-API準拠の「tsurugi-dbapi」も用意されている
インストールはpip install tsurugi-dbapiのみ。Python 3.10以上、Tsurugi 1.11.0以上が必要
エンドポイントは現状tcp://のみ対応。ipc:はまだ使えない
connect → cursor → execute → commit → closeという流れは、PostgreSQLなど他のDBと大きくは変わらない