pgbench README		2003/11/26 Tatsuo Ishii (t-ishii@sra.co.jp)

■pgbench とは？

pgbench は TPC-Bに似たベンチマークテストを行なうプログラムです．今のと
ころ 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 のインストール

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

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

■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		このオプションを指定すると，ベンチマーク開始前に vacuum と
		history のクリアを行ないます．-v と -n を省略すると，
		最小限の vacuum などを行います．すなわち，history の削除，
		と history, branches, history の vacuum を行います．
		これは，vacuum の時間を最小限にしながら，パフォーマンスに
		影響するゴミ掃除を効果的に行います．通常は -v と -n を
		省略することをおすすめします．

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

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

-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;

■作者とライセンス条件

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

■改定履歴

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 リリース
