postgresql/contrib/pgbench/README.pgbench
Tatsuo Ishii cdf4b9aff2 Apply patches from Neil Conway.
> Hi Tatsuo,
>
> I've attached a patch for the version of pgbench in CVS. It includes the
> following changes:
>
>     - fix some spelling mistakes, indentation stuff, etc.
>
>     - minor code cleanup -- (void) args instead of (), etc.
>
>     - allocate the state array dynamically, so that it is only as
>     large as needed. This reduces the memory consumption of pgbench
>     slightly, and makes a larger MAXCLIENTS setting possible
>
>     - (the only controversial change) add an option "-l" to log
>     transaction latencies to a file. The "transaction latency"
>     is the time between when the BEGIN is issued and the transaction
>     commits. This is written to a file, along with the client #
>     and the transaction #. The data in the file can then be used
>     for things like:
>
>         - consistency analysis: is the TPS the same through the
>         entire run of pgbench, or does it change?
>
>         - more detailed stats: what is the average latency, worse-case
>         latency, best-case latency?
>
>         - graphs: feed the data to gnuplot, graph latency versus. time
>
>         - etc.
>
>     I was going to store this data in memory and write it to disk
>     at the end of the pgbench run, but that isn't feasible because
>     the data can be very large: for example, ~70MB if benchmarking
>     128 clients doing 100,000 transactions each.
>
> Cheers,
>
> Neil
2002-07-20 03:02:01 +00:00

188 lines
4.9 KiB
Plaintext

pgbench README 2002/07/20 Tatsuo Ishii (t-ishii@sra.co.jp)
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
(1) Configure and build the standard Postgres distribution.
You can get away with just running configure at the top level
and doing "make all" in src/interfaces/libpq.
(2) Run make in this directory.
You will see an executable file "pgbench". You can run it here,
or install it with the standard Postgres programs by doing
"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.
-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.
-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 License?
Basically it is same as BSD license. See pgbench.c for more details.
o History
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