-----------------------------------------------------
About pgcbench
-----------------------------------------------------

The pgcbench is the program which performs the benchmark test of PGCluster. 
Of course, it can use for benchmark not only PGCluster but PostgreSQL.

The pgcbench displays the number of executed transaction per second (tps) which performed transaction containing SELECT, UPDATE, and INSERT.
The table set as the object of transaction contains data of 100,000 lines by a default. 

A display is actually as follows. 
	number of clients: 4
	number of transactions actually processed: 100
	run time (sec) = 4.416423
	tps = 22.642759 (including connections establishing)


The pgcbench is calculating tps not based on the actually completed number of transactions but based on the number that is specified at beginning. 
So, the tps displayed may not be right when the benchmark has been suspended.

The pgcbench was created based on pgbench which is the benchmark program for PostgreSQL written by Tatsuo Ishii.


-----------------------------------------------------
Feature of pgcbench
-----------------------------------------------------
- Although the pgbench is simulating multi-user connections in the single process, pgcbench has made multi-user connections in the multi-process by fork. 
- There are some options which specifies the contents of transaction in pgcbench. 


-----------------------------------------------------
Installation of pgcbench
-----------------------------------------------------
1. Install with the PGCluster 
Your installation of PGCluster also installs pgcbench automatically. 

2. Install only pgcbench
If you want install only pgcbench, you do not need to compile all of the PGCluster. 
pgcbench is compiled as follow.

	$ cd $TOP_PGCusters_Source
	$ ./configure
	$ cd src/interface/libpq
	$ make all
	$ cd $TOP_PGCusters_Source/src/pgcluster/tool
	$ make

-----------------------------------------------------
Usage of pgcbench
-----------------------------------------------------
pgcbench [options] [DB name]
pgcbench -i [options] [DB name] (for initialization of DB)

[options]
-h: host name
-p: port number
-c: number of clients connected simultaneously (default is 1)
-t: number of transaction which each client executed
-s: scaling factor of table size. 1 means 100,000 records. ( use with '-i' )
-u: user name
-P: password
-n: it does not execute VACUUM and is not cleared  history table.
-v: execute VACUUM and clear history table
-I: execute INSERT query only
-U: execute UPDATE query only
-S: execute SELECT query only
-f: command script file name
-T: transaction is performed in the transaction bloc surrounded by BEGIN and END. 
-C: each session is reconnected for every transaction
-l: The execution time of each transaction is recorded. That log file is created under current directory as "pgcbench_log.xxx".
-d: debug option

-----------------------------------------------------
Initialization of the database
-----------------------------------------------------
In order to execute a default benchmark test by pgcbench, the data base should be initialized and made test data. 
You can execute the following commands for initialization of the data base. 

	$ pgcbench -i [DB name ]

Thereby, the following tables are created (when a scaling factor is 1) . 

	table name | row num
	-----------+--------
	branches   |      1
	tellers    |     10
	accounts   | 100000
	history    |      0

When a scaling factor is changed into 10, 100, 1000, etc., according to it, the number of table rows will increase 10 times, 100 times, and 1000 times.
For example, when the scaling factor is set to 100, the number of table rows is as follows. 

	table name |   row num
	-----------+----------
	branches   |      100
	tellers    |     1000
	accounts   | 10000000
	history    |        0


-----------------------------------------------------
Format of the command script file 
-----------------------------------------------------
The pgcbench read the command script file that is specified with '-f' option, and executes the specified transaction. 
The specified command can be described one per one line.
The null line is disregarded and the row which starts with double hyphen means a comment line. 
In addition to the SQL command, the meta-command which starts with a backslash can be described in this file.

The following meta-commands can be used. 

\setrandom name min max
	Random digits are set into variable 'name'. 
	The sphere of random digits is between 'min' and 'max'. 
	For example, when you want to execute the benchmark like TPC-B, you can describes as follows. 


	\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')
	END
