<!--
doc/src/sgml/ref/pgbench.sgml
PostgreSQL documentation
-->

<refentry id="pgbench">
 <indexterm zone="pgbench">
  <primary>pgbench</primary>
 </indexterm>

 <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>

 <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>
 <para>
  <application>pgbench</application> is a simple program for running benchmark
  tests on <productname>PostgreSQL</productname>.  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>,
  <command>UPDATE</command>, and <command>INSERT</command> commands per transaction.
  However, it is easy to test other cases by writing your own transaction
  script files.
 </para>

 <para>
  Typical output from <application>pgbench</application> looks like:

<screen>
transaction type: &lt;builtin: TPC-B (sort of)&gt;
scaling factor: 10
query mode: simple
number of clients: 10
number of threads: 1
maximum number of tries: 1
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
number of failed transactions: 0 (0.000%)
latency average = 11.013 ms
latency stddev = 7.351 ms
initial connection time = 45.758 ms
tps = 896.967014 (without initial connection time)
</screen>

  The first seven lines report some of the most important parameter
  settings.
  The sixth line reports the maximum number of tries for transactions with
  serialization or deadlock errors (see <xref linkend="failures-and-retries"/>
  for more information).
  The eighth 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
  failed before completion or some SQL command(s) failed.  (In
  <option>-T</option> mode, only the actual number of transactions is printed.)
  The next line reports the number of failed transactions due to
  serialization or deadlock errors (see <xref linkend="failures-and-retries"/>
  for more information).
  The last line reports the number of transactions per second.
 </para>

  <para>
   The default TPC-B-like transaction test requires specific tables to be
   set up beforehand.  <application>pgbench</application> should be invoked with
   the <option>-i</option> (initialize) option to create and populate these
   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:

<programlisting>
pgbench -i <optional> <replaceable>other-options</replaceable> </optional> <replaceable>dbname</replaceable>
</programlisting>

   where <replaceable>dbname</replaceable> is the name of the already-created
   database to test in.  (You may also need <option>-h</option>,
   <option>-p</option>, and/or <option>-U</option> options to specify how to
   connect to the database server.)
  </para>

  <caution>
   <para>
    <literal>pgbench -i</literal> creates four tables <structname>pgbench_accounts</structname>,
    <structname>pgbench_branches</structname>, <structname>pgbench_history</structname>,