初始化选项

pgbench接受以下命令行初始化参数：

基准测试选项

pgbench接受以下命令行基准测试参数：

公共选项

pgbench 还接受以下用于连接参数及其他通用设置的命令行参数：

在pgbench中实际执行的“事务”是什么？

pgbench会从指定列表中随机选取测试脚本来执行。 这些脚本既可以是用-b指定的内置脚本，也可以是用-f指定的用户脚本。 每个脚本都可以在其后加上一个以@引出的相对权重，以改变其被选中的概率。 默认权重为1。权重为0的脚本会被忽略。

默认的内置事务脚本（也可通过-b tpcb-like调用）会针对随机选取的aid、 tid、bid和delta在每个事务中发出七条命令。 该场景受 TPC-B 基准启发，但并不是真正的 TPC-B，因此才取了这个名字。

如果选择simple-update内置脚本（也就是-N），事务中将不包含第 4 步和第 5 步。这会避免在这些表上发生更新争用，但也会让该测试场景更不像 TPC-B。

如果选择select-only内置脚本（也就是-S），则只执行SELECT。

自定义脚本

pgbench支持自定义基准测试场景：只需用从文件中读取的事务脚本（-f选项）替换默认事务脚本（见上文）即可。在这种情况下，一个“事务”就表示脚本文件的一次执行。

脚本文件包含一个或多个以分号结束的 SQL 命令。空行以及以--开头的行会被忽略。脚本文件还可以包含“元命令”，它们由pgbench自身解释，详见下文。

脚本文件提供了一种简单的变量替换机制。变量名必须由字母（包括非拉丁字母）、数字和下划线组成，并且首字符不能是数字。 如上所述，变量可以用命令行-D选项设置，也可以用下文介绍的元命令设置。 除了通过-D命令行选项预先设置的变量之外，还有少量变量会被自动预设，列在Table 300中。 如果使用-D为这些变量指定值，则会覆盖自动预设值。 一旦设置好变量，就可以在 SQL 命令中写:variablename来插入其值。 当运行多个客户端会话时，每个会话都有自己的变量集合。 pgbench在单条语句中最多支持 255 次变量使用。

脚本文件中的元命令以反斜线（\）开头，通常延伸到行尾，不过也可以通过写反斜线换行继续到后续行。元命令及其参数之间以空白分隔。支持的元命令如下：

内置操作符

Table 301中列出的算术、按位、比较和逻辑操作符都内置于pgbench中，可用于\set中的表达式。 这些操作符按优先级从低到高列出。除非另有说明，接受两个数字输入的操作符只要任一输入为双精度，就会产生双精度结果；否则产生整数结果。

内置函数

Table 302中列出的函数都内置于pgbench，可用于\set中的表达式。

random函数使用均匀分布生成值，也就是说，指定范围内的所有值都以相同概率被抽取。random_exponential、random_gaussian和random_zipfian函数则需要额外提供一个 double 参数，用来确定分布的精确形状。

哈希函数hash、hash_murmur2和hash_fnv1a都接受一个输入值和一个可选的种子参数。 如果没有提供种子，则会使用:default_seed的值；除非通过命令行-D选项覆盖，否则该值会被随机初始化。

permute接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size)内整数的伪随机排列，并返回输入值在该排列中的索引。如果未指定种子，则默认使用:default_seed。与哈希函数不同，permute保证输出值中不会出现冲突或空洞。区间之外的输入值会按size取模解释。如果size不是正数，该函数会报错。permute可用于打散诸如random_zipfian或random_exponential这类非均匀随机函数的分布，使那些更常抽到的值不再具有显而易见的相关性。例如，下面的pgbench脚本模拟了社交媒体和博客平台中一种可能的真实工作负载，其中少数账户会产生过量负载：

\set size 1000000
\set r random_zipfian(1, :size, 1.07)
\set k 1 + permute(:r, :size)

在某些情况下，需要若干彼此不相关的不同分布，这时可选种子参数就很有用：

\set k1 1 + permute(:r, :size, :default_seed + 123)
\set k2 1 + permute(:r, :size, :default_seed + 321)

也可以用hash近似实现类似的行为：

\set size 1000000
\set r random_zipfian(1, 100 * :size, 1.07)
\set k 1 + abs(hash(:r)) % :size

但是，由于hash会产生冲突，有些值将永远不可达，而另一些值则会比原始分布所预期的更常出现。

作为一个示例，内置的类 TPC-B 事务的全部定义是：

\set aid random(1, 100000 * :scale)
\set bid random(1, 1 * :scale)
\set tid random(1, 10 * :scale)
\set delta random(-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;

该脚本允许事务的每次迭代都引用不同的随机选中行。（这个示例也说明了为什么每个客户端会话都必须拥有自己的变量 — 否则它们就无法彼此独立地访问不同的行。）

逐事务日志记录

使用-l选项时（但未指定--aggregate-interval选项），pgbench会将每个事务的信息写入日志文件。日志文件名为prefix.nnn，其中prefix默认为pgbench_log，nnn是pgbench进程的 PID。可以用--log-prefix选项修改此前缀。如果-j选项为 2 或更大，即存在多个工作线程，则每个工作线程都有自己的日志文件。第一个工作线程的日志文件名与标准单工作线程情况相同。其他工作线程的附加日志文件名为prefix.nnn.mmm，其中mmm是每个工作线程从 1 开始的顺序编号。

每行日志文件描述一个事务。 它包含以下以空格分隔的字段：

当同时使用--rate和--latency-limit时， 跳过事务的time将被报告为skipped。 如果事务以失败结束，其time将被报告为failed。 如果使用--failures-detailed选项，失败事务的time会根据失败类型报告为serialization或deadlock（详见Failures and Serialization/Deadlock Retries）。

这里是在单个客户端运行中生成的一个日志文件的片段：

0 199 2241 0 1175850568 995598
0 200 2465 0 1175850568 998079
0 201 2513 0 1175850569 608
0 202 2038 0 1175850569 2663

另一个示例使用的是--rate=100以及--latency-limit=5（注意额外的 schedule_lag列）：

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

在这个示例中，事务 82 迟到了，因为它的延迟（6.173 ms）超过了 5 ms 限制。接下来的两个事务被跳过，因为它们在开始之前就已经迟到了。

以下示例显示了一个带有失败和重试的日志文件片段，最大尝试次数设置为10（请注意额外的retries列）：

3 0 47423 0 1499414498 34501 3
3 1 8333 0 1499414498 42848 0
3 2 8358 0 1499414498 51219 0
4 0 72345 0 1499414498 59433 6
1 3 41718 0 1499414498 67879 4
1 4 8416 0 1499414498 76311 0
3 3 33235 0 1499414498 84469 3
0 0 failed 0 1499414498 84905 9
2 0 failed 0 1499414498 86248 9
3 4 8307 0 1499414498 92788 0

如果使用--failures-detailed选项，失败的类型将在time中报告，如下所示：

3 0 47423 0 1499414498 34501 3
3 1 8333 0 1499414498 42848 0
3 2 8358 0 1499414498 51219 0
4 0 72345 0 1499414498 59433 6
1 3 41718 0 1499414498 67879 4
1 4 8416 0 1499414498 76311 0
3 3 33235 0 1499414498 84469 3
0 0 serialization 0 1499414498 84905 9
2 0 serialization 0 1499414498 86248 9
3 4 8307 0 1499414498 92788 0

在能够处理大量事务的硬件上运行长时间测试时，日志文件可能会变得非常大。可以使用--sampling-rate选项，仅记录事务的随机样本。

聚合日志记录

使用--aggregate-interval选项时，日志文件会采用不同的格式。每一行日志描述一个聚合时间间隔，包含以下以空格分隔的字段：

下面是使用该选项生成的示例输出：

pgbench --aggregate-interval=10 --time=20 --client=10 --log --rate=1000 --latency-limit=10 --failures-detailed --max-tries=10 test

1650260552 5178 26171317 177284491527 1136 44462 2647617 7321113867 0 9866 64 7564 28340 4148 0
1650260562 4808 25573984 220121792172 1171 62083 3037380 9666800914 0 9998 598 7392 26621 4527 0

请注意，普通（未聚合）日志格式会显示每个事务所使用的脚本，而聚合格式不会。因此，如果需要按脚本区分的数据，就必须自行聚合。

逐语句报告

使用-r选项，pgbench为每个语句收集以下统计信息：

报告仅在--max-tries选项不等于1时显示重试统计信息。

所有数值都是针对每个客户端执行的每条语句计算的，并在基准测试完成后报告。

对于默认脚本，输出将类似如下：

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 1
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%)
number of transactions above the 50.0 ms latency limit: 1311/10000 (13.110 %)
latency average = 28.488 ms
latency stddev = 21.009 ms
initial connection time = 69.068 ms
tps = 346.224794 (without initial connection time)
statement latencies in milliseconds and failures:
   0.012  0  \set aid random(1, 100000 * :scale)
   0.002  0  \set bid random(1, 1 * :scale)
   0.002  0  \set tid random(1, 10 * :scale)
   0.002  0  \set delta random(-5000, 5000)
   0.319  0  BEGIN;
   0.834  0  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
   0.641  0  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
  11.126  0  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
  12.961  0  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
   0.634  0  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
   1.957  0  END;

使用可串行化默认事务隔离级别的默认脚本的另一个输出示例 (PGOPTIONS='-c default_transaction_isolation=serializable' pgbench ...):

starting vacuum...end.
transaction type: <builtin: TPC-B (sort of)>
scaling factor: 1
query mode: simple
number of clients: 10
number of threads: 1
maximum number of tries: 10
number of transactions per client: 1000
number of transactions actually processed: 6317/10000
number of failed transactions: 3683 (36.830%)
number of transactions retried: 7667 (76.670%)
total number of retries: 45339
number of transactions above the 50.0 ms latency limit: 106/6317 (1.678 %)
latency average = 17.016 ms
latency stddev = 13.283 ms
initial connection time = 45.017 ms
tps = 186.792667 (without initial connection time)
statement latencies in milliseconds, failures and retries:
  0.006     0      0  \set aid random(1, 100000 * :scale)
  0.001     0      0  \set bid random(1, 1 * :scale)
  0.001     0      0  \set tid random(1, 10 * :scale)
  0.001     0      0  \set delta random(-5000, 5000)
  0.385     0      0  BEGIN;
  0.773     0      1  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
  0.624     0      0  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
  1.098   320   3762  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
  0.582  3363  41576  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
  0.465     0      0  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
  1.933     0      0  END;

如果指定了多个脚本文件，则会分别为每个脚本文件报告所有统计信息。

注意，为逐语句延迟计算收集额外的计时信息会带来一定开销。这会拖慢平均执行速度，并降低计算出的 TPS。减速幅度在很大程度上取决于平台和硬件。比较启用和未启用延迟报告时的平均 TPS 值，是判断这一计时开销是否显著的好方法。

失败和串行化/死锁重试

在执行pgbench时，有三种主要类型的错误：

客户端在发生严重错误时会中止运行；例如，与数据库服务器的连接丢失，或者脚本在最后一个事务尚未完成时就结束了。 另外，如果 SQL 或元命令执行失败，且原因不是串行化或死锁错误，客户端也会中止。 否则，如果 SQL 命令因串行化或死锁错误而失败，客户端不会中止。 在这种情况下，当前事务会回滚，也包括将客户端变量设置为此事务运行之前的状态 （假设一个事务脚本只包含一个事务；详见What Is the "Transaction" Actually Performed in pgbench?了解更多信息）。 发生串行化或死锁错误的事务会在回滚后重新执行，直到成功完成，或者达到最大尝试次数（由--max-tries指定）、达到最大重试时间（由--latency-limit指定），或者基准测试结束（由--time指定）。如果最后一次尝试仍然失败，该事务会被报告为失败，但客户端不会中止，而是继续工作。

成功事务的延迟包括事务执行的整个时间，包括回滚和重试。延迟仅针对成功的事务和命令进行测量，而不针对失败的事务或命令。

主报告包含失败事务的数量。如果--max-tries选项不等于 1，主报告还会包含与重试相关的统计信息：发生过重试的事务总数以及重试总次数。每个脚本报告都会继承主报告中的这些字段。逐语句报告仅在--max-tries选项不等于 1 时显示重试统计信息。

如果希望在逐事务日志、聚合日志以及主报告和逐脚本报告中按基本类型对失败进行分组，请使用--failures-detailed选项。如果还希望按类型区分所有错误和失败（即不会重试的错误），包括超出了哪一种重试限制，以及串行化/死锁失败超出了多少，请使用--verbose-errors选项。

表访问方法

可以为 pgbench 表指定表访问方法。环境变量PGOPTIONS用于指定通过命令行传递给 PostgreSQL 的数据库配置选项（见Section 19.1.4）。例如，可以用如下方式为 pgbench 创建的表指定一个名为wuzza的假想默认表访问方法：

PGOPTIONS='-c default_table_access_method=wuzza'

良好实践

很容易用pgbench得出完全没有意义的数字。下面给出一些有助于获得有用结果的准则。

首先，绝不要相信任何只运行了几秒钟的测试。使用-t或-T选项让测试至少持续几分钟，以便平滑掉噪声。在某些情况下，可能需要数小时才能得到可复现的结果。一个好做法是把同一测试运行几次，看看结果是否可复现。

对于默认的类 TPC-B 测试场景，初始化比例因子（-s）应至少与计划测试的最大客户端数（-c）一样大；否则，测到的主要将是更新争用。pgbench_branches表中只有-s行，而每个事务都要更新其中一行，因此-c超过-s时，必然会有大量事务阻塞等待其他事务。

默认测试场景还会对表初始化后的时间长短非常敏感：表中死元组和空闲空间的累积会改变结果。要理解这些结果，必须跟踪更新总数以及何时发生清理。如果启用了自动清理，它可能会给测得的性能带来不可预测的变化。

pgbench的一个局限是：在尝试测试大量客户端会话时，它自己也可能成为瓶颈。可以通过在与数据库服务器不同的机器上运行pgbench来缓解这一点，不过网络延迟必须足够低。甚至可以在多台客户端机器上同时运行多个pgbench实例，对同一台数据库服务器施压。

安全性

如果不可信用户能够访问尚未采用安全的模式使用模式的数据库，就不要在该数据库中运行pgbench。pgbench使用非限定名称，并且不会更改搜索路径。