2015-03-11 03:33:24 +01:00
|
|
|
<!-- doc/src/sgml/ref/pgbench.sgml -->
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refentry id="pgbench">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="pgbench">
|
|
|
|
<primary>pgbench</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refmeta>
|
|
|
|
<refentrytitle><application>pgbench</application></refentrytitle>
|
|
|
|
<manvolnum>1</manvolnum>
|
|
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
|
|
</refmeta>
|
|
|
|
|
|
|
|
<refnamediv>
|
|
|
|
<refname>pgbench</refname>
|
|
|
|
<refpurpose>run a benchmark test on <productname>PostgreSQL</productname></refpurpose>
|
|
|
|
</refnamediv>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsynopsisdiv>
|
|
|
|
<cmdsynopsis>
|
|
|
|
<command>pgbench</command>
|
|
|
|
<arg choice="plain"><option>-i</option></arg>
|
|
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
|
|
<arg choice="opt"><replaceable>dbname</replaceable></arg>
|
|
|
|
</cmdsynopsis>
|
|
|
|
<cmdsynopsis>
|
|
|
|
<command>pgbench</command>
|
|
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
|
|
|
<arg choice="opt"><replaceable>dbname</replaceable></arg>
|
|
|
|
</cmdsynopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Description</title>
|
2010-03-23 05:09:17 +01:00
|
|
|
<para>
|
|
|
|
<application>pgbench</application> is a simple program for running benchmark
|
|
|
|
tests on <productname>PostgreSQL</>. It runs the same sequence of SQL
|
|
|
|
commands over and over, possibly in multiple concurrent database sessions,
|
|
|
|
and then calculates the average transaction rate (transactions per second).
|
|
|
|
By default, <application>pgbench</application> tests a scenario that is
|
|
|
|
loosely based on TPC-B, involving five <command>SELECT</>,
|
|
|
|
<command>UPDATE</>, and <command>INSERT</> commands per transaction.
|
|
|
|
However, it is easy to test other cases by writing your own transaction
|
|
|
|
script files.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2015-09-11 03:22:21 +02:00
|
|
|
Typical output from <application>pgbench</application> looks like:
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2016-01-27 02:54:22 +01:00
|
|
|
transaction type: <builtin: TPC-B (sort of)>
|
2010-03-23 05:09:17 +01:00
|
|
|
scaling factor: 10
|
|
|
|
query mode: simple
|
|
|
|
number of clients: 10
|
|
|
|
number of threads: 1
|
|
|
|
number of transactions per client: 1000
|
|
|
|
number of transactions actually processed: 10000/10000
|
|
|
|
tps = 85.184871 (including connections establishing)
|
|
|
|
tps = 85.296346 (excluding connections establishing)
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
The first six lines report some of the most important parameter
|
|
|
|
settings. The next line reports the number of transactions completed
|
|
|
|
and intended (the latter being just the product of number of clients
|
|
|
|
and number of transactions per client); these will be equal unless the run
|
2012-05-09 19:39:53 +02:00
|
|
|
failed before completion. (In <option>-T</> mode, only the actual
|
2010-08-12 22:39:39 +02:00
|
|
|
number of transactions is printed.)
|
2010-08-15 21:46:24 +02:00
|
|
|
The last two lines report the number of transactions per second,
|
2010-03-23 05:09:17 +01:00
|
|
|
figured with and without counting the time to start database sessions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The default TPC-B-like transaction test requires specific tables to be
|
|
|
|
set up beforehand. <application>pgbench</> should be invoked with
|
2012-05-09 19:39:53 +02:00
|
|
|
the <option>-i</> (initialize) option to create and populate these
|
2010-03-23 05:09:17 +01:00
|
|
|
tables. (When you are testing a custom script, you don't need this
|
|
|
|
step, but will instead need to do whatever setup your test needs.)
|
|
|
|
Initialization looks like:
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbname</>
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
where <replaceable>dbname</> is the name of the already-created
|
2012-05-09 19:39:53 +02:00
|
|
|
database to test in. (You may also need <option>-h</>,
|
|
|
|
<option>-p</>, and/or <option>-U</> options to specify how to
|
2010-03-23 05:09:17 +01:00
|
|
|
connect to the database server.)
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<caution>
|
|
|
|
<para>
|
|
|
|
<literal>pgbench -i</> creates four tables <structname>pgbench_accounts</>,
|
|
|
|
<structname>pgbench_branches</>, <structname>pgbench_history</>, and
|
|
|
|
<structname>pgbench_tellers</>,
|
|
|
|
destroying any existing tables of these names.
|
|
|
|
Be very careful to use another database if you have tables having these
|
|
|
|
names!
|
|
|
|
</para>
|
|
|
|
</caution>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
At the default <quote>scale factor</> of 1, the tables initially
|
|
|
|
contain this many rows:
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2010-03-23 05:09:17 +01:00
|
|
|
table # of rows
|
|
|
|
---------------------------------
|
|
|
|
pgbench_branches 1
|
|
|
|
pgbench_tellers 10
|
|
|
|
pgbench_accounts 100000
|
|
|
|
pgbench_history 0
|
2010-07-29 21:34:41 +02:00
|
|
|
</screen>
|
2010-03-23 05:09:17 +01:00
|
|
|
You can (and, for most purposes, probably should) increase the number
|
2012-05-09 19:39:53 +02:00
|
|
|
of rows by using the <option>-s</> (scale factor) option. The
|
|
|
|
<option>-F</> (fillfactor) option might also be used at this point.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Once you have done the necessary setup, you can run your benchmark
|
2012-05-09 19:39:53 +02:00
|
|
|
with a command that doesn't include <option>-i</>, that is
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</>
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
In nearly all cases, you'll need some options to make a useful test.
|
2012-05-09 19:39:53 +02:00
|
|
|
The most important options are <option>-c</> (number of clients),
|
|
|
|
<option>-t</> (number of transactions), <option>-T</> (time limit),
|
|
|
|
and <option>-f</> (specify a custom script file).
|
2010-03-23 05:09:17 +01:00
|
|
|
See below for a full list.
|
|
|
|
</para>
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>Options</title>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
<para>
|
2012-05-09 19:39:53 +02:00
|
|
|
The following is divided into three subsections: Different options are used
|
|
|
|
during database initialization and while running benchmarks, some options
|
|
|
|
are useful in both cases.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2 id="pgbench-init-options">
|
|
|
|
<title>Initialization Options</title>
|
2010-05-25 17:55:28 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
<application>pgbench</application> accepts the following command-line
|
|
|
|
initialization arguments:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
|
|
|
<varlistentry>
|
2010-08-12 22:39:39 +02:00
|
|
|
<term><option>-i</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--initialize</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-08-12 22:39:39 +02:00
|
|
|
Required to invoke initialization mode.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2013-05-14 03:37:01 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-F</option> <replaceable>fillfactor</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--fillfactor=</option><replaceable>fillfactor</></term>
|
2013-05-14 03:37:01 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Create the <structname>pgbench_accounts</>,
|
|
|
|
<structname>pgbench_tellers</> and
|
|
|
|
<structname>pgbench_branches</> tables with the given fillfactor.
|
|
|
|
Default is 100.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2012-07-23 20:38:34 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-n</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--no-vacuum</option></term>
|
2012-07-23 20:38:34 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Perform no vacuuming after initialization.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
<varlistentry>
|
2013-05-14 03:37:01 +02:00
|
|
|
<term><option>-q</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--quiet</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2013-05-14 03:37:01 +02:00
|
|
|
Switch logging to quiet mode, producing only one progress message per 5
|
|
|
|
seconds. The default logging prints one message each 100000 rows, which
|
|
|
|
often outputs many lines per second (especially on good hardware).
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-s</option> <replaceable>scale_factor</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--scale=</option><replaceable>scale_factor</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Multiply the number of rows generated by the scale factor.
|
|
|
|
For example, <literal>-s 100</> will create 10,000,000 rows
|
|
|
|
in the <structname>pgbench_accounts</> table. Default is 1.
|
2013-01-29 10:49:40 +01:00
|
|
|
When the scale is 20,000 or larger, the columns used to
|
|
|
|
hold account identifiers (<structfield>aid</structfield> columns)
|
|
|
|
will switch to using larger integers (<type>bigint</type>),
|
|
|
|
in order to be big enough to hold the range of account
|
|
|
|
identifiers.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2012-06-20 00:33:59 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>--foreign-keys</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Create foreign key constraints between the standard tables.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-07-25 15:16:14 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>--index-tablespace=<replaceable>index_tablespace</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Create indexes in the specified tablespace, rather than the default
|
|
|
|
tablespace.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>--tablespace=<replaceable>tablespace</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Create tables in the specified tablespace, rather than the default
|
|
|
|
tablespace.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2011-07-25 12:49:00 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>--unlogged-tables</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Create all tables as unlogged tables, rather than permanent tables.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-05-25 17:55:28 +02:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2 id="pgbench-run-options">
|
|
|
|
<title>Benchmarking Options</title>
|
2010-05-25 17:55:28 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
<application>pgbench</application> accepts the following command-line
|
|
|
|
benchmarking arguments:
|
|
|
|
|
|
|
|
<variablelist>
|
2016-01-27 02:54:22 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-b</> <replaceable>scriptname</></term>
|
|
|
|
<term><option>--builtin</> <replaceable>scriptname</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Add the specified builtin script to the list of executed scripts.
|
|
|
|
Available builtin scripts are: <literal>tpcb-like</>,
|
|
|
|
<literal>simple-update</> and <literal>select-only</>.
|
|
|
|
With special name <literal>list</>, show the list of builtin scripts
|
|
|
|
and exit immediately.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-c</option> <replaceable>clients</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--client=</option><replaceable>clients</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Number of clients simulated, that is, number of concurrent database
|
|
|
|
sessions. Default is 1.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-C</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--connect</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Establish a new connection for each transaction, rather than
|
|
|
|
doing it just once per client session.
|
|
|
|
This is useful to measure the connection overhead.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-d</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--debug</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Print debugging output.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-D</option> <replaceable>varname</><literal>=</><replaceable>value</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--define=</option><replaceable>varname</><literal>=</><replaceable>value</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Define a variable for use by a custom script (see below).
|
2012-05-09 19:39:53 +02:00
|
|
|
Multiple <option>-D</> options are allowed.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
2016-01-27 02:54:22 +01:00
|
|
|
<term><option>-f</> <replaceable>filename</></term>
|
|
|
|
<term><option>--file=</><replaceable>filename</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2016-01-27 02:54:22 +01:00
|
|
|
Add a transaction script read from <replaceable>filename</> to
|
|
|
|
the list of executed scripts.
|
2010-05-25 17:55:28 +02:00
|
|
|
See below for details.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-j</option> <replaceable>threads</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--jobs=</option><replaceable>threads</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Number of worker threads within <application>pgbench</application>.
|
|
|
|
Using more than one thread can be helpful on multi-CPU machines.
|
2015-07-03 09:45:40 +02:00
|
|
|
Clients are distributed as evenly as possible among available threads.
|
2010-05-25 17:55:28 +02:00
|
|
|
Default is 1.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-l</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--log</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-08-17 06:37:21 +02:00
|
|
|
Write the time taken by each transaction to a log file.
|
2010-05-25 17:55:28 +02:00
|
|
|
See below for details.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2014-10-13 19:25:56 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-L</option> <replaceable>limit</></term>
|
|
|
|
<term><option>--latency-limit=</option><replaceable>limit</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Transaction which last more than <replaceable>limit</> milliseconds
|
|
|
|
are counted and reported separately, as <firstterm>late</>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
When throttling is used (<option>--rate=...</>), transactions that
|
|
|
|
lag behind schedule by more than <replaceable>limit</> ms, and thus
|
|
|
|
have no hope of meeting the latency limit, are not sent to the server
|
|
|
|
at all. They are counted and reported separately as
|
|
|
|
<firstterm>skipped</>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-M</option> <replaceable>querymode</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--protocol=</option><replaceable>querymode</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Protocol to use for submitting queries to the server:
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
|
|
<para><literal>simple</>: use simple query protocol.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para><literal>extended</>: use extended query protocol.</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
|
|
<para><literal>prepared</>: use extended query protocol with prepared statements.</para>
|
|
|
|
</listitem>
|
|
|
|
</itemizedlist>
|
|
|
|
The default is simple query protocol. (See <xref linkend="protocol">
|
|
|
|
for more information.)
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-n</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--no-vacuum</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Perform no vacuuming before running the test.
|
|
|
|
This option is <emphasis>necessary</>
|
|
|
|
if you are running a custom test scenario that does not include
|
|
|
|
the standard tables <structname>pgbench_accounts</>,
|
|
|
|
<structname>pgbench_branches</>, <structname>pgbench_history</>, and
|
|
|
|
<structname>pgbench_tellers</>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-N</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--skip-some-updates</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2016-01-27 02:54:22 +01:00
|
|
|
Run builtin simple-update script.
|
|
|
|
Shorthand for <option>-b simple-update</>.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2013-07-17 01:05:37 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-P</option> <replaceable>sec</></term>
|
2013-07-23 01:40:22 +02:00
|
|
|
<term><option>--progress=</option><replaceable>sec</></term>
|
2013-07-17 01:05:37 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2013-10-05 23:33:38 +02:00
|
|
|
Show progress report every <literal>sec</> seconds. The report
|
|
|
|
includes the time since the beginning of the run, the tps since the
|
|
|
|
last report, and the transaction latency average and standard
|
2014-09-11 11:40:01 +02:00
|
|
|
deviation since the last report. Under throttling (<option>-R</>),
|
|
|
|
the latency is computed with respect to the transaction scheduled
|
|
|
|
start time, not the actual transaction beginning time, thus it also
|
|
|
|
includes the average schedule lag time.
|
2013-07-17 01:05:37 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2015-09-16 16:24:53 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>--progress-timestamp</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
When showing progress (option <option>-P</>), use a timestamp
|
|
|
|
(Unix epoch) instead of the number of seconds since the
|
|
|
|
beginning of the run. The unit is in seconds, with millisecond
|
|
|
|
precision after the dot.
|
|
|
|
This helps compare logs generated by various tools.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2014-07-15 20:34:33 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-r</option></term>
|
|
|
|
<term><option>--report-latencies</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Report the average per-statement latency (execution time from the
|
|
|
|
perspective of the client) of each command after the benchmark
|
|
|
|
finishes. See below for details.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2013-07-23 01:40:22 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-R</option> <replaceable>rate</></term>
|
|
|
|
<term><option>--rate=</option><replaceable>rate</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Execute transactions targeting the specified rate instead of running
|
|
|
|
as fast as possible (the default). The rate is given in transactions
|
|
|
|
per second. If the targeted rate is above the maximum possible rate,
|
|
|
|
the rate limit won't impact the results.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
The rate is targeted by starting transactions along a
|
2013-09-23 21:49:21 +02:00
|
|
|
Poisson-distributed schedule time line. The expected start time
|
2013-07-23 01:40:22 +02:00
|
|
|
schedule moves forward based on when the client first started, not
|
|
|
|
when the previous transaction ended. That approach means that when
|
|
|
|
transactions go past their original scheduled end time, it is
|
|
|
|
possible for later ones to catch up again.
|
|
|
|
</para>
|
2013-11-10 15:20:52 +01:00
|
|
|
<para>
|
2014-09-11 11:40:01 +02:00
|
|
|
When throttling is active, the transaction latency reported at the
|
|
|
|
end of the run is calculated from the scheduled start times, so it
|
|
|
|
includes the time each transaction had to wait for the previous
|
|
|
|
transaction to finish. The wait time is called the schedule lag time,
|
|
|
|
and its average and maximum are also reported separately. The
|
|
|
|
transaction latency with respect to the actual transaction start time,
|
|
|
|
i.e. the time spent executing the transaction in the database, can be
|
|
|
|
computed by subtracting the schedule lag time from the reported
|
|
|
|
latency.
|
2013-07-23 01:40:22 +02:00
|
|
|
</para>
|
2014-09-11 11:40:01 +02:00
|
|
|
|
2014-10-13 19:25:56 +02:00
|
|
|
<para>
|
|
|
|
If <option>--latency-limit</> is used together with <option>--rate</>,
|
|
|
|
a transaction can lag behind so much that it is already over the
|
|
|
|
latency limit when the previous transaction ends, because the latency
|
|
|
|
is calculated from the scheduled start time. Such transactions are
|
|
|
|
not sent to the server, but are skipped altogether and counted
|
|
|
|
separately.
|
|
|
|
</para>
|
|
|
|
|
2013-07-23 01:40:22 +02:00
|
|
|
<para>
|
2014-09-11 11:40:01 +02:00
|
|
|
A high schedule lag time is an indication that the system cannot
|
|
|
|
process transactions at the specified rate, with the chosen number of
|
|
|
|
clients and threads. When the average transaction execution time is
|
|
|
|
longer than the scheduled interval between each transaction, each
|
|
|
|
successive transaction will fall further behind, and the schedule lag
|
|
|
|
time will keep increasing the longer the test run is. When that
|
|
|
|
happens, you will have to reduce the specified transaction rate.
|
2013-07-23 01:40:22 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-s</option> <replaceable>scale_factor</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--scale=</option><replaceable>scale_factor</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Report the specified scale factor in <application>pgbench</>'s
|
|
|
|
output. With the built-in tests, this is not necessary; the
|
|
|
|
correct scale factor will be detected by counting the number of
|
2016-01-27 02:54:22 +01:00
|
|
|
rows in the <structname>pgbench_branches</> table.
|
|
|
|
However, when testing only custom benchmarks (<option>-f</> option),
|
|
|
|
the scale factor will be reported as 1 unless this option is used.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-S</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--select-only</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2016-01-27 02:54:22 +01:00
|
|
|
Run built-in select-only script.
|
|
|
|
Shorthand for <option>-b select-only</>.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-t</option> <replaceable>transactions</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--transactions=</option><replaceable>transactions</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Number of transactions each client runs. Default is 10.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-T</option> <replaceable>seconds</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--time=</option><replaceable>seconds</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Run the test for this many seconds, rather than a fixed number of
|
2012-05-09 19:39:53 +02:00
|
|
|
transactions per client. <option>-t</option> and
|
|
|
|
<option>-T</option> are mutually exclusive.
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-v</option></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--vacuum-all</option></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Vacuum all four standard tables before running the test.
|
2015-09-11 03:22:21 +02:00
|
|
|
With neither <option>-n</> nor <option>-v</>, <application>pgbench</application> will vacuum the
|
2010-05-25 17:55:28 +02:00
|
|
|
<structname>pgbench_tellers</> and <structname>pgbench_branches</>
|
|
|
|
tables, and will truncate <structname>pgbench_history</>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2013-05-14 03:37:01 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>--aggregate-interval=<replaceable>seconds</></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Length of aggregation interval (in seconds). May be used only together
|
|
|
|
with <application>-l</application> - with this option, the log contains
|
|
|
|
per-interval summary (number of transactions, min/max latency and two
|
|
|
|
additional fields useful for variance estimation).
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
This option is not currently supported on Windows.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>--sampling-rate=<replaceable>rate</></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sampling rate, used when writing data into the log, to reduce the
|
|
|
|
amount of log generated. If this option is given, only the specified
|
|
|
|
fraction of transactions are logged. 1.0 means all transactions will
|
|
|
|
be logged, 0.05 means only 5% of the transactions will be logged.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
Remember to take the sampling rate into account when processing the
|
|
|
|
log file. For example, when computing tps values, you need to multiply
|
|
|
|
the numbers accordingly (e.g. with 0.01 sample rate, you'll only get
|
|
|
|
1/100 of the actual tps).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2010-05-25 17:55:28 +02:00
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-05-25 17:55:28 +02:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2 id="pgbench-common-options">
|
|
|
|
<title>Common Options</title>
|
2010-05-25 17:55:28 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
<application>pgbench</application> accepts the following command-line
|
|
|
|
common arguments:
|
|
|
|
|
|
|
|
<variablelist>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-h</option> <replaceable>hostname</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--host=</option><replaceable>hostname</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-08-17 06:37:21 +02:00
|
|
|
The database server's host name
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-p</option> <replaceable>port</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--port=</option><replaceable>port</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
The database server's port number
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-U</option> <replaceable>login</></term>
|
2013-06-27 14:52:13 +02:00
|
|
|
<term><option>--username=</option><replaceable>login</></term>
|
2010-05-25 17:55:28 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2010-08-17 06:37:21 +02:00
|
|
|
The user name to connect as
|
2010-05-25 17:55:28 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2012-06-18 01:44:00 +02:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-V</></term>
|
|
|
|
<term><option>--version</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Print the <application>pgbench</application> version and exit.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term><option>-?</></term>
|
|
|
|
<term><option>--help</></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Show help about <application>pgbench</application> command line
|
|
|
|
arguments, and exit.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-05-25 17:55:28 +02:00
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
|
|
|
</refsect1>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<refsect2>
|
2015-09-11 03:22:21 +02:00
|
|
|
<title>What is the <quote>Transaction</> Actually Performed in <application>pgbench</application>?</title>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
<para>
|
2016-01-27 02:54:22 +01:00
|
|
|
Pgbench executes test scripts chosen randomly from a specified list.
|
|
|
|
They include built-in scripts with <option>-b</> and
|
|
|
|
user-provided custom scripts with <option>-f</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The default builtin transaction script (also invoked with <option>-b tpcb-like</>)
|
|
|
|
issues seven commands per transaction over randomly chosen <literal>aid</>,
|
|
|
|
<literal>tid</>, <literal>bid</> and <literal>balance</>.
|
|
|
|
The scenario is inspired by the TPC-B benchmark, but is not actually TPC-B,
|
|
|
|
hence the name.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<orderedlist>
|
|
|
|
<listitem><para><literal>BEGIN;</literal></para></listitem>
|
|
|
|
<listitem><para><literal>UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;</literal></para></listitem>
|
|
|
|
<listitem><para><literal>SELECT abalance FROM pgbench_accounts WHERE aid = :aid;</literal></para></listitem>
|
|
|
|
<listitem><para><literal>UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;</literal></para></listitem>
|
|
|
|
<listitem><para><literal>UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;</literal></para></listitem>
|
|
|
|
<listitem><para><literal>INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);</literal></para></listitem>
|
|
|
|
<listitem><para><literal>END;</literal></para></listitem>
|
|
|
|
</orderedlist>
|
|
|
|
|
|
|
|
<para>
|
2016-01-27 02:54:22 +01:00
|
|
|
If you select the <literal>simple-update</> builtin (also <option>-N</>),
|
|
|
|
steps 4 and 5 aren't included in the transaction.
|
|
|
|
This will avoid update contention on these tables, but
|
|
|
|
it makes the test case even less like TPC-B.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If you select the <literal>select-only</> builtin (also <option>-S</>),
|
|
|
|
only the <command>SELECT</> is issued.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2>
|
2010-03-23 05:09:17 +01:00
|
|
|
<title>Custom Scripts</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<application>pgbench</application> has support for running custom
|
|
|
|
benchmark scenarios by replacing the default transaction script
|
|
|
|
(described above) with a transaction script read from a file
|
2012-05-09 19:39:53 +02:00
|
|
|
(<option>-f</option> option). In this case a <quote>transaction</>
|
2016-01-27 02:54:22 +01:00
|
|
|
counts as one execution of a script file.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2010-08-17 06:37:21 +02:00
|
|
|
The format of a script file is one SQL command per line; multiline
|
2010-03-23 05:09:17 +01:00
|
|
|
SQL commands are not supported. Empty lines and lines beginning with
|
|
|
|
<literal>--</> are ignored. Script file lines can also be
|
|
|
|
<quote>meta commands</>, which are interpreted by <application>pgbench</>
|
|
|
|
itself, as described below.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
There is a simple variable-substitution facility for script files.
|
2012-05-09 19:39:53 +02:00
|
|
|
Variables can be set by the command-line <option>-D</> option,
|
2010-03-23 05:09:17 +01:00
|
|
|
explained above, or by the meta commands explained below.
|
2012-05-09 19:39:53 +02:00
|
|
|
In addition to any variables preset by <option>-D</> command-line options,
|
2013-06-14 22:31:44 +02:00
|
|
|
there are a few variables that are preset automatically, listed in
|
|
|
|
<xref linkend="pgbench-automatic-variables">. A value specified for these
|
|
|
|
variables using <option>-D</> takes precedence over the automatic presets.
|
2010-03-23 05:09:17 +01:00
|
|
|
Once set, a variable's
|
|
|
|
value can be inserted into a SQL command by writing
|
|
|
|
<literal>:</><replaceable>variablename</>. When running more than
|
|
|
|
one client session, each session has its own set of variables.
|
|
|
|
</para>
|
|
|
|
|
2013-06-14 22:31:44 +02:00
|
|
|
<table id="pgbench-automatic-variables">
|
|
|
|
<title>Automatic variables</title>
|
|
|
|
<tgroup cols="2">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>Variable</entry>
|
|
|
|
<entry>Description</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry> <literal>scale</literal> </entry>
|
|
|
|
<entry>current scale factor</entry>
|
|
|
|
</row>
|
|
|
|
|
|
|
|
<row>
|
|
|
|
<entry> <literal>client_id</literal> </entry>
|
|
|
|
<entry>unique number identifying the client session (starts from zero)</entry>
|
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
|
|
|
|
2010-03-23 05:09:17 +01:00
|
|
|
<para>
|
|
|
|
Script file meta commands begin with a backslash (<literal>\</>).
|
|
|
|
Arguments to a meta command are separated by white space.
|
|
|
|
These meta commands are supported:
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<variablelist>
|
2016-03-01 19:04:09 +01:00
|
|
|
<varlistentry id='pgbench-metacommand-set'>
|
2010-03-23 05:09:17 +01:00
|
|
|
<term>
|
2015-03-03 05:28:31 +01:00
|
|
|
<literal>\set <replaceable>varname</> <replaceable>expression</></literal>
|
2010-03-23 05:09:17 +01:00
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2015-03-02 20:21:41 +01:00
|
|
|
Sets variable <replaceable>varname</> to an integer value calculated
|
|
|
|
from <replaceable>expression</>.
|
|
|
|
The expression may contain integer constants such as <literal>5432</>,
|
|
|
|
references to variables <literal>:</><replaceable>variablename</>,
|
|
|
|
and expressions composed of unary (<literal>-</>) or binary operators
|
2016-03-01 19:04:09 +01:00
|
|
|
(<literal>+</>, <literal>-</>, <literal>*</>, <literal>/</>,
|
|
|
|
<literal>%</>) with their usual associativity,
|
|
|
|
<link linkend="pgbench-builtin-functions">function calls</>, and
|
|
|
|
parentheses.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2015-03-02 20:21:41 +01:00
|
|
|
Examples:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
\set ntellers 10 * :scale
|
2015-03-02 20:21:41 +01:00
|
|
|
\set aid (1021 * :aid) % (100000 * :scale) + 1
|
2012-05-15 21:55:13 +02:00
|
|
|
</programlisting></para>
|
2010-03-23 05:09:17 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
2015-12-18 19:24:51 +01:00
|
|
|
<literal>\setrandom <replaceable>varname</> <replaceable>min</> <replaceable>max</> [ uniform | { gaussian | exponential } <replaceable>parameter</> ]</literal>
|
2014-07-30 19:22:08 +02:00
|
|
|
</term>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sets variable <replaceable>varname</> to a random integer value
|
|
|
|
between the limits <replaceable>min</> and <replaceable>max</> inclusive.
|
|
|
|
Each limit can be either an integer constant or a
|
|
|
|
<literal>:</><replaceable>variablename</> reference to a variable
|
|
|
|
having an integer value.
|
|
|
|
</para>
|
|
|
|
|
2014-07-30 19:22:08 +02:00
|
|
|
<para>
|
|
|
|
By default, or when <literal>uniform</> is specified, all values in the
|
2014-08-30 17:52:36 +02:00
|
|
|
range are drawn with equal probability. Specifying <literal>gaussian</>
|
2014-07-30 19:22:08 +02:00
|
|
|
or <literal>exponential</> options modifies this behavior; each
|
2015-12-18 19:24:51 +01:00
|
|
|
requires a mandatory parameter which determines the precise shape of the
|
2014-07-30 19:22:08 +02:00
|
|
|
distribution.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For a Gaussian distribution, the interval is mapped onto a standard
|
|
|
|
normal distribution (the classical bell-shaped Gaussian curve) truncated
|
2015-12-18 19:24:51 +01:00
|
|
|
at <literal>-parameter</> on the left and <literal>+parameter</>
|
2014-07-30 19:22:08 +02:00
|
|
|
on the right.
|
2015-12-18 19:24:51 +01:00
|
|
|
Values in the middle of the interval are more likely to be drawn.
|
2014-07-30 19:22:08 +02:00
|
|
|
To be precise, if <literal>PHI(x)</> is the cumulative distribution
|
|
|
|
function of the standard normal distribution, with mean <literal>mu</>
|
2015-12-18 19:24:51 +01:00
|
|
|
defined as <literal>(max + min) / 2.0</>, with
|
|
|
|
<literallayout>
|
|
|
|
f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) /
|
|
|
|
(2.0 * PHI(parameter) - 1.0)
|
|
|
|
</literallayout>
|
|
|
|
then value <replaceable>i</> between <replaceable>min</> and
|
|
|
|
<replaceable>max</> inclusive is drawn with probability:
|
|
|
|
<literal>f(i + 0.5) - f(i - 0.5)</>.
|
|
|
|
Intuitively, the larger <replaceable>parameter</>, the more
|
2014-07-30 19:22:08 +02:00
|
|
|
frequently values close to the middle of the interval are drawn, and the
|
|
|
|
less frequently values close to the <replaceable>min</> and
|
2015-12-18 19:24:51 +01:00
|
|
|
<replaceable>max</> bounds. About 67% of values are drawn from the
|
|
|
|
middle <literal>1.0 / parameter</>, that is a relative
|
|
|
|
<literal>0.5 / parameter</> around the mean, and 95% in the middle
|
|
|
|
<literal>2.0 / parameter</>, that is a relative
|
|
|
|
<literal>1.0 / parameter</> around the mean; for instance, if
|
|
|
|
<replaceable>parameter</> is 4.0, 67% of values are drawn from the
|
|
|
|
middle quarter (1.0 / 4.0) of the interval (i.e. from
|
|
|
|
<literal>3.0 / 8.0</> to <literal>5.0 / 8.0</>) and 95% from
|
|
|
|
the middle half (<literal>2.0 / 4.0</>) of the interval (second and
|
|
|
|
third quartiles). The minimum <replaceable>parameter</> is 2.0 for
|
|
|
|
performance of the Box-Muller transform.
|
2014-07-30 19:22:08 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2015-12-18 19:24:51 +01:00
|
|
|
For an exponential distribution, <replaceable>parameter</>
|
|
|
|
controls the distribution by truncating a quickly-decreasing
|
|
|
|
exponential distribution at <replaceable>parameter</>, and then
|
2014-07-30 19:22:08 +02:00
|
|
|
projecting onto integers between the bounds.
|
2015-12-18 19:24:51 +01:00
|
|
|
To be precise, with
|
|
|
|
<literallayout>
|
|
|
|
f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1.0 - exp(-parameter))
|
|
|
|
</literallayout>
|
|
|
|
Then value <replaceable>i</> between <replaceable>min</> and
|
2014-07-30 19:22:08 +02:00
|
|
|
<replaceable>max</> inclusive is drawn with probability:
|
2015-12-18 19:24:51 +01:00
|
|
|
<literal>f(x) - f(x + 1)</>.
|
|
|
|
Intuitively, the larger <replaceable>parameter</>, the more
|
2014-07-30 19:22:08 +02:00
|
|
|
frequently values close to <replaceable>min</> are accessed, and the
|
|
|
|
less frequently values close to <replaceable>max</> are accessed.
|
2015-12-18 19:24:51 +01:00
|
|
|
The closer to 0 <replaceable>parameter</>, the flatter (more uniform)
|
|
|
|
the access distribution.
|
2014-07-30 19:22:08 +02:00
|
|
|
A crude approximation of the distribution is that the most frequent 1%
|
|
|
|
values in the range, close to <replaceable>min</>, are drawn
|
2015-12-18 19:24:51 +01:00
|
|
|
<replaceable>parameter</>% of the time.
|
|
|
|
<replaceable>parameter</> value must be strictly positive.
|
2014-07-30 19:22:08 +02:00
|
|
|
</para>
|
|
|
|
|
2010-03-23 05:09:17 +01:00
|
|
|
<para>
|
|
|
|
Example:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2014-07-30 19:22:08 +02:00
|
|
|
\setrandom aid 1 :naccounts gaussian 5.0
|
2012-05-15 21:55:13 +02:00
|
|
|
</programlisting></para>
|
2010-03-23 05:09:17 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<literal>\sleep <replaceable>number</> [ us | ms | s ]</literal>
|
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Causes script execution to sleep for the specified duration in
|
|
|
|
microseconds (<literal>us</>), milliseconds (<literal>ms</>) or seconds
|
|
|
|
(<literal>s</>). If the unit is omitted then seconds are the default.
|
|
|
|
<replaceable>number</> can be either an integer constant or a
|
|
|
|
<literal>:</><replaceable>variablename</> reference to a variable
|
|
|
|
having an integer value.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Example:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
\sleep 10 ms
|
2012-05-15 21:55:13 +02:00
|
|
|
</programlisting></para>
|
2010-03-23 05:09:17 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<literal>\setshell <replaceable>varname</> <replaceable>command</> [ <replaceable>argument</> ... ]</literal>
|
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sets variable <replaceable>varname</> to the result of the shell command
|
|
|
|
<replaceable>command</>. The command must return an integer value
|
|
|
|
through its standard output.
|
|
|
|
</para>
|
|
|
|
|
2013-05-14 03:59:39 +02:00
|
|
|
<para><replaceable>argument</> can be either a text constant or a
|
2010-03-23 05:09:17 +01:00
|
|
|
<literal>:</><replaceable>variablename</> reference to a variable of
|
|
|
|
any types. If you want to use <replaceable>argument</> starting with
|
|
|
|
colons, you need to add an additional colon at the beginning of
|
|
|
|
<replaceable>argument</>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Example:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
\setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon
|
2012-05-15 21:55:13 +02:00
|
|
|
</programlisting></para>
|
2010-03-23 05:09:17 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
|
|
<literal>\shell <replaceable>command</> [ <replaceable>argument</> ... ]</literal>
|
|
|
|
</term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Same as <literal>\setshell</literal>, but the result is ignored.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Example:
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
\shell command literal_argument :variable ::literal_starting_with_colon
|
2012-05-15 21:55:13 +02:00
|
|
|
</programlisting></para>
|
2010-03-23 05:09:17 +01:00
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
As an example, the full definition of the built-in TPC-B-like
|
|
|
|
transaction is:
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
\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 -5000 5000
|
|
|
|
BEGIN;
|
|
|
|
UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
|
|
|
|
SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
|
|
|
|
UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
|
|
|
|
UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
|
|
|
|
INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
|
|
|
|
END;
|
2010-07-29 21:34:41 +02:00
|
|
|
</programlisting>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
This script allows each iteration of the transaction to reference
|
|
|
|
different, randomly-chosen rows. (This example also shows why it's
|
|
|
|
important for each client session to have its own variables —
|
|
|
|
otherwise they'd not be independently touching different rows.)
|
|
|
|
</para>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2016-03-01 19:04:09 +01:00
|
|
|
<refsect2 id="pgbench-builtin-functions">
|
|
|
|
<title>Built-In Functions</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The following functions are built into <application>pgbench</> and
|
|
|
|
may be used in conjunction with
|
|
|
|
<link linkend="pgbench-metacommand-set"><literal>\set</literal></link>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<!-- list pgbench functions in alphabetical order -->
|
|
|
|
<table>
|
|
|
|
<title>pgbench Functions</title>
|
|
|
|
<tgroup cols="5">
|
|
|
|
<thead>
|
|
|
|
<row>
|
|
|
|
<entry>Function</entry>
|
|
|
|
<entry>Return Type</entry>
|
|
|
|
<entry>Description</entry>
|
|
|
|
<entry>Example</entry>
|
|
|
|
<entry>Result</entry>
|
|
|
|
</row>
|
|
|
|
</thead>
|
|
|
|
<tbody>
|
|
|
|
<row>
|
|
|
|
<entry><literal><function>abs(<replaceable>a</>)</></></>
|
|
|
|
<entry>same as <replaceable>a</></>
|
|
|
|
<entry>integer value</>
|
|
|
|
<entry><literal>abs(-17)</></>
|
|
|
|
<entry><literal>17</></>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry><literal><function>debug(<replaceable>a</>)</></></>
|
|
|
|
<entry>same as <replaceable>a</> </>
|
|
|
|
<entry>print to <systemitem>stderr</systemitem> the given argument</>
|
|
|
|
<entry><literal>debug(5432)</></>
|
|
|
|
<entry><literal>5432</></>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry><literal><function>max(<replaceable>i</> [, <replaceable>...</> ] )</></></>
|
|
|
|
<entry>integer</>
|
|
|
|
<entry>maximum value</>
|
|
|
|
<entry><literal>max(5, 4, 3, 2)</></>
|
|
|
|
<entry><literal>5</></>
|
|
|
|
</row>
|
|
|
|
<row>
|
|
|
|
<entry><literal><function>min(<replaceable>i</> [, <replaceable>...</> ] )</></></>
|
|
|
|
<entry>integer</>
|
|
|
|
<entry>minimum value</>
|
|
|
|
<entry><literal>min(5, 4, 3, 2)</></>
|
|
|
|
<entry><literal>2</></>
|
|
|
|
</row>
|
|
|
|
</tbody>
|
|
|
|
</tgroup>
|
|
|
|
</table>
|
|
|
|
</refsect2>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Per-Transaction Logging</title>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
|
|
|
<para>
|
2013-01-31 07:53:58 +01:00
|
|
|
With the <option>-l</> option but without the <option>--aggregate-interval</option>,
|
|
|
|
<application>pgbench</> writes the time taken by each transaction
|
|
|
|
to a log file. The log file will be named
|
2010-03-23 05:09:17 +01:00
|
|
|
<filename>pgbench_log.<replaceable>nnn</></filename>, where
|
2015-09-11 03:22:21 +02:00
|
|
|
<replaceable>nnn</> is the PID of the <application>pgbench</application> process.
|
2012-05-09 19:39:53 +02:00
|
|
|
If the <option>-j</> option is 2 or higher, creating multiple worker
|
2010-03-23 05:09:17 +01:00
|
|
|
threads, each will have its own log file. The first worker will use the
|
2010-08-12 22:39:39 +02:00
|
|
|
same name for its log file as in the standard single worker case.
|
2010-03-23 05:09:17 +01:00
|
|
|
The additional log files for the other workers will be named
|
|
|
|
<filename>pgbench_log.<replaceable>nnn</>.<replaceable>mmm</></filename>,
|
|
|
|
where <replaceable>mmm</> is a sequential number for each worker starting
|
|
|
|
with 1.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The format of the log is:
|
|
|
|
|
2010-07-29 21:34:41 +02:00
|
|
|
<synopsis>
|
2014-10-13 19:25:56 +02:00
|
|
|
<replaceable>client_id</> <replaceable>transaction_no</> <replaceable>time</> <replaceable>file_no</> <replaceable>time_epoch</> <replaceable>time_us</> <optional><replaceable>schedule_lag</replaceable></optional>
|
2010-07-29 21:34:41 +02:00
|
|
|
</synopsis>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2010-08-12 22:39:39 +02:00
|
|
|
where <replaceable>time</> is the total elapsed transaction time in microseconds,
|
2010-03-23 05:09:17 +01:00
|
|
|
<replaceable>file_no</> identifies which script file was used
|
2012-05-09 19:39:53 +02:00
|
|
|
(useful when multiple scripts were specified with <option>-f</>),
|
2010-03-23 05:09:17 +01:00
|
|
|
and <replaceable>time_epoch</>/<replaceable>time_us</> are a
|
2015-09-11 03:22:21 +02:00
|
|
|
Unix epoch format time stamp and an offset
|
2014-08-30 17:52:36 +02:00
|
|
|
in microseconds (suitable for creating an ISO 8601
|
2015-09-11 03:22:21 +02:00
|
|
|
time stamp with fractional seconds) showing when
|
2014-10-13 19:25:56 +02:00
|
|
|
the transaction completed.
|
|
|
|
Field <replaceable>schedule_lag</> is the difference between the
|
|
|
|
transaction's scheduled start time, and the time it actually started, in
|
|
|
|
microseconds. It is only present when the <option>--rate</> option is used.
|
|
|
|
The last field <replaceable>skipped_transactions</> reports the number of
|
|
|
|
transactions skipped because they were too far behind schedule. It is only
|
|
|
|
present when both options <option>--rate</> and <option>--latency-limit</>
|
|
|
|
are used.
|
2010-03-23 05:09:17 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2014-10-13 19:25:56 +02:00
|
|
|
Here is a snippet of the log file generated:
|
2010-07-29 21:34:41 +02:00
|
|
|
<screen>
|
2010-03-23 05:09:17 +01:00
|
|
|
0 199 2241 0 1175850568 995598
|
|
|
|
0 200 2465 0 1175850568 998079
|
|
|
|
0 201 2513 0 1175850569 608
|
|
|
|
0 202 2038 0 1175850569 2663
|
2014-10-13 19:25:56 +02:00
|
|
|
</screen>
|
|
|
|
|
|
|
|
Another example with --rate=100 and --latency-limit=5 (note the additional
|
|
|
|
<replaceable>schedule_lag</> column):
|
|
|
|
<screen>
|
|
|
|
0 81 4621 0 1412881037 912698 3005
|
|
|
|
0 82 6173 0 1412881037 914578 4304
|
|
|
|
0 83 skipped 0 1412881037 914578 5217
|
|
|
|
0 83 skipped 0 1412881037 914578 5099
|
|
|
|
0 83 4722 0 1412881037 916203 3108
|
|
|
|
0 84 4142 0 1412881037 918023 2333
|
|
|
|
0 85 2465 0 1412881037 919759 740
|
|
|
|
</screen>
|
|
|
|
In this example, transaction 82 was late, because it's latency (6.173 ms) was
|
|
|
|
over the 5 ms limit. The next two transactions were skipped, because they
|
|
|
|
were already late before they were even started.
|
|
|
|
</para>
|
2012-10-03 14:37:42 +02:00
|
|
|
|
|
|
|
<para>
|
|
|
|
When running a long test on hardware that can handle a lot of transactions,
|
|
|
|
the log files can become very large. The <option>--sampling-rate</> option
|
|
|
|
can be used to log only a random sample of transactions.
|
|
|
|
</para>
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-03-23 05:09:17 +01:00
|
|
|
|
2013-01-31 07:53:58 +01:00
|
|
|
<refsect2>
|
|
|
|
<title>Aggregated Logging</title>
|
2015-03-03 05:28:31 +01:00
|
|
|
|
2013-01-31 07:53:58 +01:00
|
|
|
<para>
|
|
|
|
With the <option>--aggregate-interval</option> option, the logs use a bit different format:
|
|
|
|
|
|
|
|
<synopsis>
|
2014-10-13 19:25:56 +02:00
|
|
|
<replaceable>interval_start</> <replaceable>num_of_transactions</> <replaceable>latency_sum</> <replaceable>latency_2_sum</> <replaceable>min_latency</> <replaceable>max_latency</> <optional><replaceable>lag_sum</> <replaceable>lag_2_sum</> <replaceable>min_lag</> <replaceable>max_lag</> <optional><replaceable>skipped_transactions</></optional></optional>
|
2013-01-31 07:53:58 +01:00
|
|
|
</synopsis>
|
|
|
|
|
2015-09-11 03:22:21 +02:00
|
|
|
where <replaceable>interval_start</> is the start of the interval (Unix epoch
|
|
|
|
format time stamp), <replaceable>num_of_transactions</> is the number of transactions
|
2013-01-31 07:53:58 +01:00
|
|
|
within the interval, <replaceable>latency_sum</replaceable> is a sum of latencies
|
|
|
|
(so you can compute average latency easily). The following two fields are useful
|
|
|
|
for variance estimation - <replaceable>latency_sum</> is a sum of latencies and
|
|
|
|
<replaceable>latency_2_sum</> is a sum of 2nd powers of latencies. The last two
|
|
|
|
fields are <replaceable>min_latency</> - a minimum latency within the interval, and
|
|
|
|
<replaceable>max_latency</> - maximum latency within the interval. A transaction is
|
2014-10-13 19:25:56 +02:00
|
|
|
counted into the interval when it was committed. The fields in the end,
|
|
|
|
<replaceable>lag_sum</>, <replaceable>lag_2_sum</>, <replaceable>min_lag</>,
|
|
|
|
and <replaceable>max_lag</>, are only present if the <option>--rate</>
|
|
|
|
option is used. The very last one, <replaceable>skipped_transactions</>,
|
|
|
|
is only present if the option <option>--latency-limit</> is present, too.
|
2014-09-11 11:40:01 +02:00
|
|
|
They are calculated from the time each transaction had to wait for the
|
|
|
|
previous one to finish, i.e. the difference between each transaction's
|
|
|
|
scheduled start time and the time it actually started.
|
2013-01-31 07:53:58 +01:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Here is example outputs:
|
|
|
|
<screen>
|
|
|
|
1345828501 5601 1542744 483552416 61 2573
|
|
|
|
1345828503 7884 1979812 565806736 60 1479
|
|
|
|
1345828505 7208 1979422 567277552 59 1391
|
|
|
|
1345828507 7685 1980268 569784714 60 1398
|
|
|
|
1345828509 7073 1979779 573489941 236 1411
|
|
|
|
</screen></para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Notice that while the plain (unaggregated) log file contains index
|
|
|
|
of the custom script files, the aggregated log does not. Therefore if
|
|
|
|
you need per script data, you need to aggregate the data on your own.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
</refsect2>
|
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2>
|
2011-01-29 19:00:18 +01:00
|
|
|
<title>Per-Statement Latencies</title>
|
2010-08-12 22:39:39 +02:00
|
|
|
|
|
|
|
<para>
|
2012-05-09 19:39:53 +02:00
|
|
|
With the <option>-r</> option, <application>pgbench</> collects
|
2010-08-12 22:39:39 +02:00
|
|
|
the elapsed transaction time of each statement executed by every
|
|
|
|
client. It then reports an average of those values, referred to
|
|
|
|
as the latency for each statement, after the benchmark has finished.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For the default script, the output will look similar to this:
|
|
|
|
<screen>
|
|
|
|
starting vacuum...end.
|
2016-01-27 02:54:22 +01:00
|
|
|
transaction type: <builtin: TPC-B (sort of)>
|
2010-08-12 22:39:39 +02:00
|
|
|
scaling factor: 1
|
|
|
|
query mode: simple
|
|
|
|
number of clients: 10
|
|
|
|
number of threads: 1
|
|
|
|
number of transactions per client: 1000
|
|
|
|
number of transactions actually processed: 10000/10000
|
|
|
|
tps = 618.764555 (including connections establishing)
|
|
|
|
tps = 622.977698 (excluding connections establishing)
|
2016-01-27 02:54:22 +01:00
|
|
|
SQL script 1: <builtin: TPC-B (sort of)>
|
2016-02-01 15:55:33 +01:00
|
|
|
- 10000 transactions (100.0% of total, tps = 618.764555)
|
|
|
|
- latency average = 15.844 ms
|
|
|
|
- latency stddev = 2.715 ms
|
2016-01-27 02:54:22 +01:00
|
|
|
- statement latencies in milliseconds:
|
2010-08-12 22:39:39 +02:00
|
|
|
0.004386 \set nbranches 1 * :scale
|
|
|
|
0.001343 \set ntellers 10 * :scale
|
|
|
|
0.001212 \set naccounts 100000 * :scale
|
|
|
|
0.001310 \setrandom aid 1 :naccounts
|
|
|
|
0.001073 \setrandom bid 1 :nbranches
|
|
|
|
0.001005 \setrandom tid 1 :ntellers
|
|
|
|
0.001078 \setrandom delta -5000 5000
|
|
|
|
0.326152 BEGIN;
|
|
|
|
0.603376 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
|
|
|
|
0.454643 SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
|
|
|
|
5.528491 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
|
|
|
|
7.335435 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
|
|
|
|
0.371851 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
|
|
|
|
1.212976 END;
|
|
|
|
</screen>
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
If multiple script files are specified, the averages are reported
|
|
|
|
separately for each script file.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Note that collecting the additional timing information needed for
|
|
|
|
per-statement latency computation adds some overhead. This will slow
|
|
|
|
average execution speed and lower the computed TPS. The amount
|
|
|
|
of slowdown varies significantly depending on platform and hardware.
|
|
|
|
Comparing average TPS values with and without latency reporting enabled
|
|
|
|
is a good way to measure if the timing overhead is significant.
|
|
|
|
</para>
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
2010-08-12 22:39:39 +02:00
|
|
|
|
2012-05-09 19:39:53 +02:00
|
|
|
<refsect2>
|
2010-03-23 05:09:17 +01:00
|
|
|
<title>Good Practices</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It is very easy to use <application>pgbench</> to produce completely
|
|
|
|
meaningless numbers. Here are some guidelines to help you get useful
|
|
|
|
results.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
In the first place, <emphasis>never</> believe any test that runs
|
2012-05-09 19:39:53 +02:00
|
|
|
for only a few seconds. Use the <option>-t</> or <option>-T</> option
|
2010-03-23 05:09:17 +01:00
|
|
|
to make the run last at least a few minutes, so as to average out noise.
|
|
|
|
In some cases you could need hours to get numbers that are reproducible.
|
|
|
|
It's a good idea to try the test run a few times, to find out if your
|
|
|
|
numbers are reproducible or not.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
For the default TPC-B-like test scenario, the initialization scale factor
|
2012-05-09 19:39:53 +02:00
|
|
|
(<option>-s</>) should be at least as large as the largest number of
|
|
|
|
clients you intend to test (<option>-c</>); else you'll mostly be
|
|
|
|
measuring update contention. There are only <option>-s</> rows in
|
2010-03-23 05:09:17 +01:00
|
|
|
the <structname>pgbench_branches</> table, and every transaction wants to
|
2012-05-09 19:39:53 +02:00
|
|
|
update one of them, so <option>-c</> values in excess of <option>-s</>
|
2010-03-23 05:09:17 +01:00
|
|
|
will undoubtedly result in lots of transactions blocked waiting for
|
|
|
|
other transactions.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The default test scenario is also quite sensitive to how long it's been
|
|
|
|
since the tables were initialized: accumulation of dead rows and dead space
|
|
|
|
in the tables changes the results. To understand the results you must keep
|
|
|
|
track of the total number of updates and when vacuuming happens. If
|
|
|
|
autovacuum is enabled it can result in unpredictable changes in measured
|
|
|
|
performance.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
A limitation of <application>pgbench</> is that it can itself become
|
|
|
|
the bottleneck when trying to test a large number of client sessions.
|
|
|
|
This can be alleviated by running <application>pgbench</> on a different
|
|
|
|
machine from the database server, although low network latency will be
|
|
|
|
essential. It might even be useful to run several <application>pgbench</>
|
|
|
|
instances concurrently, on several client machines, against the same
|
|
|
|
database server.
|
|
|
|
</para>
|
2012-05-09 19:39:53 +02:00
|
|
|
</refsect2>
|
|
|
|
</refsect1>
|
|
|
|
</refentry>
|