$Id: README,v 1.2 2005/08/02 01:24:53 tom-sato Exp $

■ pgcbench とは

pgcbench は PGCluster のベンチマークテストを行うプログラムです。もちろ
ん、PGCluster だけではなく PostgreSQL のベンチマークを実施することもで
きます。

pgcbench は SELECT、UPDATE、INSERT を含むトランザクションを実行し、全
体の実行時間と実際に完了したであろうトランザクションの数から 1 秒間に
実行できたトランザクション数 (tps) を表示します。処理の対象となるテー
ブルはデフォルトでは 10 万行のデータを含みます。

実際に表示は以下のようになります。

   number of clients: 4
   number of transactions actually processed: 100
   run time (sec) = 4.416423 
   tps = 22.642759 (including connections establishing)

※ 注意

   pgcbench では、トランザクションが実際に完了したかどうかに関係なく、
   最初に指定されたトランザクションの数をもとに tps を求めているため、
   ベンチマークが途中で終了してしまった場合、表示される tps が信用でき
   ない可能性があることに注意してください。

なお、pgcbench は pgbench という PostgreSQL 用に書かれたベンチマークテ
ストを行なうプログラムをもとに作成されました。


■ pgbench との違い

・ マルチユーザ環境の実現方法

   pgbench が libpq の非同期処理機能を使ったシングルプロセスによってシ
   ミュレートしているのに対して、pgcbench では fork を使ったマルチプロ
   セスによって実現しています。これは、シングルプロセスではロックが発
   生すると、PGCluster が止まってしまうことを避けるためです。

・ オプションの変更

   pgcbench には、PGCluster のベンチマークテストを行なうのに便利な、ト
   ランザクションの内容を指定するオプションが、いくつか追加されていま
   す．


■ pgcbench のインストール

1. PGCluster を configure、make します。

   pgcbench のインストールだけが目的であれば、PGCluster のすべてをコン
   パイルする必要はありません。PGCluster ソースのトップディレクトリで 
   configure をした後、src/interface/libpq で make all を実行すれば準
   備完了です。

2. このディレクトリ (src/pgcluster/tool) で make を実行します。

   そうすると、pgcbench という実行プログラムができます。そのまま実行し
   ても構いませんし、make install を実行して PGCluster の標準実行プロ
   グラムディレクトリ (デフォルトでは /usr/local/pgsql/bin) にインストー
   ルすることもできます。


■ pgcbench の使い方

   pgcbench [オプション] [データベース名]

データベース名を省略すると、ログイン名と同じデータベース名を指定したも
のと見なします。なお、pgcbench でデフォルトのベンチマークを実施するた
めには、後述の -i オプションを使用してデータベースをあらかじめ初期化し
ておく必要があります。

pgcbench にはいろいろなオプションがあります。

-h ホスト名

   PostgreSQLの データベースデーモン postmaster の動作しているホスト名
   を指定します。省略すると環境変数 PGHOST に設定したホスト名が指定さ
   れます。PGHOST も指定されていないと自ホストに Unix ドメインソケット
   で接続します。

-p ポート番号

   postmaster の使用するポート番号を指定します。省略すると環境変数
   PGPORT に設定したポート番号が指定されます。PGPORT も指定されていな
   いと 5432 が指定されたものと見なします。

-c クライアント数

   同時実行クライアント数を指定します。省略時は 1 となります。pgcbench 
   は同時実行クライアントごとにファイルディスクリプタを使用するので、
   使用可能ファイルディスクリプタ数を越えるクライアント数は指定できま
   せん。使用可能ファイルディスクリプタ数は limit や ulimit コマンドで
   確認することができます。

-t トランザクション数

   トランザクション数を指定します。各クライアントが実行するトランザク
   ション数はこれをクライアント数で割った数となります。省略時は 10 と
   なります。

-s スケーリングファクター

   -i オプションとともに使用します。スケーリングファクターは 1 以上の
   整数です。スケーリングファクターを変えることにより、テストの対象と
   なるテーブルの大きさが 10 万 × スケーリングファクターになります。
   デフォルトのスケーリングファクターは 1 です。

-u ログイン名

   DB ユーザのログイン名を指定します。省略すると環境変数 PGUSER に設定
   したログイン名が指定されます。

-P パスワード

   パスワードを指定します。なお、このオプションを使うと、パスワードを
   ps コマンドで見られるなど、セキュリティホールになる可能性があるので、
   テスト用にのみお使い下さい。

-n

   このオプションを指定すると、ベンチマーク開始前に VACUUM と history
   テーブルのクリアを実行しません。

-v

   このオプションを指定すると、ベンチマーク開始前に VACUUM と history
   テーブルのクリアを実行します。-v と -n を省略すると、最小限の
   VACUUM などを実行します。すなわち、history テーブルのクリアと、
   branches、tellers、history テーブルの VACUUM を実行します。これは、
   VACUUM の時間を最小限にしながら、パフォーマンスに影響するゴミ掃除を
   効果的に実行します。通常は -v と -n を省略することを推奨します。

-I

   挿入のみのトランザクションを実行します。挿入スピードを測定したいと
   きに使います。

-U

   更新のみのトランザクションを実行します。更新スピードを測定したいと
   きに使います。

-S

   検索のみのトランザクションを実行します。検索スピードを測定したいと
   きに使います。

-f ファイル名

   トランザクションの内容が記述されたファイル名を指定します。このオプ
   ションを指定すると、ファイルに記述された内容のトランザクションを実
   行します。ベンチマークで使用するテーブルはあらかじめ初期化しておく
   必要があります。入力ファイルのフォーマットは後述します。

-T

   BEGIN と END で囲まれたトランザクションブロック内でトランザクション
   を実行します。

-C

   このオプションを指定すると、最初に確立したコネクションを使い回すの
   ではなく、各トランザクションごとに DB への接続を行います。コネクショ
   ンのオーバーへッドを測定するのに有効です。

-l

   個々のトランザクションの実行時間を記録します。記録先はカレントディ
   レクトリ以下の pgbench_log.xxx というファイルです。ファイルのフォー
   マットは以下のようになります。時間はマイクロ秒単位です。

      <クライアント ID> <トランザクション番号> <時間>

-d

   デバッグオプション。様々な情報が表示されます。


■ データベースの初期化

pgcbench でデフォルトのベンチマークテストを実施するためには、あらかじ
めデータベースを初期化し、テストデータを作る必要があります。

   pgcbench -i [データベース名]

これにより以下のテーブルが作成されます (スケーリングファクターが 1 の
場合)。

    テーブル名 |  行数
   ------------+--------
    branches   |      1
    tellers    |     10
    accounts   | 100000
    history    |      0

※ 注意

   同じ名前のテーブルがあると削除されてしまうのでご注意下さい。

スケーリングファクターを 10、100、1000 などに変更すると、上記行数はそ
れに応じて 10 倍、100 倍、1000 倍になります。例えば、スケーリングファ
クターを 100 とすると以下のようになります。

    テーブル名 |   行数
   ------------+----------
    branches   |      100
    tellers    |     1000
    accounts   | 10000000
    history    |        0


■ 入力ファイルのフォーマット

pgcbench では、-f オプションを指定してトランザクションに含まれる SQL 
コマンドの内容を記述したファイルを読み込むことができます。入力ファイル
には 1 行につき 1 つのコマンドを記述します。空行は無視され、二重ハイフ
ンで始まる行はコメントを意味します。

コマンドには、SQL コマンドに加え、バックスラッシュで始まるメタコマンド
を記述することができます。メタコマンドは pgcbench 自身によって実行され
ます。メタコマンドの形式はバックスラッシュ、その直後にコマンドの動詞、
その次に引数が続きます。動詞コマンドと引数、またそれぞれの引数は空白文
字によって区別されます。

今のところ、以下のメタコマンドが定義されています。

\setrandom name min max

   最小値 min と最大値 max の間の値を取る乱数を、name 変数に設定します。

変数に乱数を設定するには、\setrandom メタコマンドを使用して以下のよう
に記述します。

   \setrandom aid 1 100000

これは、変数 aid に 1 から 100000 の間の乱数を設定します。また、変数の
値を SQL コマンドに埋め込むには、以下のようにその名前の前にコロンを付
けます。

  SELECT abalance FROM accounts WHERE aid = :aid

例えば、TPC-B に似たベンチマークを行うには、以下のようにトランザクショ
ンの内容をファイルに記述し、-f オプションによってそのファイルを指定し
て pgcbench を実行します。

   \setrandom aid 1 100000
   \setrandom bid 1 1
   \setrandom tid 1 10
   \setrandom delta 1 1000
   BEGIN
   UPDATE accounts SET abalance = abalance + :delta WHERE aid = :aid
   SELECT abalance FROM accounts WHERE aid = :aid
   UPDATE tellers SET tbalance = tbalance + :delta WHERE tid = :tid
   UPDATE branches SET bbalance = bbalance + :delta WHERE bid = :bid
   INSERT INTO history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, 'now')

なお、この例では、-i オプションを使って初期化したデータベース (スケー
リングファクターが 1 の場合) に対してベンチマークを行うことを仮定して
います。


■ トランザクションの定義

pgcbench のデフォルトのベンチマークでは、以下の SQL コマンドを全部完了
して 1 トランザクションと数えています。

1. SELECT abalance FROM accounts WHERE aid = :aid

   :aid は 1 からスケーリングファクター × 10 万までの値を取る乱数です。
   ここでは 1 件だけ検索されます。以下、乱数の値はそれぞれこのトランザ
   クションの中では同じ値を使います。

2. UPDATE accounts SET abalance = abalance + :delta WHERE aid = :aid

   :delta は 1 から 1000 までの値を取る乱数です。

3. SELECT abalance FROM accounts WHERE aid = :aid

4. INSERT INTO history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, 'now')

   :tid は 1 からスケーリングファクター × 10 までの値を取る乱数、:bid
   は 1 からスケーリングファクターまでの値を取る乱数です。

5. INSERT INTO history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, 'now')

6. INSERT INTO history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, 'now')

7. SELECT abalance FROM accounts WHERE aid = :aid

-T オプションを指定してトランザクションブロック内でトランザクションを
実行する場合、1 を BEGINに、7 を END に置き換えた SQL コマンドが実行さ
れます。また、トランザクションとして実行される SQL コマンドは、-I オプ
ション (挿入のみ) であれば 4、-U (更新のみ) であれば 2、-S (検索のみ)
であれば 1 となります。
