初始化选项

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 命令行选项预先设置的变量之外，还有少量变量会被自动预设，列在表 288 中。如果使用 -D 为这些变量指定值，则会覆盖自动预设值。一旦设置好变量，就可以在 SQL 命令中写:variablename 来插入其值。当运行多个客户端会话时，每个会话都有自己的变量集合。pgbench 在单条语句中最多支持 255 次变量使用。

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

内置操作符

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

内置函数

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

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

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

permute 接受一个输入值、一个大小参数以及一个可选的种子参数。它会生成范围[0, size) 内整数的伪随机置换，并返回输入值在该置换中的索引。所选置换由种子参数决定；如果未指定种子，则默认使用:default_seed。与 hash 函数不同，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（详见失败和串行化/死锁重试）。

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

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 命令因串行化或死锁错误而失败，客户端不会中止。在这种情况下，当前事务会回滚，也包括将客户端变量设置为此事务运行之前的状态（假设一个事务脚本只包含一个事务；详见在 pgbench 中实际执行的“事务”是什么？了解更多信息）。发生串行化或死锁错误的事务会在回滚后重新执行，直到成功完成，或者达到最大尝试次数（由 --max-tries 指定）、达到最大重试时间（由 --latency-limit 指定），或者基准测试结束（由 --time 指定）。如果最后一次尝试仍然失败，该事务会被报告为失败，但客户端不会中止，而是继续工作。

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

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

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

良好实践

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

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

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

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

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

安全性

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