Transactd 運用マニュアル

プラグイン概要

プロトコル

Transactd プラグインとTransactd クライアントは専用のTransactd プロトコルでバイナリデータをやりとりして通信します。

TCP通信

Transactd プラグインはデフォルトでTCP Port 8610を使用します。

リモートクライアントからサーバーへアクセスする場合は、サーバーのファイアーウォールにてTCP ポート8610への接続を許可する設定を行ってください。

ローカルpipe通信

Windows上でのローカル通信に限り、ローカルpipeサーバーと共有メモリによる高速通信を行うことができます。

ローカルpipeサーバーを使用する場合は、mysqld.exeを「グローバル オブジェクトの作成」 権限を持つユーザーにて実行する必要があります。WindowsのデフォルトではSERVICE、NETWORK_SERVICE、LOCAL_SERVICE、Administratorsにその権限があります。既存のユーザーにこの権限を付与するには、Windowsの[管理ツール][ローカルセキュリティーポリシー]-[ローカルポリシー]-[ユーザー権限の割り当て]-[グローバルオブジェクトの作成]で設定します。

コネクションとスレッド

Transactdのサーバー実装は、コネクションごと専用スレッドで実行するConnection Per Thread (CPT)モデル(デフォルト)と、スレッドを事前にプールしておき空いているスレッドをランダムに使用するThread Pool (TPOOL)モデルの両方をサポートします。

CPTモデルにおいて、コネクションが切断されるとそのスレッドは不要になりますが、TransactdはそれをWait threadプールに入れ、次のコネクションで再利用します。 これによりCPTモデルにおいてもスレッド作成のコストを低減させています。

クライアントアプリケーションがマルチスレッドで動作している場合、クライアントの通信ライブラリは、サーバーへのConnect要求を受け取った際に、呼び出されたスレッドを確認し、スレッドごとに異なるコネクションを作成し利用します。Webサーバーアプリケーションなどの実装で、コネクションプールを使用することがあります。コネクションプールを実現するために、1つのスレッドからのConnect要求でも新しいコネクションを作成するオプションがあります。

コネクションとデータベース

1つのコネクションの中で複数のデータベースをオープンすることができます。たとえば、シングルスレッドのデスクトップアプリケーションにおいて、2つのウィンドウでそれぞれデータベースをオープンすると、コネクションは1つですが、データベースを2つオープンできます。2つのデータベースは1つのコネクションで操作されますので、同時に両方の操作が行われることはありません。これによりコネクションを節約し、サーバー負荷を低減します。

データベースとトランザクション

トランザクションのグルーピングはデータベース単位です。1つのコネクションから複数のデータベースをオープンした場合でも、トランザクションはデータベースごと独立して処理されます。

アクセス可能ホストの設定

Transactdのクライアント認証についてはセキュリティのページを参照してください。

ポートの変更

TransactdのデフォルトのTCPポートは8610です。このポートは任意のポートに変更可能です。

サーバーリッスンポートの変更

サーバーの待ち受けポートはmy.cnfもしくはmy.iniで変更します。

# my.cnfもしくはmy.iniの設定
[mysqld]
loose-transactd_port=8610

クライアントのポート変更

クライアントポートの変更は、下記の内容の設定ファイルを作成し、既定のフォルダに配置します。(ポートの変更が不要であれば必要ありません。)

# 設定ファイルの内容
[transctd_client]
port = 8610

配置先のパスは以下の通りです。

ローカルpipe通信の無効化(Windowsのみ)

Windowsでサーバーがローカルにある場合、クライアントとの通信は高速なローカルpipe方式で行われます。通常これを変更する必要はありませんが、ローカルでもTCPによる通信に変更することができます。 通信方法を変更するには、下記の内容の設定ファイルを作成し、既定のフォルダに配置します。

# 設定ファイルの内容
[transctd_client]
port = 8610
use_piped_local = 0

ファイル名はc:\windows\transactd.iniです。use_piped_localに0を設定すると無効になります。1で有効になります。

エラーログ

Transactd Plugin (サーバーサイド)のエラーログはMySQLのerror.logにインテグレートされています。

クライアントのエラーはWindowsでは%ProgramData%\BizStation\Transactd\transactd_clinet_err.logに出力されます。
Linuxでは/var/log/transactd_clinet_err.logに出力されます。(Version 3.4以前はtrnsctcl_error.log)

エラーの原因を追究するにはクライアントとサーバーの両方のログを確認してください。また、クライアントにおいて最初のエラーでtrnsctcl_error.logが管理者アカウントによって作成された場合、そのほかのユーザーが書き込みできない場合があります。うまくログが出力されていない場合はtrnsctcl_error.logにuserアカウントで書き込み権限があるかどうかを確認してください。

Transactd プラグインの状態の確認

コマンドラインのMySQLクライアントからshow statusコマンドを使ってTransactd プラグインの動作を確認できます。

mysql> show status like 'tr%';
+------------------------------+-------+
| Variable_name                | Value |
+------------------------------+-------+
| Transactd_cur_open_databases | 2     |
| Transactd_ha                 | 1     |
| Transactd_pipe_connections   | 2     |
| Transactd_pipe_wait_threads  | 0     |
| Transactdd_tcp_connections   | 0     |
| Transactd_tcp_wait_threads   | 0     |
| Transactd_tpool_connections  | 1     |
| Transactd_tpool_threads      | 15    |
+------------------------------+-------+

ステータスの意味は以下の通りです。

Transactd_cur_open_databases 現在開かれているデータベースの数
Transactd_ha

現在のTransactd High Availability (THA)の設定値です。以下の値の合計値が取得できます。

  • 0 このサーバーはスレーブロール
  • 1 このサーバーはマスターロール
  • 2 ロールは未指定
  • 4 再起動時に前回のロールを復元する
  • 8 THA自動フェイルオーバーが有効
Transactd_pipe_connections ローカルパイプコネクション(スレッド)の数(Windowsのみ)。 コネクション数には、accpter スレッドも含まれます。 accpterスレッドは新たな接続を待っている状態なので、実際に接続されているコネクション数は -1した数になります。
Transactd_pipe_wait_threads ローカルパイプコネクションスレッドの待機している数。接続がクローズされるとそのスレッドは次の接続のために待機状態になります。
Transactd_tcp_connections TCPコネクション(スレッド)の数 [1]
Transactd_tcp_wait_threads 待機している TCPコネクションスレッドの数 [1]
Transactd_tpool_connections TCPコネクションの数 [2]
Transactd_tpool_threads プールされたスレッドの数 [2]

[1] transactd_tcp_server_typeが1: connection per thread (cpt)server)の時に有効です。

[2] transactd_tcp_server_typeが 2: thread poool (tpool)serverの時に有効です。

前述の例では、開かれているデータベースが2個、使用中のパイプコネクション数が1、パイプコネクションのaccepterスレッドが1、プールされたスレッドの数が15ということになります。

my.cnf(my.ini)の設定

プラグインをインストールする前に設定してもエラーにならないように、各項目の先頭にloose-をつけることを推奨します。

transactd_address = 0.0.0.0 TCPサーバーが待ち受けるアドレス。(デフォルトは0.0.0.0)
IP v4とv6の両方に対応。0::0はIP v4とv6のすべてのアドレスを許可します。
transactd_port = 8610 TCPサーバーが使用するポート番号。(デフォルトは 8610)
transactd_table_name_lowercase = 1 0または1を指定します。(デフォルトは 1)
1の場合、テーブル作成時にテーブル名として小文字を使用します。
transactd_auth_type = "" クライアントの認証方法を指定します。
"host_auth"もしくは未指定(デフォルト) : ホスト認証
"mysql_native" : ユーザーとホストの組み合わせ認証
transactd_hostcheck_username = "root" ホスト認証の場合にアクセス可能ホストの設定に使用するユーザー名。(デフォルトは root)
transactd_tcp_server_type = 1 0 : TCPサーバーを使用しない
1 : Connection per thread (cpt) サーバーを使用する(デフォルト)
2 : Thread pool (tpool) サーバーを使用する。現状では、読み取りのみで使用してください。
transactd_max_tcp_connections = 200 1 ~ 3000 (デフォルトは 200)
同時に接続可能なTCPコネクションの数。transactd_tcp_server_typeが1の場合のみ有効。
transactd_pool_threads = 15 1 ~ 1000 (デフォルトは 15)
transactd_tcp_server_typeが2の場合のみ有効。
transactd_use_piped_local = 1 0 : ローカルpipeサーバーを使用しない。
1 : ローカルpipeサーバーを使用する。(デフォルト)
Windowsの場合のみ有効。
transactd_max_pipe_connections = 10 1 ~ 100
同時に接続可能なローカルpipeコネクションの数。Windowsの場合のみ有効。
transactd_pipe_comm_sharemem_size = 3145728 66000 ~ 52428800 (50MB) (デフォルトは 3145728 = 3MB)
ローカルpipeサーバー用のバッファサイズ。 巨大なBLOBやTEXTにアクセスする場合は、このサイズを大きくしておく必要があります。
transactd_use_btrv_variable_table = 1 0 or 1 (default 1)
Btrieve互換の可変長テーブルを使用するかどうかを指定します。 可変長テーブルは最後のフィールドがVARBINARYでVARタイプフィールドが1つだけでかつBLOB TEXTを含まないテーブルの場合にのみ有効になります。有効の場合、最後のVARBINARYフィールドはSQLからは正しく扱えません。
transactd_use_handlersocket = 1[3] 0 : TransactdでHandlerSocketプロトコルを使用しない。(デフォルト)
1 : TransactdでHandlerSocketプロトコルを使用する。
transactd_hs_port = 9999[3] TransactdでHandlerSocketプロトコルを使用する際のポート番号。(デフォルトは 9999)
transactd_lock_wait_timeout = 1 Transactd用の lock_wait_timeout。(デフォルトは 1秒。指定可能範囲は1 ~ 3600)
transactd_transaction_isolation = "READ-COMMITTED" Transactd用の transaction_isolation。(デフォルトは "READ-COMMITTED")
transactd_timestamp_always = 1

TIMESTAMP型またはDATETIME型のDEFAULT CURRENT_TIMESTAMPまたはON UPDATE CURRENT_TIMESTAMPが設定されたフィールドで、挿入や更新の前に自動でフィールドの値をNULL値(ゼロ)にするかどうかを指定します。(デフォルトは1)

  • 1を指定すると、挿入や更新の前にフィールドの値を自動でNULL値(ゼロ)にします。そのため、必ず挿入時や更新時のタイムスタンプが記録されます。
  • 0を指定すると、フィールドの値は自動ではNULL値(ゼロ)にされません。以前の値を保持するか、NULL値(ゼロ)にすることで挿入時や更新時のタイムスタンプを記録するかを、プログラムで明示的に処理する必要があります。
  • transactd_timestamp_alwaysの設定値に関わらず、NULLを許可するフィールドの値にNULL(無効値)を指定すると、そのフィールドの値はNULL(無効値)となり、以前の値も挿入時や更新時のタイムスタンプも記録されません。
transactd_startup_ha = 4

サーバー起動時のTransactd High Availability (THA)の設定値を指定します。設定値は以下の値の合計値で指定します。

  • 0 このサーバーはスレーブロール
  • 1 このサーバーはマスターロール
  • 2 ロールは未指定
  • 4 再起動時に前回のロールを復元する
  • 8 THA自動フェイルオーバーが有効

[3] USE_HANDLERSOCKETマクロを有効にしてPluginをビルドした場合にのみ有効です。

コマンドラインのMySQLクライアントからshow variablesコマンドを使って上記の設定を確認できます。

mysql> show variables like 'transactd_use_piped_local';
+----------------------------+-------+
| Variable_name              | Value |
+----------------------------+-------+
| transactd_use_piped_local  | 1     |
+----------------------------+-------+

文字コードの設定

Transactd プラグインで文字コードを正しく扱うための設定について、 Transactd での文字コードおよび SDKドキュメント - 関連ページ - API概要 - 詳細 - 文字コード の項目 を参照してください。

データタイプ

Transactd プラグインで使用可能なデータタイプについて、SDKドキュメント - 関連ページ - API概要 - 詳細 - データタイプ の項目およびSDKドキュメント - 関連ページ - データタイプ対応表を参照してください。

仕様および制限事項

フィールド名

$nfで始まるフィールド名は内部で使用される特殊なフィールドのために予約されています。

FULLTEXTインデックス

FULLTEXTインデックスでのアクセスはサポートされていません。

キーセグメント

マルチカラムのキー(マルチセグメントキー)のカラム数はインデックスごとに最大で8カラムまでです。これはTtransactdのスキーマによる制限です。

NUMERIC

Numericタイプは十分なテストが行われていません。

言語サポート

そのほかの言語はテストされていません。

ハードウェアのCPU

サポートされるCPUはリトルエンディアンのみです。ビッグエンディアンのCPUはサポートされません。また、現在のところサポート予定はありません。

VIEW

Viewの表示、作成はサポートされません。

キャラクターセット (文字コード)

Transacdのサーバー側では、保存時、読み取り時のいずれも文字コードのチェック、文字コードの変換は行われません。それらが正しいかどうかを保証するのはクライアントの責任になります。

Transactd プラグインで文字コードを正しく扱うための設定について、SDKドキュメント - 関連ページ - API概要 - 詳細 - 文字コード の項目を参照してください。

Btrieve APIとの互換性

ここではPSQLデータベースとTransactd + MySQLデータベースの互換性について説明します。

ファイルスペックとフラグ

オペレーション

オーナーネーム

フィールドタイプのマッピング

Btrieve APIのレコードイメージをそのまま構造体などに割り当てているアプリケーションで、SQLでのアクセスも可能にしたい場合はフィールドをSQLからアクセスできる型でマップすることになります。 このような場合、テーブル作成時にいくつかの対策が必要になります。

キーフラグ

ヌルキー

MySQLはヌルキーをサポートしませんが、Transactdはそれをエミュレートし利用可能にしています。

BtrieveテーブルをMySQLにマイグレーションすると、ヌルキー(任意セグメントヌルキーも含む)のキーごとに1バイトの”$nf”で始まる名前のNull Indicator Fieldを自動で追加します。SQLでアクセスするとこのフィールドが見えますが、Btrieve APIではこのフィールドはレコードイメージから 取り除かれて返されます。NIFフィールドはレコードイメージの最後に追加されます。

このエミュレーションはうまく動作しますが、seekPrevオペレーションでは、非ヌル値からヌル値を含むレコードに向かってカレントが移動していきます。 この場合、非ヌル値へもそのまま移動できてしまいます。そのようなオペレーションについては読み取ったレコードがヌルキーでないか確認するコードが必要です。 また、ヌル値を含むレコードへのアクセスは唯一この方法によります。

ヌル値の指定

ヌルキーにおいて、ヌル値の指定はできません。値の場合はゼロ、文字列の場合は長さゼロをヌルとして扱います。 ヌルキーにおいてヌル値が指定されていた場合は、そのフィールドをNOT NULLフィールドとしてテーブルを作成します。

ヌル値の指定の多くは、任意セグメントヌルキーにて、そのフィールドはゼロを常用するけれどもインデックスには含めたいという場合に、通常使われない値をヌル値として指定します。このような場合はNOT NULLフィールドとすることで目的を達成できます。もし、そのような目的でない場合は、もう一つフィールドを追加して、そのフィールドをゼロにするか否かで制御する必要があります。

その他

フィールドタイプによって処理を変えるようなメタプログラミングを行っていて、新しいMySQLの型を使用する場合は、それらに対応する処理をアプリケーションに追加する必要があります。