pgbench README 2006/07/26 Tatsuo Ishii o What is pgbench? pgbench is a simple program to run a benchmark test. 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) (optional)Initialize database by: pgbench -i where 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 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. -D varname=value Define a variable. It can be refereed to by a script provided by using -f option. Multile -D options are allowed. -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: \set name operand1 [ operator operand2 ] set the calculated value using "operand1" "operator" "operand2" to variable "name". If "operator" and "operand2" are omitted, the value of operand1 is set to variable "name". example: \set ntellers 10 * :tps \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 Variables can also be defined by using -D option. Example, TPC-B like benchmark can be defined as follows(scaling factor = 1): \set nbranches :tps \set ntellers 10 * :tps \set naccounts 100000 * :tps \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, 'now') END If you want to automatically set the scaling factor from the number of tuples in branches table, use -s option and shell command like this: pgbench -s $(psql -At -c "SELECT count(*) FROM branches") -f tpc_b.sql Notice that -f option does not execute vacuum and clearing history table before starting benchmark. o License? Basically it is same as BSD license. See pgbench.c for more details. o History 2006/07/26 * New features contributed by Tomoaki Sato. * predefined variable "tps" The value of variable tps is taken from the scaling factor specified by -s option. * -D option Variable values can be defined by -D option. * \set command now allows arithmetic calculations. 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