mirror of
https://github.com/postgres/postgres.git
synced 2025-08-09 17:03:00 +03:00
Move most /contrib README files into SGML. Some still need conversion
or will never be converted.
This commit is contained in:
Bruce Momjian
@@ -1,284 +0,0 @@
|
||||
$PostgreSQL: pgsql/contrib/pgbench/README.pgbench,v 1.20 2007/07/06 20:17:02 wieck Exp $
|
||||
|
||||
pgbench README
|
||||
|
||||
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 <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. branches,
|
||||
tellers and accounts tables are created with a fillfactor which is
|
||||
set using -F 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.
|
||||
Regular (not initializing) runs using one of the
|
||||
built-in tests will detect scale based on the number of
|
||||
branches in the database. For custom (-f) runs it can
|
||||
be manually specified with this parameter.
|
||||
|
||||
-D varname=value
|
||||
Define a variable. It can be refered to by a script
|
||||
provided by using -f option. Multiple -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 file_no time-epoch time-us
|
||||
|
||||
where time is measured in microseconds, , the file_no is
|
||||
which test file was used (useful when multiple were
|
||||
specified with -f), and time-epoch/time-us are a
|
||||
UNIX epoch format timestamp followed by an offset
|
||||
in microseconds (suitable for creating a ISO 8601
|
||||
timestamp with a fraction of a second) of when
|
||||
the transaction completed.
|
||||
|
||||
Here are example outputs:
|
||||
|
||||
0 199 2241 0 1175850568 995598
|
||||
0 200 2465 0 1175850568 998079
|
||||
0 201 2513 0 1175850569 608
|
||||
0 202 2038 0 1175850569 2663
|
||||
|
||||
-F fillfactor
|
||||
|
||||
Create tables(accounts, tellers and branches) with the given
|
||||
fillfactor. Default is 100. This should be used with -i
|
||||
(initialize) option.
|
||||
|
||||
-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;
|
||||
|
||||
If you specify -N, (4) and (5) aren't included in the transaction.
|
||||
|
||||
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 * :scale
|
||||
|
||||
\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.
|
||||
|
||||
\sleep num [us|ms|s]
|
||||
|
||||
causes script execution to sleep for the specified duration of
|
||||
microseconds (us), milliseconds (ms) or the default seconds (s).
|
||||
|
||||
example:
|
||||
|
||||
\setrandom millisec 1000 2500
|
||||
\sleep :millisec ms
|
||||
|
||||
Example, TPC-B like benchmark can be defined as follows(scaling
|
||||
factor = 1):
|
||||
|
||||
\set nbranches :scale
|
||||
\set ntellers 10 * :scale
|
||||
\set naccounts 100000 * :scale
|
||||
\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 before contributed to PostgreSQL
|
||||
|
||||
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
|
||||
Reference in New Issue
Block a user