初始化选项

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 298 中。使用 -D 为这些变量指定的值优先于自动预设值。变量一旦被设置，就可以通过写 :variablename 把它的值插入到 SQL 命令中。运行多个客户端会话时，每个会话都有自己的一组变量。pgbench 在一条语句中最多支持 255 个变量引用。

脚本文件的元命令以反斜杠（\）开头，通常延伸到行尾，不过也可以通过书写反斜杠加换行把它们延续到后续的行。元命令的参数以空白分隔。支持以下元命令：

内建运算符

Table 299 中列出的算术、位运算、比较和逻辑运算符都内建于 pgbench，可以用在 \set 中出现的表达式里。这些运算符按优先级升序列出。除非另有说明，接受两个数字输入的运算符在任一输入为双精度时会产生双精度值，否则会产生整数结果。

内建函数

Table 300 中列出的函数都内建于 pgbench，可以用在 \set 中出现的表达式里。

random 函数使用均匀分布生成值，也就是说所有值都以相等的概率在指定范围内抽取。random_exponential、random_gaussian 和 random_zipfian 函数需要一个额外的双精度参数，由它决定分布的精确形状。

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

permute 接受一个输入值、一个大小和一个可选的种子参数。它生成 [0, size) 范围内整数的一个伪随机排列，并返回输入值在排列结果中的索引。如果未指定种子，所选的排列以 :default_seed 为默认的参数化种子。与哈希函数不同，permute 保证输出值中既没有冲突也没有空洞。区间之外的输入值按对大小取模来解释。如果大小不为正，该函数会引发错误。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 表指定 Table Access Method（表访问方法）。环境变量 PGOPTIONS 指定那些通过命令行传递给 PostgreSQL 的数据库配置选项（见 Section 19.1.4）。例如，假设 pgbench 所创建的表有一个名为 wuzza 的默认表访问方法，则可以这样指定它：

PGOPTIONS='-c default_table_access_method=wuzza'

良好实践

使用 pgbench 很容易产生完全无意义的数字。下面是一些可以帮助你获得有用结果的指导原则。

首先，千万不要相信任何只运行几秒钟的测试。使用 -t 或 -T 选项让运行至少持续几分钟，以便平均掉噪声。在某些情况下，可能需要几个小时才能得到可重现的数字。最好把测试运行多试几次，看看你的数字是否可以重现。

对于默认的类 TPC-B 测试场景，初始化比例因子（-s）至少应当与你打算测试的最大客户端数量（-c）一样大；否则你度量的将主要是更新争用。由于在只有 -s 行的 pgbench_branches 表中，每个事务都想要更新其中一行，因此 -c 值超过 -s 时无疑会导致大量事务被阻塞、等待其他事务。

默认的测试场景对表初始化后经过的时间也相当敏感：表中死元组和死空间的累积会改变结果。要理解结果，你必须跟踪更新的总数以及清理发生的时间。如果启用了自动清理，它可能导致度量到的性能发生不可预测的变化。

pgbench 的一个局限是，在试图测试大量客户端会话时，它本身可能成为瓶颈。可以通过在与数据库服务器不同的机器上运行 pgbench 来缓解这一问题，不过低网络延迟将是必不可少的。在多台客户端机器上并发运行多个 pgbench 实例来测试同一台数据库服务器，甚至也可能很有用。

安全

如果不受信任的用户可以访问一个尚未采用 secure schema usage pattern（安全的 schema 使用模式）的数据库，请不要在该数据库中运行 pgbench。pgbench 使用非限定名称，并且不会操纵搜索路径。