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
配置先のパスは以下の通りです。
- Windows :
c:\windows\transactd.ini
- Linux :
/etc/transactd.cnf
ローカル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)の設定値です。以下の値の合計値が取得できます。
|
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型の
|
transactd_startup_ha = 4 | サーバー起動時のTransactd High Availability (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タイプは十分なテストが行われていません。
言語サポート
- スキーマ(データベース名、テーブル名、フィールド名)としてテストされている言語は、latin1 cp932 utfmb4の3つです。
- フィールドの値としてテストされている言語は、latin1 cp932 utfmb4 utf16leの4つです。
そのほかの言語はテストされていません。
ハードウェアのCPU
サポートされるCPUはリトルエンディアンのみです。ビッグエンディアンのCPUはサポートされません。また、現在のところサポート予定はありません。
VIEW
Viewの表示、作成はサポートされません。
キャラクターセット (文字コード)
Transacdのサーバー側では、保存時、読み取り時のいずれも文字コードのチェック、文字コードの変換は行われません。それらが正しいかどうかを保証するのはクライアントの責任になります。
Transactd プラグインで文字コードを正しく扱うための設定について、SDKドキュメント - 関連ページ - API概要 - 詳細 - 文字コード の項目を参照してください。
Btrieve APIとの互換性
ここではPSQLデータベースとTransactd + MySQLデータベースの互換性について説明します。
ファイルスペックとフラグ
- ページサイズは指定できません。指定した値は無視されます。
- プリアロケーションは指定できません。指定した値は無視されます。
- データ圧縮は指定できません。指定した値は無視されます。
- キーオンリーファイルは作成できません。
- インデックスバランス、フリースペース割合、デュプリケートポインタ、VATの使用は指定できません。指定した値は無視されます。
オペレーション
- Statオペレーションでは、ファイルスペックのレコード長とレコード数のみが返されそれ以外の値は返されません。
- GetChunk(23) Update Chunk(53)はサポートされていません。
- Version(26)はTransactdとMySQLのバージョンを返します。
- Lock(26) Unlock(27)は自動で行われるため明示的に指定できません。これらのオペレーションは無視されます。
- Continuousオペレーションはサポートされていません。
- GetDirectory SetDirectoryはサポートされません。
- ユニークなキーがない場合、StepLastと StepPrevは利用できません。そのような状況で呼び出された場合、41 STATUS_NOSUPPORT_OPが返されます。
オーナーネーム
- オーナーネームの書き込みスペースとしてテーブルのcommentを利用します。ユーザーに容易にオーナーネーム の値を知られないようにし、本来の役割を持たせるにはinformation_schema.tablesのtable_commentフィールドへの読み取りアクセスを制限する必要があります。
フィールドタイプのマッピング
Btrieve APIのレコードイメージをそのまま構造体などに割り当てているアプリケーションで、SQLでのアクセスも可能にしたい場合はフィールドをSQLからアクセスできる型でマップすることになります。 このような場合、テーブル作成時にいくつかの対策が必要になります。
- 文字列型 : binary型とすることで互換性を保つことができます。
- 日付型 : MySQLの日付型はPSQLの日付型とバイナリ互換性がないため、Integer型とすることで互換性のあるイメージにできます。 しかし、日付から数値に変換してSQL文を作成し、結果として得られた数値を日付に変換する必要があります。
キーフラグ
- すべてのキー値は変更可能キーであり、変更不可にはなりません。
- オルタネートコレーディングシーケンス(ACS)はサポートされません。
- 繰り返し重複キータイプはその概念がありません。
ヌルキー
MySQLはヌルキーをサポートしませんが、Transactdはそれをエミュレートし利用可能にしています。
BtrieveテーブルをMySQLにマイグレーションすると、ヌルキー(任意セグメントヌルキーも含む)のキーごとに1バイトの”$nf”で始まる名前のNull Indicator Fieldを自動で追加します。SQLでアクセスするとこのフィールドが見えますが、Btrieve APIではこのフィールドはレコードイメージから 取り除かれて返されます。NIFフィールドはレコードイメージの最後に追加されます。
このエミュレーションはうまく動作しますが、seekPrevオペレーションでは、非ヌル値からヌル値を含むレコードに向かってカレントが移動していきます。 この場合、非ヌル値へもそのまま移動できてしまいます。そのようなオペレーションについては読み取ったレコードがヌルキーでないか確認するコードが必要です。 また、ヌル値を含むレコードへのアクセスは唯一この方法によります。
ヌル値の指定
ヌルキーにおいて、ヌル値の指定はできません。値の場合はゼロ、文字列の場合は長さゼロをヌルとして扱います。 ヌルキーにおいてヌル値が指定されていた場合は、そのフィールドをNOT NULLフィールドとしてテーブルを作成します。
ヌル値の指定の多くは、任意セグメントヌルキーにて、そのフィールドはゼロを常用するけれどもインデックスには含めたいという場合に、通常使われない値をヌル値として指定します。このような場合はNOT NULLフィールドとすることで目的を達成できます。もし、そのような目的でない場合は、もう一つフィールドを追加して、そのフィールドをゼロにするか否かで制御する必要があります。
その他
フィールドタイプによって処理を変えるようなメタプログラミングを行っていて、新しいMySQLの型を使用する場合は、それらに対応する処理をアプリケーションに追加する必要があります。