1<!-- 2doc/src/sgml/ref/pgbench.sgml 3PostgreSQL documentation 4--> 5 6<refentry id="pgbench"> 7 <indexterm zone="pgbench"> 8 <primary>pgbench</primary> 9 </indexterm> 10 11 <refmeta> 12 <refentrytitle><application>pgbench</application></refentrytitle> 13 <manvolnum>1</manvolnum> 14 <refmiscinfo>Application</refmiscinfo> 15 </refmeta> 16 17 <refnamediv> 18 <refname>pgbench</refname> 19 <refpurpose>run a benchmark test on <productname>PostgreSQL</productname></refpurpose> 20 </refnamediv> 21 22 <refsynopsisdiv> 23 <cmdsynopsis> 24 <command>pgbench</command> 25 <arg choice="plain"><option>-i</option></arg> 26 <arg rep="repeat"><replaceable>option</replaceable></arg> 27 <arg choice="opt"><replaceable>dbname</replaceable></arg> 28 </cmdsynopsis> 29 <cmdsynopsis> 30 <command>pgbench</command> 31 <arg rep="repeat"><replaceable>option</replaceable></arg> 32 <arg choice="opt"><replaceable>dbname</replaceable></arg> 33 </cmdsynopsis> 34 </refsynopsisdiv> 35 36 <refsect1> 37 <title>Description</title> 38 <para> 39 <application>pgbench</application> is a simple program for running benchmark 40 tests on <productname>PostgreSQL</>. It runs the same sequence of SQL 41 commands over and over, possibly in multiple concurrent database sessions, 42 and then calculates the average transaction rate (transactions per second). 43 By default, <application>pgbench</application> tests a scenario that is 44 loosely based on TPC-B, involving five <command>SELECT</>, 45 <command>UPDATE</>, and <command>INSERT</> commands per transaction. 46 However, it is easy to test other cases by writing your own transaction 47 script files. 48 </para> 49 50 <para> 51 Typical output from <application>pgbench</application> looks like: 52 53<screen> 54transaction type: <builtin: TPC-B (sort of)> 55scaling factor: 10 56query mode: simple 57number of clients: 10 58number of threads: 1 59number of transactions per client: 1000 60number of transactions actually processed: 10000/10000 61tps = 85.184871 (including connections establishing) 62tps = 85.296346 (excluding connections establishing) 63</screen> 64 65 The first six lines report some of the most important parameter 66 settings. The next line reports the number of transactions completed 67 and intended (the latter being just the product of number of clients 68 and number of transactions per client); these will be equal unless the run 69 failed before completion. (In <option>-T</> mode, only the actual 70 number of transactions is printed.) 71 The last two lines report the number of transactions per second, 72 figured with and without counting the time to start database sessions. 73 </para> 74 75 <para> 76 The default TPC-B-like transaction test requires specific tables to be 77 set up beforehand. <application>pgbench</> should be invoked with 78 the <option>-i</> (initialize) option to create and populate these 79 tables. (When you are testing a custom script, you don't need this 80 step, but will instead need to do whatever setup your test needs.) 81 Initialization looks like: 82 83<programlisting> 84pgbench -i <optional> <replaceable>other-options</> </optional> <replaceable>dbname</> 85</programlisting> 86 87 where <replaceable>dbname</> is the name of the already-created 88 database to test in. (You may also need <option>-h</>, 89 <option>-p</>, and/or <option>-U</> options to specify how to 90 connect to the database server.) 91 </para> 92 93 <caution> 94 <para> 95 <literal>pgbench -i</> creates four tables <structname>pgbench_accounts</>, 96 <structname>pgbench_branches</>, <structname>pgbench_history</>, and 97 <structname>pgbench_tellers</>, 98 destroying any existing tables of these names. 99 Be very careful to use another database if you have tables having these 100 names! 101 </para> 102 </caution> 103 104 <para> 105 At the default <quote>scale factor</> of 1, the tables initially 106 contain this many rows: 107<screen> 108table # of rows 109--------------------------------- 110pgbench_branches 1 111pgbench_tellers 10 112pgbench_accounts 100000 113pgbench_history 0 114</screen> 115 You can (and, for most purposes, probably should) increase the number 116 of rows by using the <option>-s</> (scale factor) option. The 117 <option>-F</> (fillfactor) option might also be used at this point. 118 </para> 119 120 <para> 121 Once you have done the necessary setup, you can run your benchmark 122 with a command that doesn't include <option>-i</>, that is 123 124<programlisting> 125pgbench <optional> <replaceable>options</> </optional> <replaceable>dbname</> 126</programlisting> 127 128 In nearly all cases, you'll need some options to make a useful test. 129 The most important options are <option>-c</> (number of clients), 130 <option>-t</> (number of transactions), <option>-T</> (time limit), 131 and <option>-f</> (specify a custom script file). 132 See below for a full list. 133 </para> 134 </refsect1> 135 136 <refsect1> 137 <title>Options</title> 138 139 <para> 140 The following is divided into three subsections: Different options are used 141 during database initialization and while running benchmarks, some options 142 are useful in both cases. 143 </para> 144 145 <refsect2 id="pgbench-init-options"> 146 <title>Initialization Options</title> 147 148 <para> 149 <application>pgbench</application> accepts the following command-line 150 initialization arguments: 151 152 <variablelist> 153 154 <varlistentry> 155 <term><option>-i</option></term> 156 <term><option>--initialize</option></term> 157 <listitem> 158 <para> 159 Required to invoke initialization mode. 160 </para> 161 </listitem> 162 </varlistentry> 163 164 <varlistentry> 165 <term><option>-F</option> <replaceable>fillfactor</></term> 166 <term><option>--fillfactor=</option><replaceable>fillfactor</></term> 167 <listitem> 168 <para> 169 Create the <structname>pgbench_accounts</>, 170 <structname>pgbench_tellers</> and 171 <structname>pgbench_branches</> tables with the given fillfactor. 172 Default is 100. 173 </para> 174 </listitem> 175 </varlistentry> 176 177 <varlistentry> 178 <term><option>-n</option></term> 179 <term><option>--no-vacuum</option></term> 180 <listitem> 181 <para> 182 Perform no vacuuming after initialization. 183 </para> 184 </listitem> 185 </varlistentry> 186 187 <varlistentry> 188 <term><option>-q</option></term> 189 <term><option>--quiet</option></term> 190 <listitem> 191 <para> 192 Switch logging to quiet mode, producing only one progress message per 5 193 seconds. The default logging prints one message each 100000 rows, which 194 often outputs many lines per second (especially on good hardware). 195 </para> 196 </listitem> 197 </varlistentry> 198 199 <varlistentry> 200 <term><option>-s</option> <replaceable>scale_factor</></term> 201 <term><option>--scale=</option><replaceable>scale_factor</></term> 202 <listitem> 203 <para> 204 Multiply the number of rows generated by the scale factor. 205 For example, <literal>-s 100</> will create 10,000,000 rows 206 in the <structname>pgbench_accounts</> table. Default is 1. 207 When the scale is 20,000 or larger, the columns used to 208 hold account identifiers (<structfield>aid</structfield> columns) 209 will switch to using larger integers (<type>bigint</type>), 210 in order to be big enough to hold the range of account 211 identifiers. 212 </para> 213 </listitem> 214 </varlistentry> 215 216 <varlistentry> 217 <term><option>--foreign-keys</option></term> 218 <listitem> 219 <para> 220 Create foreign key constraints between the standard tables. 221 </para> 222 </listitem> 223 </varlistentry> 224 225 <varlistentry> 226 <term><option>--index-tablespace=<replaceable>index_tablespace</replaceable></option></term> 227 <listitem> 228 <para> 229 Create indexes in the specified tablespace, rather than the default 230 tablespace. 231 </para> 232 </listitem> 233 </varlistentry> 234 235 <varlistentry> 236 <term><option>--tablespace=<replaceable>tablespace</replaceable></option></term> 237 <listitem> 238 <para> 239 Create tables in the specified tablespace, rather than the default 240 tablespace. 241 </para> 242 </listitem> 243 </varlistentry> 244 245 <varlistentry> 246 <term><option>--unlogged-tables</option></term> 247 <listitem> 248 <para> 249 Create all tables as unlogged tables, rather than permanent tables. 250 </para> 251 </listitem> 252 </varlistentry> 253 254 </variablelist> 255 </para> 256 257 </refsect2> 258 259 <refsect2 id="pgbench-run-options"> 260 <title>Benchmarking Options</title> 261 262 <para> 263 <application>pgbench</application> accepts the following command-line 264 benchmarking arguments: 265 266 <variablelist> 267 <varlistentry> 268 <term><option>-b</> <replaceable>scriptname[@weight]</></term> 269 <term><option>--builtin</>=<replaceable>scriptname[@weight]</></term> 270 <listitem> 271 <para> 272 Add the specified built-in script to the list of scripts to be executed. 273 Available built-in scripts are: <literal>tpcb-like</literal>, 274 <literal>simple-update</literal> and <literal>select-only</literal>. 275 Unambiguous prefixes of built-in names are accepted. 276 With the special name <literal>list</literal>, show the list of built-in scripts 277 and exit immediately. 278 </para> 279 <para> 280 Optionally, write an integer weight after <literal>@</literal> to 281 adjust the probability of selecting this script versus other ones. 282 The default weight is 1. 283 See below for details. 284 </para> 285 </listitem> 286 </varlistentry> 287 288 289 <varlistentry> 290 <term><option>-c</option> <replaceable>clients</></term> 291 <term><option>--client=</option><replaceable>clients</></term> 292 <listitem> 293 <para> 294 Number of clients simulated, that is, number of concurrent database 295 sessions. Default is 1. 296 </para> 297 </listitem> 298 </varlistentry> 299 300 <varlistentry> 301 <term><option>-C</option></term> 302 <term><option>--connect</option></term> 303 <listitem> 304 <para> 305 Establish a new connection for each transaction, rather than 306 doing it just once per client session. 307 This is useful to measure the connection overhead. 308 </para> 309 </listitem> 310 </varlistentry> 311 312 <varlistentry> 313 <term><option>-d</option></term> 314 <term><option>--debug</option></term> 315 <listitem> 316 <para> 317 Print debugging output. 318 </para> 319 </listitem> 320 </varlistentry> 321 322 <varlistentry> 323 <term><option>-D</option> <replaceable>varname</><literal>=</><replaceable>value</></term> 324 <term><option>--define=</option><replaceable>varname</><literal>=</><replaceable>value</></term> 325 <listitem> 326 <para> 327 Define a variable for use by a custom script (see below). 328 Multiple <option>-D</> options are allowed. 329 </para> 330 </listitem> 331 </varlistentry> 332 333 <varlistentry> 334 <term><option>-f</> <replaceable>filename[@weight]</></term> 335 <term><option>--file=</><replaceable>filename[@weight]</></term> 336 <listitem> 337 <para> 338 Add a transaction script read from <replaceable>filename</replaceable> 339 to the list of scripts to be executed. 340 </para> 341 <para> 342 Optionally, write an integer weight after <literal>@</literal> to 343 adjust the probability of selecting this script versus other ones. 344 The default weight is 1. 345 (To use a script file name that includes an <literal>@</literal> 346 character, append a weight so that there is no ambiguity, for 347 example <literal>filen@me@1</literal>.) 348 See below for details. 349 </para> 350 </listitem> 351 </varlistentry> 352 353 <varlistentry> 354 <term><option>-j</option> <replaceable>threads</></term> 355 <term><option>--jobs=</option><replaceable>threads</></term> 356 <listitem> 357 <para> 358 Number of worker threads within <application>pgbench</application>. 359 Using more than one thread can be helpful on multi-CPU machines. 360 Clients are distributed as evenly as possible among available threads. 361 Default is 1. 362 </para> 363 </listitem> 364 </varlistentry> 365 366 <varlistentry> 367 <term><option>-l</option></term> 368 <term><option>--log</option></term> 369 <listitem> 370 <para> 371 Write information about each transaction to a log file. 372 See below for details. 373 </para> 374 </listitem> 375 </varlistentry> 376 377 <varlistentry> 378 <term><option>-L</option> <replaceable>limit</></term> 379 <term><option>--latency-limit=</option><replaceable>limit</></term> 380 <listitem> 381 <para> 382 Transactions that last more than <replaceable>limit</> milliseconds 383 are counted and reported separately, as <firstterm>late</>. 384 </para> 385 <para> 386 When throttling is used (<option>--rate=...</>), transactions that 387 lag behind schedule by more than <replaceable>limit</> ms, and thus 388 have no hope of meeting the latency limit, are not sent to the server 389 at all. They are counted and reported separately as 390 <firstterm>skipped</>. 391 </para> 392 </listitem> 393 </varlistentry> 394 395 <varlistentry> 396 <term><option>-M</option> <replaceable>querymode</></term> 397 <term><option>--protocol=</option><replaceable>querymode</></term> 398 <listitem> 399 <para> 400 Protocol to use for submitting queries to the server: 401 <itemizedlist> 402 <listitem> 403 <para><literal>simple</>: use simple query protocol.</para> 404 </listitem> 405 <listitem> 406 <para><literal>extended</>: use extended query protocol.</para> 407 </listitem> 408 <listitem> 409 <para><literal>prepared</>: use extended query protocol with prepared statements.</para> 410 </listitem> 411 </itemizedlist> 412 The default is simple query protocol. (See <xref linkend="protocol"> 413 for more information.) 414 </para> 415 </listitem> 416 </varlistentry> 417 418 <varlistentry> 419 <term><option>-n</option></term> 420 <term><option>--no-vacuum</option></term> 421 <listitem> 422 <para> 423 Perform no vacuuming before running the test. 424 This option is <emphasis>necessary</> 425 if you are running a custom test scenario that does not include 426 the standard tables <structname>pgbench_accounts</>, 427 <structname>pgbench_branches</>, <structname>pgbench_history</>, and 428 <structname>pgbench_tellers</>. 429 </para> 430 </listitem> 431 </varlistentry> 432 433 <varlistentry> 434 <term><option>-N</option></term> 435 <term><option>--skip-some-updates</option></term> 436 <listitem> 437 <para> 438 Run built-in simple-update script. 439 Shorthand for <option>-b simple-update</>. 440 </para> 441 </listitem> 442 </varlistentry> 443 444 <varlistentry> 445 <term><option>-P</option> <replaceable>sec</></term> 446 <term><option>--progress=</option><replaceable>sec</></term> 447 <listitem> 448 <para> 449 Show progress report every <replaceable>sec</> seconds. The report 450 includes the time since the beginning of the run, the tps since the 451 last report, and the transaction latency average and standard 452 deviation since the last report. Under throttling (<option>-R</>), 453 the latency is computed with respect to the transaction scheduled 454 start time, not the actual transaction beginning time, thus it also 455 includes the average schedule lag time. 456 </para> 457 </listitem> 458 </varlistentry> 459 460 <varlistentry> 461 <term><option>-r</option></term> 462 <term><option>--report-latencies</option></term> 463 <listitem> 464 <para> 465 Report the average per-statement latency (execution time from the 466 perspective of the client) of each command after the benchmark 467 finishes. See below for details. 468 </para> 469 </listitem> 470 </varlistentry> 471 472 <varlistentry> 473 <term><option>-R</option> <replaceable>rate</></term> 474 <term><option>--rate=</option><replaceable>rate</></term> 475 <listitem> 476 <para> 477 Execute transactions targeting the specified rate instead of running 478 as fast as possible (the default). The rate is given in transactions 479 per second. If the targeted rate is above the maximum possible rate, 480 the rate limit won't impact the results. 481 </para> 482 <para> 483 The rate is targeted by starting transactions along a 484 Poisson-distributed schedule time line. The expected start time 485 schedule moves forward based on when the client first started, not 486 when the previous transaction ended. That approach means that when 487 transactions go past their original scheduled end time, it is 488 possible for later ones to catch up again. 489 </para> 490 <para> 491 When throttling is active, the transaction latency reported at the 492 end of the run is calculated from the scheduled start times, so it 493 includes the time each transaction had to wait for the previous 494 transaction to finish. The wait time is called the schedule lag time, 495 and its average and maximum are also reported separately. The 496 transaction latency with respect to the actual transaction start time, 497 i.e., the time spent executing the transaction in the database, can be 498 computed by subtracting the schedule lag time from the reported 499 latency. 500 </para> 501 502 <para> 503 If <option>--latency-limit</> is used together with <option>--rate</>, 504 a transaction can lag behind so much that it is already over the 505 latency limit when the previous transaction ends, because the latency 506 is calculated from the scheduled start time. Such transactions are 507 not sent to the server, but are skipped altogether and counted 508 separately. 509 </para> 510 511 <para> 512 A high schedule lag time is an indication that the system cannot 513 process transactions at the specified rate, with the chosen number of 514 clients and threads. When the average transaction execution time is 515 longer than the scheduled interval between each transaction, each 516 successive transaction will fall further behind, and the schedule lag 517 time will keep increasing the longer the test run is. When that 518 happens, you will have to reduce the specified transaction rate. 519 </para> 520 </listitem> 521 </varlistentry> 522 523 <varlistentry> 524 <term><option>-s</option> <replaceable>scale_factor</></term> 525 <term><option>--scale=</option><replaceable>scale_factor</></term> 526 <listitem> 527 <para> 528 Report the specified scale factor in <application>pgbench</>'s 529 output. With the built-in tests, this is not necessary; the 530 correct scale factor will be detected by counting the number of 531 rows in the <structname>pgbench_branches</> table. 532 However, when testing only custom benchmarks (<option>-f</> option), 533 the scale factor will be reported as 1 unless this option is used. 534 </para> 535 </listitem> 536 </varlistentry> 537 538 <varlistentry> 539 <term><option>-S</option></term> 540 <term><option>--select-only</option></term> 541 <listitem> 542 <para> 543 Run built-in select-only script. 544 Shorthand for <option>-b select-only</>. 545 </para> 546 </listitem> 547 </varlistentry> 548 549 <varlistentry> 550 <term><option>-t</option> <replaceable>transactions</></term> 551 <term><option>--transactions=</option><replaceable>transactions</></term> 552 <listitem> 553 <para> 554 Number of transactions each client runs. Default is 10. 555 </para> 556 </listitem> 557 </varlistentry> 558 559 <varlistentry> 560 <term><option>-T</option> <replaceable>seconds</></term> 561 <term><option>--time=</option><replaceable>seconds</></term> 562 <listitem> 563 <para> 564 Run the test for this many seconds, rather than a fixed number of 565 transactions per client. <option>-t</option> and 566 <option>-T</option> are mutually exclusive. 567 </para> 568 </listitem> 569 </varlistentry> 570 571 <varlistentry> 572 <term><option>-v</option></term> 573 <term><option>--vacuum-all</option></term> 574 <listitem> 575 <para> 576 Vacuum all four standard tables before running the test. 577 With neither <option>-n</> nor <option>-v</>, <application>pgbench</application> will vacuum the 578 <structname>pgbench_tellers</> and <structname>pgbench_branches</> 579 tables, and will truncate <structname>pgbench_history</>. 580 </para> 581 </listitem> 582 </varlistentry> 583 584 <varlistentry> 585 <term><option>--aggregate-interval=<replaceable>seconds</></option></term> 586 <listitem> 587 <para> 588 Length of aggregation interval (in seconds). May be used only 589 with <option>-l</option> option. With this option, the log contains 590 per-interval summary data, as described below. 591 </para> 592 </listitem> 593 </varlistentry> 594 595 <varlistentry> 596 <term><option>--log-prefix=<replaceable>prefix</></option></term> 597 <listitem> 598 <para> 599 Set the filename prefix for the log files created by 600 <option>--log</>. The default is <literal>pgbench_log</>. 601 </para> 602 </listitem> 603 </varlistentry> 604 605 <varlistentry> 606 <term><option>--progress-timestamp</option></term> 607 <listitem> 608 <para> 609 When showing progress (option <option>-P</>), use a timestamp 610 (Unix epoch) instead of the number of seconds since the 611 beginning of the run. The unit is in seconds, with millisecond 612 precision after the dot. 613 This helps compare logs generated by various tools. 614 </para> 615 </listitem> 616 </varlistentry> 617 618 <varlistentry> 619 <term><option>--sampling-rate=<replaceable>rate</></option></term> 620 <listitem> 621 <para> 622 Sampling rate, used when writing data into the log, to reduce the 623 amount of log generated. If this option is given, only the specified 624 fraction of transactions are logged. 1.0 means all transactions will 625 be logged, 0.05 means only 5% of the transactions will be logged. 626 </para> 627 <para> 628 Remember to take the sampling rate into account when processing the 629 log file. For example, when computing tps values, you need to multiply 630 the numbers accordingly (e.g., with 0.01 sample rate, you'll only get 631 1/100 of the actual tps). 632 </para> 633 </listitem> 634 </varlistentry> 635 636 </variablelist> 637 </para> 638 639 </refsect2> 640 641 <refsect2 id="pgbench-common-options"> 642 <title>Common Options</title> 643 644 <para> 645 <application>pgbench</application> accepts the following command-line 646 common arguments: 647 648 <variablelist> 649 650 <varlistentry> 651 <term><option>-h</option> <replaceable>hostname</></term> 652 <term><option>--host=</option><replaceable>hostname</></term> 653 <listitem> 654 <para> 655 The database server's host name 656 </para> 657 </listitem> 658 </varlistentry> 659 660 <varlistentry> 661 <term><option>-p</option> <replaceable>port</></term> 662 <term><option>--port=</option><replaceable>port</></term> 663 <listitem> 664 <para> 665 The database server's port number 666 </para> 667 </listitem> 668 </varlistentry> 669 670 <varlistentry> 671 <term><option>-U</option> <replaceable>login</></term> 672 <term><option>--username=</option><replaceable>login</></term> 673 <listitem> 674 <para> 675 The user name to connect as 676 </para> 677 </listitem> 678 </varlistentry> 679 680 <varlistentry> 681 <term><option>-V</></term> 682 <term><option>--version</></term> 683 <listitem> 684 <para> 685 Print the <application>pgbench</application> version and exit. 686 </para> 687 </listitem> 688 </varlistentry> 689 690 <varlistentry> 691 <term><option>-?</></term> 692 <term><option>--help</></term> 693 <listitem> 694 <para> 695 Show help about <application>pgbench</application> command line 696 arguments, and exit. 697 </para> 698 </listitem> 699 </varlistentry> 700 </variablelist> 701 </para> 702 703 </refsect2> 704 </refsect1> 705 706 <refsect1> 707 <title>Notes</title> 708 709 <refsect2> 710 <title>What is the <quote>Transaction</> Actually Performed in <application>pgbench</application>?</title> 711 712 <para> 713 <application>pgbench</application> executes test scripts chosen randomly 714 from a specified list. 715 The scripts may include built-in scripts specified with <option>-b</option> 716 and user-provided scripts specified with <option>-f</option>. 717 Each script may be given a relative weight specified after an 718 <literal>@</literal> so as to change its selection probability. 719 The default weight is <literal>1</literal>. 720 Scripts with a weight of <literal>0</literal> are ignored. 721 </para> 722 723 <para> 724 The default built-in transaction script (also invoked with <option>-b tpcb-like</>) 725 issues seven commands per transaction over randomly chosen <literal>aid</>, 726 <literal>tid</>, <literal>bid</> and <literal>delta</>. 727 The scenario is inspired by the TPC-B benchmark, but is not actually TPC-B, 728 hence the name. 729 </para> 730 731 <orderedlist> 732 <listitem><para><literal>BEGIN;</literal></para></listitem> 733 <listitem><para><literal>UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;</literal></para></listitem> 734 <listitem><para><literal>SELECT abalance FROM pgbench_accounts WHERE aid = :aid;</literal></para></listitem> 735 <listitem><para><literal>UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;</literal></para></listitem> 736 <listitem><para><literal>UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;</literal></para></listitem> 737 <listitem><para><literal>INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);</literal></para></listitem> 738 <listitem><para><literal>END;</literal></para></listitem> 739 </orderedlist> 740 741 <para> 742 If you select the <literal>simple-update</> built-in (also <option>-N</>), 743 steps 4 and 5 aren't included in the transaction. 744 This will avoid update contention on these tables, but 745 it makes the test case even less like TPC-B. 746 </para> 747 748 <para> 749 If you select the <literal>select-only</> built-in (also <option>-S</>), 750 only the <command>SELECT</> is issued. 751 </para> 752 </refsect2> 753 754 <refsect2> 755 <title>Custom Scripts</title> 756 757 <para> 758 <application>pgbench</application> has support for running custom 759 benchmark scenarios by replacing the default transaction script 760 (described above) with a transaction script read from a file 761 (<option>-f</option> option). In this case a <quote>transaction</> 762 counts as one execution of a script file. 763 </para> 764 765 <para> 766 A script file contains one or more SQL commands terminated by 767 semicolons. Empty lines and lines beginning with 768 <literal>--</> are ignored. Script files can also contain 769 <quote>meta commands</>, which are interpreted by <application>pgbench</> 770 itself, as described below. 771 </para> 772 773 <note> 774 <para> 775 Before <productname>PostgreSQL</> 9.6, SQL commands in script files 776 were terminated by newlines, and so they could not be continued across 777 lines. Now a semicolon is <emphasis>required</> to separate consecutive 778 SQL commands (though a SQL command does not need one if it is followed 779 by a meta command). If you need to create a script file that works with 780 both old and new versions of <application>pgbench</>, be sure to write 781 each SQL command on a single line ending with a semicolon. 782 </para> 783 </note> 784 785 <para> 786 There is a simple variable-substitution facility for script files. 787 Variables can be set by the command-line <option>-D</> option, 788 explained above, or by the meta commands explained below. 789 In addition to any variables preset by <option>-D</> command-line options, 790 there are a few variables that are preset automatically, listed in 791 <xref linkend="pgbench-automatic-variables">. A value specified for these 792 variables using <option>-D</> takes precedence over the automatic presets. 793 Once set, a variable's 794 value can be inserted into a SQL command by writing 795 <literal>:</><replaceable>variablename</>. When running more than 796 one client session, each session has its own set of variables. 797 </para> 798 799 <table id="pgbench-automatic-variables"> 800 <title>Automatic Variables</title> 801 <tgroup cols="2"> 802 <thead> 803 <row> 804 <entry>Variable</entry> 805 <entry>Description</entry> 806 </row> 807 </thead> 808 809 <tbody> 810 <row> 811 <entry> <literal>scale</literal> </entry> 812 <entry>current scale factor</entry> 813 </row> 814 815 <row> 816 <entry> <literal>client_id</literal> </entry> 817 <entry>unique number identifying the client session (starts from zero)</entry> 818 </row> 819 </tbody> 820 </tgroup> 821 </table> 822 823 <para> 824 Script file meta commands begin with a backslash (<literal>\</>) and 825 normally extend to the end of the line, although they can be continued 826 to additional lines by writing backslash-return. 827 Arguments to a meta command are separated by white space. 828 These meta commands are supported: 829 </para> 830 831 <variablelist> 832 <varlistentry id='pgbench-metacommand-set'> 833 <term> 834 <literal>\set <replaceable>varname</> <replaceable>expression</></literal> 835 </term> 836 837 <listitem> 838 <para> 839 Sets variable <replaceable>varname</> to a value calculated 840 from <replaceable>expression</>. 841 The expression may contain integer constants such as <literal>5432</>, 842 double constants such as <literal>3.14159</>, 843 references to variables <literal>:</><replaceable>variablename</>, 844 unary operators (<literal>+</>, <literal>-</>) and binary operators 845 (<literal>+</>, <literal>-</>, <literal>*</>, <literal>/</>, 846 <literal>%</>) with their usual precedence and associativity, 847 <link linkend="pgbench-builtin-functions">function calls</>, and 848 parentheses. 849 </para> 850 851 <para> 852 Examples: 853<programlisting> 854\set ntellers 10 * :scale 855\set aid (1021 * random(1, 100000 * :scale)) % \ 856 (100000 * :scale) + 1 857</programlisting></para> 858 </listitem> 859 </varlistentry> 860 861 <varlistentry> 862 <term> 863 <literal>\sleep <replaceable>number</> [ us | ms | s ]</literal> 864 </term> 865 866 <listitem> 867 <para> 868 Causes script execution to sleep for the specified duration in 869 microseconds (<literal>us</>), milliseconds (<literal>ms</>) or seconds 870 (<literal>s</>). If the unit is omitted then seconds are the default. 871 <replaceable>number</> can be either an integer constant or a 872 <literal>:</><replaceable>variablename</> reference to a variable 873 having an integer value. 874 </para> 875 876 <para> 877 Example: 878<programlisting> 879\sleep 10 ms 880</programlisting></para> 881 </listitem> 882 </varlistentry> 883 884 <varlistentry> 885 <term> 886 <literal>\setshell <replaceable>varname</> <replaceable>command</> [ <replaceable>argument</> ... ]</literal> 887 </term> 888 889 <listitem> 890 <para> 891 Sets variable <replaceable>varname</> to the result of the shell command 892 <replaceable>command</> with the given <replaceable>argument</>(s). 893 The command must return an integer value through its standard output. 894 </para> 895 896 <para> 897 <replaceable>command</> and each <replaceable>argument</> can be either 898 a text constant or a <literal>:</><replaceable>variablename</> reference 899 to a variable. If you want to use an <replaceable>argument</> starting 900 with a colon, write an additional colon at the beginning of 901 <replaceable>argument</>. 902 </para> 903 904 <para> 905 Example: 906<programlisting> 907\setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon 908</programlisting></para> 909 </listitem> 910 </varlistentry> 911 912 <varlistentry> 913 <term> 914 <literal>\shell <replaceable>command</> [ <replaceable>argument</> ... ]</literal> 915 </term> 916 917 <listitem> 918 <para> 919 Same as <literal>\setshell</literal>, but the result of the command 920 is discarded. 921 </para> 922 923 <para> 924 Example: 925<programlisting> 926\shell command literal_argument :variable ::literal_starting_with_colon 927</programlisting></para> 928 </listitem> 929 </varlistentry> 930 </variablelist> 931 </refsect2> 932 933 <refsect2 id="pgbench-builtin-functions"> 934 <title>Built-In Functions</title> 935 936 <para> 937 The functions listed in <xref linkend="pgbench-functions"> are built 938 into <application>pgbench</> and may be used in expressions appearing in 939 <link linkend="pgbench-metacommand-set"><literal>\set</literal></link>. 940 </para> 941 942 <!-- list pgbench functions in alphabetical order --> 943 <table id="pgbench-functions"> 944 <title>pgbench Functions</title> 945 <tgroup cols="5"> 946 <thead> 947 <row> 948 <entry>Function</entry> 949 <entry>Return Type</entry> 950 <entry>Description</entry> 951 <entry>Example</entry> 952 <entry>Result</entry> 953 </row> 954 </thead> 955 <tbody> 956 <row> 957 <entry><literal><function>abs(<replaceable>a</>)</></></> 958 <entry>same as <replaceable>a</></> 959 <entry>absolute value</> 960 <entry><literal>abs(-17)</></> 961 <entry><literal>17</></> 962 </row> 963 <row> 964 <entry><literal><function>debug(<replaceable>a</>)</></></> 965 <entry>same as <replaceable>a</> </> 966 <entry>print <replaceable>a</> to <systemitem>stderr</systemitem>, 967 and return <replaceable>a</></> 968 <entry><literal>debug(5432.1)</></> 969 <entry><literal>5432.1</></> 970 </row> 971 <row> 972 <entry><literal><function>double(<replaceable>i</>)</></></> 973 <entry>double</> 974 <entry>cast to double</> 975 <entry><literal>double(5432)</></> 976 <entry><literal>5432.0</></> 977 </row> 978 <row> 979 <entry><literal><function>greatest(<replaceable>a</> [, <replaceable>...</> ] )</></></> 980 <entry>double if any <replaceable>a</> is double, else integer</> 981 <entry>largest value among arguments</> 982 <entry><literal>greatest(5, 4, 3, 2)</></> 983 <entry><literal>5</></> 984 </row> 985 <row> 986 <entry><literal><function>int(<replaceable>x</>)</></></> 987 <entry>integer</> 988 <entry>cast to int</> 989 <entry><literal>int(5.4 + 3.8)</></> 990 <entry><literal>9</></> 991 </row> 992 <row> 993 <entry><literal><function>least(<replaceable>a</> [, <replaceable>...</> ] )</></></> 994 <entry>double if any <replaceable>a</> is double, else integer</> 995 <entry>smallest value among arguments</> 996 <entry><literal>least(5, 4, 3, 2.1)</></> 997 <entry><literal>2.1</></> 998 </row> 999 <row> 1000 <entry><literal><function>pi()</></></> 1001 <entry>double</> 1002 <entry>value of the constant PI</> 1003 <entry><literal>pi()</></> 1004 <entry><literal>3.14159265358979323846</></> 1005 </row> 1006 <row> 1007 <entry><literal><function>random(<replaceable>lb</>, <replaceable>ub</>)</></></> 1008 <entry>integer</> 1009 <entry>uniformly-distributed random integer in <literal>[lb, ub]</></> 1010 <entry><literal>random(1, 10)</></> 1011 <entry>an integer between <literal>1</> and <literal>10</></> 1012 </row> 1013 <row> 1014 <entry><literal><function>random_exponential(<replaceable>lb</>, <replaceable>ub</>, <replaceable>parameter</>)</></></> 1015 <entry>integer</> 1016 <entry>exponentially-distributed random integer in <literal>[lb, ub]</>, 1017 see below</> 1018 <entry><literal>random_exponential(1, 10, 3.0)</></> 1019 <entry>an integer between <literal>1</> and <literal>10</></> 1020 </row> 1021 <row> 1022 <entry><literal><function>random_gaussian(<replaceable>lb</>, <replaceable>ub</>, <replaceable>parameter</>)</></></> 1023 <entry>integer</> 1024 <entry>Gaussian-distributed random integer in <literal>[lb, ub]</>, 1025 see below</> 1026 <entry><literal>random_gaussian(1, 10, 2.5)</></> 1027 <entry>an integer between <literal>1</> and <literal>10</></> 1028 </row> 1029 <row> 1030 <entry><literal><function>sqrt(<replaceable>x</>)</></></> 1031 <entry>double</> 1032 <entry>square root</> 1033 <entry><literal>sqrt(2.0)</></> 1034 <entry><literal>1.414213562</></> 1035 </row> 1036 </tbody> 1037 </tgroup> 1038 </table> 1039 1040 <para> 1041 The <literal>random</> function generates values using a uniform 1042 distribution, that is all the values are drawn within the specified 1043 range with equal probability. The <literal>random_exponential</> and 1044 <literal>random_gaussian</> functions require an additional double 1045 parameter which determines the precise shape of the distribution. 1046 </para> 1047 1048 <itemizedlist> 1049 <listitem> 1050 <para> 1051 For an exponential distribution, <replaceable>parameter</> 1052 controls the distribution by truncating a quickly-decreasing 1053 exponential distribution at <replaceable>parameter</>, and then 1054 projecting onto integers between the bounds. 1055 To be precise, with 1056<literallayout> 1057f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter)) 1058</literallayout> 1059 Then value <replaceable>i</> between <replaceable>min</> and 1060 <replaceable>max</> inclusive is drawn with probability: 1061 <literal>f(i) - f(i + 1)</>. 1062 </para> 1063 1064 <para> 1065 Intuitively, the larger the <replaceable>parameter</>, the more 1066 frequently values close to <replaceable>min</> are accessed, and the 1067 less frequently values close to <replaceable>max</> are accessed. 1068 The closer to 0 <replaceable>parameter</> is, the flatter (more 1069 uniform) the access distribution. 1070 A crude approximation of the distribution is that the most frequent 1% 1071 values in the range, close to <replaceable>min</>, are drawn 1072 <replaceable>parameter</>% of the time. 1073 The <replaceable>parameter</> value must be strictly positive. 1074 </para> 1075 </listitem> 1076 1077 <listitem> 1078 <para> 1079 For a Gaussian distribution, the interval is mapped onto a standard 1080 normal distribution (the classical bell-shaped Gaussian curve) truncated 1081 at <literal>-parameter</> on the left and <literal>+parameter</> 1082 on the right. 1083 Values in the middle of the interval are more likely to be drawn. 1084 To be precise, if <literal>PHI(x)</> is the cumulative distribution 1085 function of the standard normal distribution, with mean <literal>mu</> 1086 defined as <literal>(max + min) / 2.0</>, with 1087<literallayout> 1088f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) / 1089 (2.0 * PHI(parameter) - 1) 1090</literallayout> 1091 then value <replaceable>i</> between <replaceable>min</> and 1092 <replaceable>max</> inclusive is drawn with probability: 1093 <literal>f(i + 0.5) - f(i - 0.5)</>. 1094 Intuitively, the larger the <replaceable>parameter</>, the more 1095 frequently values close to the middle of the interval are drawn, and the 1096 less frequently values close to the <replaceable>min</> and 1097 <replaceable>max</> bounds. About 67% of values are drawn from the 1098 middle <literal>1.0 / parameter</>, that is a relative 1099 <literal>0.5 / parameter</> around the mean, and 95% in the middle 1100 <literal>2.0 / parameter</>, that is a relative 1101 <literal>1.0 / parameter</> around the mean; for instance, if 1102 <replaceable>parameter</> is 4.0, 67% of values are drawn from the 1103 middle quarter (1.0 / 4.0) of the interval (i.e., from 1104 <literal>3.0 / 8.0</> to <literal>5.0 / 8.0</>) and 95% from 1105 the middle half (<literal>2.0 / 4.0</>) of the interval (second and third 1106 quartiles). The minimum <replaceable>parameter</> is 2.0 for performance 1107 of the Box-Muller transform. 1108 </para> 1109 </listitem> 1110 </itemizedlist> 1111 1112 <para> 1113 As an example, the full definition of the built-in TPC-B-like 1114 transaction is: 1115 1116<programlisting> 1117\set aid random(1, 100000 * :scale) 1118\set bid random(1, 1 * :scale) 1119\set tid random(1, 10 * :scale) 1120\set delta random(-5000, 5000) 1121BEGIN; 1122UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; 1123SELECT abalance FROM pgbench_accounts WHERE aid = :aid; 1124UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; 1125UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; 1126INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); 1127END; 1128</programlisting> 1129 1130 This script allows each iteration of the transaction to reference 1131 different, randomly-chosen rows. (This example also shows why it's 1132 important for each client session to have its own variables — 1133 otherwise they'd not be independently touching different rows.) 1134 </para> 1135 1136 </refsect2> 1137 1138 <refsect2> 1139 <title>Per-Transaction Logging</title> 1140 1141 <para> 1142 With the <option>-l</> option (but without 1143 the <option>--aggregate-interval</option> option), 1144 <application>pgbench</> writes information about each transaction 1145 to a log file. The log file will be named 1146 <filename><replaceable>prefix</>.<replaceable>nnn</></filename>, 1147 where <replaceable>prefix</> defaults to <literal>pgbench_log</>, and 1148 <replaceable>nnn</> is the PID of the 1149 <application>pgbench</application> process. 1150 The prefix can be changed by using the <option>--log-prefix</> option. 1151 If the <option>-j</> option is 2 or higher, so that there are multiple 1152 worker threads, each will have its own log file. The first worker will 1153 use the same name for its log file as in the standard single worker case. 1154 The additional log files for the other workers will be named 1155 <filename><replaceable>prefix</>.<replaceable>nnn</>.<replaceable>mmm</></filename>, 1156 where <replaceable>mmm</> is a sequential number for each worker starting 1157 with 1. 1158 </para> 1159 1160 <para> 1161 The format of the log is: 1162 1163<synopsis> 1164<replaceable>client_id</> <replaceable>transaction_no</> <replaceable>time</> <replaceable>script_no</> <replaceable>time_epoch</> <replaceable>time_us</> <optional> <replaceable>schedule_lag</replaceable> </optional> 1165</synopsis> 1166 1167 where 1168 <replaceable>client_id</> indicates which client session ran the transaction, 1169 <replaceable>transaction_no</> counts how many transactions have been 1170 run by that session, 1171 <replaceable>time</> is the total elapsed transaction time in microseconds, 1172 <replaceable>script_no</> identifies which script file was used (useful when 1173 multiple scripts were specified with <option>-f</> or <option>-b</>), 1174 and <replaceable>time_epoch</>/<replaceable>time_us</> are a 1175 Unix-epoch time stamp and an offset 1176 in microseconds (suitable for creating an ISO 8601 1177 time stamp with fractional seconds) showing when 1178 the transaction completed. 1179 The <replaceable>schedule_lag</> field is the difference between the 1180 transaction's scheduled start time, and the time it actually started, in 1181 microseconds. It is only present when the <option>--rate</> option is used. 1182 When both <option>--rate</> and <option>--latency-limit</> are used, 1183 the <replaceable>time</> for a skipped transaction will be reported as 1184 <literal>skipped</>. 1185 </para> 1186 1187 <para> 1188 Here is a snippet of a log file generated in a single-client run: 1189<screen> 11900 199 2241 0 1175850568 995598 11910 200 2465 0 1175850568 998079 11920 201 2513 0 1175850569 608 11930 202 2038 0 1175850569 2663 1194</screen> 1195 1196 Another example with <literal>--rate=100</> 1197 and <literal>--latency-limit=5</> (note the additional 1198 <replaceable>schedule_lag</> column): 1199<screen> 12000 81 4621 0 1412881037 912698 3005 12010 82 6173 0 1412881037 914578 4304 12020 83 skipped 0 1412881037 914578 5217 12030 83 skipped 0 1412881037 914578 5099 12040 83 4722 0 1412881037 916203 3108 12050 84 4142 0 1412881037 918023 2333 12060 85 2465 0 1412881037 919759 740 1207</screen> 1208 In this example, transaction 82 was late, because its latency (6.173 ms) was 1209 over the 5 ms limit. The next two transactions were skipped, because they 1210 were already late before they were even started. 1211 </para> 1212 1213 <para> 1214 When running a long test on hardware that can handle a lot of transactions, 1215 the log files can become very large. The <option>--sampling-rate</> option 1216 can be used to log only a random sample of transactions. 1217 </para> 1218 </refsect2> 1219 1220 <refsect2> 1221 <title>Aggregated Logging</title> 1222 1223 <para> 1224 With the <option>--aggregate-interval</option> option, a different 1225 format is used for the log files: 1226 1227<synopsis> 1228<replaceable>interval_start</> <replaceable>num_transactions</> <replaceable>sum_latency</> <replaceable>sum_latency_2</> <replaceable>min_latency</> <replaceable>max_latency</> <optional> <replaceable>sum_lag</> <replaceable>sum_lag_2</> <replaceable>min_lag</> <replaceable>max_lag</> <optional> <replaceable>skipped</> </optional> </optional> 1229</synopsis> 1230 1231 where 1232 <replaceable>interval_start</> is the start of the interval (as a Unix 1233 epoch time stamp), 1234 <replaceable>num_transactions</> is the number of transactions 1235 within the interval, 1236 <replaceable>sum_latency</replaceable> is the sum of the transaction 1237 latencies within the interval, 1238 <replaceable>sum_latency_2</replaceable> is the sum of squares of the 1239 transaction latencies within the interval, 1240 <replaceable>min_latency</> is the minimum latency within the interval, 1241 and 1242 <replaceable>max_latency</> is the maximum latency within the interval. 1243 The next fields, 1244 <replaceable>sum_lag</>, <replaceable>sum_lag_2</>, <replaceable>min_lag</>, 1245 and <replaceable>max_lag</>, are only present if the <option>--rate</> 1246 option is used. 1247 They provide statistics about the time each transaction had to wait for the 1248 previous one to finish, i.e., the difference between each transaction's 1249 scheduled start time and the time it actually started. 1250 The very last field, <replaceable>skipped</>, 1251 is only present if the <option>--latency-limit</> option is used, too. 1252 It counts the number of transactions skipped because they would have 1253 started too late. 1254 Each transaction is counted in the interval when it was committed. 1255 </para> 1256 1257 <para> 1258 Here is some example output: 1259<screen> 12601345828501 5601 1542744 483552416 61 2573 12611345828503 7884 1979812 565806736 60 1479 12621345828505 7208 1979422 567277552 59 1391 12631345828507 7685 1980268 569784714 60 1398 12641345828509 7073 1979779 573489941 236 1411 1265</screen></para> 1266 1267 <para> 1268 Notice that while the plain (unaggregated) log file shows which script 1269 was used for each transaction, the aggregated log does not. Therefore if 1270 you need per-script data, you need to aggregate the data on your own. 1271 </para> 1272 1273 </refsect2> 1274 1275 <refsect2> 1276 <title>Per-Statement Latencies</title> 1277 1278 <para> 1279 With the <option>-r</> option, <application>pgbench</> collects 1280 the elapsed transaction time of each statement executed by every 1281 client. It then reports an average of those values, referred to 1282 as the latency for each statement, after the benchmark has finished. 1283 </para> 1284 1285 <para> 1286 For the default script, the output will look similar to this: 1287<screen> 1288starting vacuum...end. 1289transaction type: <builtin: TPC-B (sort of)> 1290scaling factor: 1 1291query mode: simple 1292number of clients: 10 1293number of threads: 1 1294number of transactions per client: 1000 1295number of transactions actually processed: 10000/10000 1296latency average = 15.844 ms 1297latency stddev = 2.715 ms 1298tps = 618.764555 (including connections establishing) 1299tps = 622.977698 (excluding connections establishing) 1300script statistics: 1301 - statement latencies in milliseconds: 1302 0.002 \set aid random(1, 100000 * :scale) 1303 0.005 \set bid random(1, 1 * :scale) 1304 0.002 \set tid random(1, 10 * :scale) 1305 0.001 \set delta random(-5000, 5000) 1306 0.326 BEGIN; 1307 0.603 UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid; 1308 0.454 SELECT abalance FROM pgbench_accounts WHERE aid = :aid; 1309 5.528 UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid; 1310 7.335 UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid; 1311 0.371 INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP); 1312 1.212 END; 1313</screen> 1314 </para> 1315 1316 <para> 1317 If multiple script files are specified, the averages are reported 1318 separately for each script file. 1319 </para> 1320 1321 <para> 1322 Note that collecting the additional timing information needed for 1323 per-statement latency computation adds some overhead. This will slow 1324 average execution speed and lower the computed TPS. The amount 1325 of slowdown varies significantly depending on platform and hardware. 1326 Comparing average TPS values with and without latency reporting enabled 1327 is a good way to measure if the timing overhead is significant. 1328 </para> 1329 </refsect2> 1330 1331 <refsect2> 1332 <title>Good Practices</title> 1333 1334 <para> 1335 It is very easy to use <application>pgbench</> to produce completely 1336 meaningless numbers. Here are some guidelines to help you get useful 1337 results. 1338 </para> 1339 1340 <para> 1341 In the first place, <emphasis>never</> believe any test that runs 1342 for only a few seconds. Use the <option>-t</> or <option>-T</> option 1343 to make the run last at least a few minutes, so as to average out noise. 1344 In some cases you could need hours to get numbers that are reproducible. 1345 It's a good idea to try the test run a few times, to find out if your 1346 numbers are reproducible or not. 1347 </para> 1348 1349 <para> 1350 For the default TPC-B-like test scenario, the initialization scale factor 1351 (<option>-s</>) should be at least as large as the largest number of 1352 clients you intend to test (<option>-c</>); else you'll mostly be 1353 measuring update contention. There are only <option>-s</> rows in 1354 the <structname>pgbench_branches</> table, and every transaction wants to 1355 update one of them, so <option>-c</> values in excess of <option>-s</> 1356 will undoubtedly result in lots of transactions blocked waiting for 1357 other transactions. 1358 </para> 1359 1360 <para> 1361 The default test scenario is also quite sensitive to how long it's been 1362 since the tables were initialized: accumulation of dead rows and dead space 1363 in the tables changes the results. To understand the results you must keep 1364 track of the total number of updates and when vacuuming happens. If 1365 autovacuum is enabled it can result in unpredictable changes in measured 1366 performance. 1367 </para> 1368 1369 <para> 1370 A limitation of <application>pgbench</> is that it can itself become 1371 the bottleneck when trying to test a large number of client sessions. 1372 This can be alleviated by running <application>pgbench</> on a different 1373 machine from the database server, although low network latency will be 1374 essential. It might even be useful to run several <application>pgbench</> 1375 instances concurrently, on several client machines, against the same 1376 database server. 1377 </para> 1378 </refsect2> 1379 <refsect2> 1380 <title>Security</title> 1381 1382 <para> 1383 If untrusted users have access to a database that has not adopted a 1384 <link linkend="ddl-schemas-patterns">secure schema usage pattern</link>, 1385 do not run <application>pgbench</application> in that 1386 database. <application>pgbench</application> uses unqualified names and 1387 does not manipulate the search path. 1388 </para> 1389 </refsect2> 1390 </refsect1> 1391</refentry> 1392