初期化用のオプション

pgbenchは以下の初期化用のコマンドライン引数を受け付けます。

ベンチマーク用オプション

pgbenchは以下のベンチマーク用コマンドライン引数を受け付けます。

共通オプション

pgbenchは接続パラメータとして以下の共通コマンドライン引数も受け付けます。

pgbenchで実際に実行される「トランザクション」は何か?

pgbenchは指定したリストからランダムに選択したテストスクリプトを実行します。 これには-bの組み込みスクリプトと-fのユーザ定義カスタムスクリプトが含まれます。 各スクリプトには@の後に指定される相対的な重みを与えることができ、それが選ばれる確率を変更することができます。 デフォルトの重みは1です。 重みが0のスクリプトは無視されます。

デフォルトの組み込みトランザクションスクリプト（-b tpcb-likeとすることでも実行されます）は、aid、tid、bid、deltaからランダムに選択され、トランザクション毎に7つのコマンドを発行します。 このシナリオはTPC-Bベンチマークに示唆を受けたものですが、実際にはTPC-Bではないので、この名前になっています。

simple-updateの組み込みを選択した（あるいは-Nを指定した）場合、第4ステップと第5ステップはトランザクションに含まれません。 これにより、これらのテーブルに対する更新の競合を避けられますが、テストケースはさらにTPC-Bらしくなくなります。

select-onlyの組み込みを選択した（あるいは-Sを指定した）場合、SELECTのみが発行されます。

独自スクリプト

pgbenchは、ファイルから読み込んだトランザクションスクリプト（-fオプション）でデフォルトのトランザクションスクリプト（上述）を置き換えて独自のベンチマークシナリオを実行する機能をサポートします。 この場合、「トランザクション」はスクリプトファイルの1回の実行として数えられます。

スクリプトファイルにはセミコロンで終了するSQLコマンドが1つ以上含まれます。 空行および--から始まる行は無視されます。 スクリプトファイルの行には、pgbench自身が解釈する「メタコマンド」（後述）も記述することができます。

スクリプトファイル向けの簡単な変数置換機能があります。 変数名は文字（非ラテン文字を含む）、数字およびアンダースコアで構成されていなければなりません。 上で説明したように変数を-Dコマンドラインオプションで設定することができます。 また、後で説明するようにメタコマンドで設定することもできます。 -Dコマンドラインオプションで設定された変数の他に、表 273に記載されているように、自動的に設定される変数がいくつかあります。 -D を使ってこれらの変数に設定された値は、自動設定の値より優先されます。 一度設定すると、変数の値は、:variablenameと書かれてSQLコマンドに挿入されます。 1つ以上のクライアントセッションが実行される場合、セッション毎に独自の変数群を持ちます。 pgbenchは1つの文内で255個までの変数の利用をサポートします。

スクリプトファイルのメタコマンドはバックスラッシュ（\）から始まり、通常は行末まで続きますが、バックスラッシュと改行を書くことで、追加の行に続けることができます。 メタコマンドへの引数は空白文字で区切られます。 以下のメタコマンドがサポートされています。

組み込み演算子

表 274に載っている算術、ビットごと、比較、論理の演算子はpgbenchに組み込まれていて、\setの式で使用できます。 演算子は優先度の低い順に載っています。 注意書きがある場合を除いて、2つの数値を取る演算子は、入力の片方が倍精度実数であれば倍精度実数の値を結果とし、そうでなければ整数の結果になります。

組み込み関数

表 275に示す関数はpgbenchに組み込まれており、\setに現れる式の中で使うことができます。

random関数は一様分布を使って値を生成します。 つまり、すべての値は指定された範囲内で同じ確率で発生します。 random_exponential、random_gaussian、および、random_zipfian関数は追加の倍精度実数のパラメータを必要とし、それによって分布の正確な形が決まります。

ハッシュ関数hash、hash_murmur2およびhash_fnv1aは入力値とオプションシードパラメータを受け付けます。 シードが与えられなかった場合、:default_seedの値が使われます。これは、コマンドライン-Dオプションで設定されない限りランダムに初期化されたものです。 ハッシュ関数はrandom_zipfianやrandom_exponentialなどのランダム関数の分布を散らすのに使用できます。 例えば、以下のpgbenchスクリプトは起こりえる現実世界のソーシャルメディアとブログプラットフォームに対する僅かなアカウントしか過大な負荷をかけないという典型的な負荷をシミュレートします。

\set r random_zipfian(0, 100000000, 1.07)
\set k abs(hash(:r)) % 1000000

一部のケースでは、互いに無関係ないくつかの異なる分布が必要で、これは暗黙のシードパラメータが役立ちます。

\set k1 abs(hash(:r, :default_seed + 123)) % 1000000
\set k2 abs(hash(:r, :default_seed + 321)) % 1000000

例えば、組み込みのTPC-Bのようなトランザクションの完全な定義を示します。

\set aid random(1, 100000 * :scale)
\set bid random(1, 1 * :scale)
\set tid random(1, 10 * :scale)
\set delta random(-5000, 5000)
BEGIN;
UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
END;

このスクリプトにより、トランザクションを繰り返す度に異なる、ランダムに選ばれた行を参照することができます。 （この例はまた、各クライアントセッションがなぜ独自の変数を持つことが重要なのかも表しています。 これがないと、異なる行を独立して参照することができないのです。）

トランザクション毎のログ処理

（--aggregate-intervalオプションなしで）-lオプションを使用すると、pgbenchは各トランザクションに関する情報をログファイルに書き出します。 ログファイルの名前はprefix.nnnで、prefixのデフォルトはpgbench_log、nnnはpgbenchプロセスのPIDです。 ファイル名の先頭の文字列は--log-prefixオプションを使って変更することができます。 -jオプションが2以上で複数のワーカスレッドがある場合、それぞれが独自のログファイルを持つことになります。 最初のワーカは標準的な単一ワーカの場合と同じ名前を持つログファイルを使用します。 他のワーカ用の追加のログファイルはprefix.nnn.mmmと命名され、ここでmmmは1から始まる各ワーカの連番です。

ログの書式は以下の通りです。

client_id transaction_no time script_no time_epoch time_us [ schedule_lag ]

client_idはどのクライアントセッションがそのトランザクションを実行したかを示します。 transaction_noはそのセッションで何個のトランザクションが実行されたかを示します。 timeはトランザクションの合計消費時間をマイクロ秒単位で示します。 script_noはどのスクリプトファイルが使用されたかを識別するものです（-fまたは-bで複数のスクリプトが指定された場合に有用です）。 time_epoch/time_usはトランザクション完了時のUnixエポック時間とマイクロ秒単位のオフセットです（小数秒付きのISO 8601タイムスタンプの作成に適します）。 schedule_lagフィールドは、マイクロ秒単位のトランザクションの予定開始時刻と実開始時刻の差です。 これは--rateオプションを使用した時だけ表示されます。 --rateと--latency-limitの両方のオプションを使用した時は、スキップされたトランザクションのtimeがskippedとして表示されます。

単一クライアントでの実行で生成されたログファイルの一部を示します。

0 199 2241 0 1175850568 995598
0 200 2465 0 1175850568 998079
0 201 2513 0 1175850569 608
0 202 2038 0 1175850569 2663

--rate=100と--latency-limit=5を指定した例を示します。(schedule_lag列が追加されていることに注意)

0 81 4621 0 1412881037 912698 3005
0 82 6173 0 1412881037 914578 4304
0 83 skipped 0 1412881037 914578 5217
0 83 skipped 0 1412881037 914578 5099
0 83 4722 0 1412881037 916203 3108
0 84 4142 0 1412881037 918023 2333
0 85 2465 0 1412881037 919759 740

この例では、トランザクション82は遅延(6.173ミリ秒)が5ミリ秒を越えており、遅れています。 次の2つのトランザクションは、開始する前にすでに遅れてしまっているため、スキップされています。

大量のトランザクションを処理することができるハードウェアで長時間試験を実行する場合、ログファイルは非常に大きくなる可能性があります。 --sampling-rateオプションを使用して、トランザクションのランダムなサンプルだけをログに記録することができます。

ログ処理の集約

--aggregate-intervalオプションを付ける場合、以下のようにログの書式が異なります。

interval_start num_transactions​ sum_latency sum_latency_2 min_latency max_latency​ [ sum_lag sum_lag_2 min_lag max_lag [ skipped ] ]

interval_startはインターバルの開始時刻（Unixエポック時間）です。 num_of_transactionsはインターバル内のトランザクション数です。 latency_sumはインターバル内のトランザクションレイテンシの総和です。 sum_latency_2はインターバル内のトランザクションレイテンシの2乗の総和です。 min_latencyはインターバル内の最小レイテンシです。 max_latencyはインターバル内の最大レイテンシです。 これに続くフィールドsum_lag、sum_lag_2、min_lag、max_lagは--rateオプションが指定された場合にのみ表示されます。 これらは、各トランザクションが直前のトランザクションの終了を待機しなければならなかった時間、つまりトランザクションの予定開始時刻と実際の開始時刻の差に関する統計を提供します。 一番最後のフィールドskippedは--latency-limitオプションも使用されたときにのみ表示されます。 これは開始時刻が遅くなったためにスキップされたトランザクションの数を数えます。 各トランザクションはインターバル内でコミットされた時に数えられます。

いくつか出力例を示します。

1345828501 5601 1542744 483552416 61 2573
1345828503 7884 1979812 565806736 60 1479
1345828505 7208 1979422 567277552 59 1391
1345828507 7685 1980268 569784714 60 1398
1345828509 7073 1979779 573489941 236 1411

通常の（集約されていない）ログファイルは、各トランザクションについてどのスクリプトファイルが使用されたかを示しますが、集約されたログにはそれがないことに注意してください。 このためスクリプト単位のデータが必要な場合は、自身でデータを集約する必要があります。

ステートメント毎のレイテンシ

-rオプションを付けると、pgbenchは各クライアントにより実行されたトランザクションのステートメント毎の経過時間を収集します。 ベンチマークが終了した後、各値の平均値(各ステートメントのレイテンシと呼びます)が報告されます。

標準スクリプトでは、次のような出力になります。

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 1
query mode: simple
number of clients: 10
number of threads: 1
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
latency average = 15.844 ms
latency stddev = 2.715 ms
tps = 618.764555 (including connections establishing)
tps = 622.977698 (excluding connections establishing)
statement latencies in milliseconds:
        0.002  \set aid random(1, 100000 * :scale)
        0.005  \set bid random(1, 1 * :scale)
        0.002  \set tid random(1, 10 * :scale)
        0.001  \set delta random(-5000, 5000)
        0.326  BEGIN;
        0.603  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
        0.454  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
        5.528  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
        7.335  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
        0.371  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
        1.212  END;

複数のスクリプトファイルが定義された場合、平均値はそれぞれのスクリプトファイル毎に分けて報告されます。

ステートメント毎のレイテンシを計算するために必要となる、追加のタイミング情報を収集することは、オーバーヘッドが加わることに注意してください。 これは平均実行速度を遅くし、計測TPSを小さくするでしょう。 低下量はプラットフォームとハードウェアに依存して著しく変わります。 レイテンシの報告を有効にする、有効にしないで平均TPS値を比較することは、タイミング・オーバーヘッドが顕著かどうかを測定するには良い方法です。

優れた実践

まったく無意味な数値を生み出すようにpgbenchを使用することは非常に簡単です。 以下に有意な結果を生み出す手助けとなるガイドラインをいくつか示します。

まず第一に、数秒で終わる試験を決して信用しないでください。 -tまたは-Tオプションを使って、雑音を取り除くために、少なくとも数分試験にかかるようにしてください。 再現可能な数値を得るために数時間必要になる場合もあります。 数回試験を繰り返し、数値が再現できるかどうか確認することを勧めます。

デフォルトのTPC-Bのような試験シナリオでは、初期倍率（-s）を試験予定のクライアント数（-c）の最大値と同程度にしなければなりません。 pgbench_branchesテーブルには-s行しかありません。 また、全トランザクションはその内の1つを更新しようとします。 ですので、-c値を-sより大きくすると、他のトランザクションを待機するためにブロックされるトランザクションが多くなることは間違いありません。

デフォルトの試験シナリオはまた、テーブルを初期化してからの経過時間に非常に敏感です。 テーブル内の不要行や不要空間の累積により結果が変わります。 結果を理解するためには、更新された行数とバキューム時期を把握する必要があります。 自動バキュームが有効な場合、性能を測定する上で結果は予測できないほど変わる可能性があります。

pgbenchの制限は、多くのクライアントセッションを試験しようとする際にpgbench自身がボトルネックになる可能性があることです。 これは、データベースサーバとは別のマシンでpgbenchを実行することで緩和させることが可能です。 しかし、多少のネットワーク遅延が重要です。 同一データベースサーバに対し複数のクライアントマシンから複数のpgbenchインスタンスを同時に実行することが有用かもしれません。

セキュリティ

安全なスキーマの利用パターンを適用していないデータベースに信頼できないユーザがアクセス可能な場合、そのデータベースでpgbenchを実行しないでください。 pgbenchは修飾していない名前を使っており、またサーチパスを操作していません。