pgbench README		2006/10/21 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 オプションを使ってあらかじめ
初期化しておくことができます．-fオプションを使って独自のトランザクショ
ンを定義する場合は，自分でデータベースの初期化をしておく必要があります．

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

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

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

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

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

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

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

-D varname=value

		変数を定義します．定義した変数は -f オプションで指定したファイ
		ルから参照できます．-D オプションでは変数名と値を = (イコール)
		で区切って指定します．-D オプションは複数指定できます．

-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 でベンチマークテストを実施するためには，あらかじめデータベース
を初期化し，テストデータを作る必要があります．-fオプションを使って独自
のトランザクションを定義する場合は，自分でデータベースの初期化をしてお
く必要があります．

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

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

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

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

スケーリングファクターを 10,100,1000 などに変更すると，上記タプル数は
それに応じて10倍，100倍，1000倍になります．テーブルとインデックスのサ
イズはデータベースサイズは概ねそれぞれ，130MB，1.3GB，13GBほどになりま
す．

たとえば，スケーリングファクターを 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 自身によって実行されます．メタ
コマンドの形式はバックスラッシュ，その直後にコマンドの動詞，その次に引
数が続きます．動詞コマンドと引数，またそれぞれの引数は空白文字によって
区切られます．

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

\set name operand1 [ operator operand2 ]
	被演算数 operand1 と operand2 を演算子 operator によって演算し
	た結果を変数 name に設定します．現状では整数の四則演算のみに対
	応しています．なお，演算子と 2 つ目の被演算数を省略すると単純
	に 1 つ目の被演算数を変数に設定します．

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

	\set ntellers 10 * :tp

	これは，変数 ntellers にスケーリングファクター (-s オプション
	で指定した) を 10 倍した結果を設定します．

\setrandom name min max

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

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

	\setrandom aid 1 100000

	これは，変数 aid に 1 から 100000 の間の乱数を設定します．

変数は SQL コマンドおよびメタコマンドから参照できます．それには以下の
ように変数名の前にコロンを付けます．

SELECT abalance FROM accounts WHERE aid = :aid

変数を定義するにはメタコマンド以外に -D オプションを使用することもでき
ます． -D オプションで定義した変数も変数名の前にコロンを付けて参照しま
す．

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

\set nbranches :scale
\set ntellers 10 * :scale
\set naccounts 100000 * :scale
\setrandom aid 1 :naccounts
\setrandom bid 1 :nbranches
\setrandom tid 1 :ntellers
\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, current_timestamp)
END

スケーリングファクターを branches テーブルのタプル数から自動的に設定し
たい場合，以下のように -s オプションとシェルのコマンド置換などを組み合
わせます．

pgbench -s $(psql -At -c "SELECT count(*) FROM branches") -f tpc_b.sql

なお，-f オプションを指定した場合，ベンチマーク開始前に vacuum と
history のクリアは自動的に行われません．

■作者とライセンス条件

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

■改定履歴

2006/10/21
	* 更にデフォルトのスケーリングファクタをbranchesから取ってこな
          いバグを修正．

2006/09/13
	* 変数tpsは紛らわしいのでscaleに変更．デフォルトシナリオの時に，
	  デフォルトのスケーリングファクタをbranchesから取ってこないバグを修正．

2006/07/26
	* 佐藤さんのパッチを適用．以下の機能追加．PostgreSQL 8.2に取り
	込まれます．

	変数 tps
	    -s オプションで指定したスケーリングファクターをファイル内で変数とし
	   て参照する機能
        -D オプション
	   コマンドのオプションとして定義した変数をファイル内から参照する機能
	\set コマンド
	   ファイル内で四則演算を行い、その結果を変数に代入する機能

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