初始化选项

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_murmur2以及hash_fnv1a接受一个输入值和一个可选的种子参数。 在没有提供种子的情况下，会使用:default_seed的值，该变量会被随机地初始化，除非用命令行的-D 选项重载。

permute接受一个输入值，大小，和一个可选种子参数。 它生成范围在[0, size)的整数的伪随机排列，并返回排列值中的输入值的索引。 排列选择由种子参数化，默认为:default_seed，如果没有指定。 与hash函数不同，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产生完全没有意义的数字。这里有一些指导可以帮你得到有用的结果。

排在第一位的是，永远不要相信任何只运行了几秒的测试。使用-t或-T选项让运行持续至少几分钟，这样可以用平均值去掉噪声。在一些情况中，你可能需要数小时来得到能重现的数字。多运行几次测试是一个好主意，这样可以看看你的数字是不是可以重现。

对于默认的类 TPC-B 测试场景，初始化的比例因子（-s）应该至少和你想要测试的最大客户端数量一样大（-c），否则你将主要在度量更新争夺。在pgbench_branches表中只有-s行，并且每个事务都想更新其中之一，因此-c值超过-s将毫无疑问地导致大量事务被阻塞来等待其他事务。

默认的测试场景也对表被初始化了多久非常敏感：表中死亡行和死亡空间的累积会改变结果。要理解结果，你必须跟踪更新的总数以及何时发生清理。如果开启了自动清理，它可能会在度量的性能上产生不可预估的改变。

pgbench的一个限制是在尝试测试大量客户端会话时，它自身可能成为瓶颈。这可以通过在数据库服务器之外的一台机器上运行pgbench来缓解，不过必须是具有低网络延迟的机器。甚至可以在多个客户端机器上针对同一个数据库服务器并发地运行多个pgbench实例。

安全性

如果不可信用户能够访问没有采用安全方案使用模式的数据库，不要在那个数据库中运行pgbench。pgbench使用非限定名称并且不会操纵搜索路径。