f50ae06e14
Make pgbench "script driven" to eliminate hard coded transaction scenario. (Tatsuo Ishii)
248 lines
6.6 KiB
Plaintext
248 lines
6.6 KiB
Plaintext
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
|