pgbench

初始化选项

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

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

内置操作符

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

内置函数

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

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

Hash 函数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（详见失败和串行化/死锁重试）。

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

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 表指定表访问方法。环境变量PGOPTIONS用于指定通过命令行传递给 PostgreSQL 的数据库配置选项（见第 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使用非限定名称，并且不会更改搜索路径。