pgbench README		2005/09/29 Tatsuo Ishii

■pgbench とは？

pgbench はベンチマークテストを行なうプログラムです．今のところ 
PostgreSQL 専用です．

pgbench は select/update/insert を含むトランザクションを実行し，全体の
実行時間と実際に完了したトランザクションの数から 1 秒間に実行できたト
ランザクション数 (tps) を表示します．処理の対象となるテーブルはデフォ
ルトでは 10万タプルのデータを含みます．

実際の表示は以下のような感じです．

number of clients: 4
number of transactions per client: 100
number of processed transactions: 400/400
tps = 19.875015(including connections establishing)
tps = 20.098827(excluding connections establishing)

pgbench は JDBCBench という，もともとは MySQL 用に書かれた JDBC 用のベ
ンチマークプログラムを参考に作成されました．

■pgbench の特徴

o C 言語と libpq だけで書かれているので移植性が高く，簡単にインストー
ルできます．

o pgbench は libpq の非同期処理機能を使ってマルチユーザ環境をシミュレー
トします．容易に同時接続環境をテストできます．

■pgbench のインストール

PostgreSQLをコンパイル，インストールした後

$ make
$ make install

とします．

■pgbench の使い方

$ pgbench [データベース名]

です．データベース名を省略すると，ユーザ名と同じデータベースを指定した
ものとみなします．データベースは後述の -i オプションを使ってあらかじめ
初期化しておく必要があります．

pgbench にはいろいろなオプションがあります．

-h ホスト名	PostgreSQLのデータベースデーモン postmaster の動
		いているホスト名を指定します．省略すると自ホストに Unix domain
		socket で接続します．

-p ポート番号	postmaster の使用するポート番号を指定します．省略すると 5432
		が指定されたものとみなします．

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

-t トランザクション数	各クライアントが実行するトランザクション数を
			指定します．省略時は 10 となります．

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

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

-U login	DBユーザのログイン名を指定します．

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

-n		このオプションを指定すると，ベンチマーク開始前に vacuum と
		history のクリアを行ないません．

-v              このオプションを指定すると，デフォルトの事前クリーンアッ
                プ処理に加え，accountsをVACUUM ANALYZEします．

		-v -n の両方を省略した場合のデフォルト事前クリーンアッ
                プ処理は，以下の処理を行います．

		- historyからの全行削除
		- branches, tellers, historyのVACUUM

		これは，vacuum の時間を最小限にしながら，パフォーマンスに
		影響するゴミ掃除を効果的に行います．通常は -v と -n を
		省略することをおすすめします．

-S		TPC-Bのトランザクションではなく，検索のみのトランザクションを
		実行します．検索スピードを測定したいときに使います．

-N
		"branches"と"tellers"テーブルの更新を行いません．これ
		によって"branches"と"tellers"への大量の更新の競合のな
		い状態での測定を行います．したがってTPC-Bのスペックに
		は適合しなくなりますが，より現実的な負荷をテストするこ
		とができます．

-f filename	トランザクションの内容が記述されたファイル名を指定しま
		す．このオプションを指定すると，ファイルに記述された内
		容のトランザクションを実行します．なお，ベンチマークの
		対象となるデータベースはあらかじめ初期化しておく必要が
		あります．入力フォーマットについては後述します．

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

-l		個々のトランザクションの実行時間を記録します．記録先は
		カレントディレクトリ以下のpgbench_log.xxxというファイ
		ルです．ファイルのフォーマットは，
		
			クライアントID	トランザクション番号  時間

		となっています．時間はマイクロ秒単位です．

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

■データベースの初期化

pgbench でベンチマークテストを実施するためには，あらかじめデータベース
を初期化し，テストデータを作る必要があります．

$ pgbench -i [データベース名]

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

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

テーブル名	タプル数
-------------------------
branches	1
tellers		10
accounts	100000
history		0

スケーリングファクターを 10,100,1000 などに変更すると，上記タプル数は
それに応じて10倍，100倍，1000倍になります．たとえば，スケーリングファ
クターを 10 とすると，

テーブル名	タプル数
-------------------------
branches	10
tellers		100
accounts	1000000
history		0

になります．

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

pgbench では，以下のシーケンスを全部完了して1トランザクションと数えて
います．

(1) begin;

(2) update accounts set abalance = abalance + :delta where aid = :aid;
    ここで，:deltaは1から1000までの値を取る乱数，:aid は 1から100000まで
    の値を取る乱数です．以下，乱数の値はそれぞれこのトランザクションの
    中では同じ値を使います．

(3) select abalance from accounts where aid = :aid;
    ここでは1件だけ検索されます．

(4) update tellers set tbalance = tbalance + :delta where tid = :tid;
    ここで :tid は 1から10の間の値をとる乱数です．

(5) update branches set bbalance = bbalance + :delta where bid = :bid;
    ここで :bid は 1 から[スケリングファクター]の間の値を取る乱数です．

(6) insert into history(tid,bid,aid,delta) values(:tid,:bid,:aid,:delta);

(7) end;

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

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

-f オプションは複数指定できます．この場合は各トランザクションにはラン
ダムに選ばれたファイルに記述されたSQLが実行されます．

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

現在のところ，以下のメタコマンドが定義されています．

\setrandom name min max
	最小値 min と最大値 max の間の値を取る乱数を，name 変数に設定
	します．

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

\setrandom aid 1 100000

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

SELECT abalance FROM accounts WHERE aid = :aid

例えば，TCP-B に類似したベンチマークを計測するには，以下のようにトラン
ザクションの内容をファイルに記述し，-f オプションによってそのファイル
を指定して pgbench を実行します．

\setrandom aid 1 100000
\setrandom bid 1 1
\setrandom tid 1 10
\setrandom delta 1 10000
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')
END

■作者とライセンス条件

pgbench は石井 達夫によって書かれました．ライセンス条件は pgbench.c の
冒頭に書いてあります．この条件を守る限り無償で利用し，また自由に再配付
できます．

■改定履歴

2005/09/29
	* 佐藤さんのパッチを適用．-f オプションの追加．

[この間いろいろ変更があったようだがREADMEはメインテナンスされていない]

2003/11/26
	* 谷田さんのパッチを適用．pgbench -iの際に，後から主キーを作成
	  するようにした．これによって初期化の実行時間が大幅に短縮でき
	  る(はず)．

2003/06/10
	* メモリが初期化されていないバグを修正
	* 環境変数PGHOST, PGPORT, PGUSERを認識するようにした．

2002/07/20
	* Nei Conwayさんのパッチを適用．
	* -l オプションの追加．

2002/02/24
	* ここからは7.3用の変更です．
	* CHECKPOINTの発行をやめました．
	* -N オプションを追加しました．

2001/10/24
	* PostgreSQL 7.2で，"time"が予約語になったので，"mtime"に変更
	した．

2001/09/09
	* PostgreSQL 7.2用に，-U, -P, -C オプションを追加しました．

2000/1/15 pgbench-1.2 は PostgreSQL に contribute されました．
	* -v オプション追加

1999/09/29 pgbench-1.1 リリース
	* 谷田さんによるcygwin対応パッチ取り込み
	* バックエンドクラッシュ時の対応
	* -S オプション追加

1999/09/04 pgbench-1.0 リリース
