postgres/contrib/pgbench/README.pgbench

pgbench README		2005/10/04 Tatsuo Ishii

o What is pgbench?

  pgbench is a simple program to run a benchmark test sort of
  "TPC-B". pgbench is a client application of PostgreSQL and runs
  with PostgreSQL only. It performs lots of small and simple
  transactions including select/update/insert operations then
  calculates number of transactions successfully completed within a
  second (transactions per second, tps). Targeting data includes a
  table with at least 100k tuples.

  Example outputs from pgbench look like:

	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)

  Similar program called "JDBCBench" already exists, but it requires
  Java that may not be available on every platform. Moreover some
  people concerned about the overhead of Java that might lead
  inaccurate results. So I decided to write in pure C, and named
  it "pgbench."

o features of pgbench

  - pgbench is written in C using libpq only. So it is very portable
    and easy to install.

  - pgbench can simulate concurrent connections using asynchronous
    capability of libpq. No threading is required.

o How to install pgbench

 $make
 $make install

o How to use pgbench?

  (1) Initialize database by:

	pgbench -i <dbname>

      where <dbname> is the name of database. pgbench uses four tables
      accounts, branches, history and tellers. These tables will be
      destroyed. Be very careful if you have tables having same
      names. Default test data contains:

	table		# of tuples
	-------------------------
	branches	1
	tellers		10
	accounts	100000
	history		0

	You can increase the number of tuples by using -s option. See
	below.

  (2) Run the benchmark test

	pgbench <dbname>

      The default configuration is:

	number of clients: 1
	number of transactions per client: 10

o options

  pgbench has number of options.

	-h hostname
		hostname where the backend is running. If this option
		is omitted, pgbench will connect to the localhost via
		Unix domain socket.

	-p port
		the port number that the backend is accepting. default is
		libpq's default, usually 5432.

	-c number_of_clients
		Number of clients simulated. default is 1.

	-t number_of_transactions
		Number of transactions each client runs. default is 10.

	-s scaling_factor
		this should be used with -i (initialize) option.
		number of tuples generated will be multiple of the
		scaling factor. For example, -s 100 will imply 10M
		(10,000,000) tuples in the accounts table.
		default is 1.  NOTE: scaling factor should be at least
		as large as the largest number of clients you intend
		to test; else you'll mostly be measuring update contention.

	-U login
		Specify db user's login name if it is different from
		the Unix login name.

	-P password
		Specify the db password. CAUTION: using this option
		might be a security hole since ps command will
		show the password. Use this for TESTING PURPOSE ONLY.

	-n
		No vacuuming and cleaning the history table prior to the
		test is performed.

	-v
		Do vacuuming before testing. This will take some time.
		With neither -n nor -v, pgbench will vacuum tellers and
		branches tables only.

	-S
		Perform select only transactions instead of TPC-B.

	-N	Do not update "branches" and "tellers". This will
	        avoid heavy update contention on branches and tellers,
	        while it will not make pgbench supporting TPC-B like
	        transactions.

	-f filename
		Read transaction script from file. Detailed
		explanation will appear later.

	-C
		Establish connection for each transaction, rather than
		doing it just once at beginning of pgbench in the normal
		mode. This is useful to measure the connection overhead.
	
	-l
		Write the time taken by each transaction to a logfile,
		with the name "pgbench_log.xxx", where xxx is the PID
		of the pgbench process. The format of the log is:

			client_id transaction_no time

		where time is measured in microseconds.

	-d
		debug option.


o What is the "transaction" actually performed in pgbench?

  (1) begin;

  (2) update accounts set abalance = abalance + :delta where aid = :aid;

  (3) select abalance from accounts where aid = :aid;

  (4) update tellers set tbalance = tbalance + :delta where tid = :tid;

  (5) update branches set bbalance = bbalance + :delta where bid = :bid;

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

  (7) end;

o -f option

  This supports for reading transaction script from a specified
  file. This file should include SQL commands in each line. SQL
  command consists of multiple lines are not supported. Empty lines
  and lines begging with "--" will be ignored.

  Multiple -f options are allowed. In this case each transaction is
  assigned randomly chosen script.

  SQL commands can include "meta command" which begins with "\" (back
  slash). A meta command takes some arguments separted by white
  spaces. Currently following meta command is supported:

  \setrandom name min max

	assign random integer to name between min and max

  example:

  \setrandom aid 1 100000

  variables can be reffered to in SQL comands by adding ":" in front
  of the varible name.

  example:

  SELECT abalance FROM accounts WHERE aid = :aid

  For example, TPC-B like benchmark can be defined as follows(scaling
  factor = 1):

\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

o License?

Basically it is same as BSD license. See pgbench.c for more details.

o History

2005/09/29
	* add -f option. contributed by Tomoaki Sato.

[updation records were missing]

2003/11/26
	* create indexes after data insertion to reduce time.
	  patch from Yutaka Tanida.

2003/06/10
	* fix uninitialized memory bug
	* add support for PGHOST, PGPORT, PGUSER environment variables

2002/07/20
	* patch contributed by Neil Conway.
	* code/document clean up and add -l option.

2002/02/24
	* do not CHECKPOINT anymore while initializing benchmark
	* database. Add -N option.

2001/10/24
	* "time"->"mtime"

2001/09/09
	* Add -U, -P, -C options

2000/1/15 pgbench-1.2 contributed to PostgreSQL
	* Add -v option

1999/09/29 pgbench-1.1 released
	* Apply cygwin patches contributed by Yutaka Tanida
	* More robust when backends die
	* Add -S option (select only)

1999/09/04 pgbench-1.0 released