初始化选项

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

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

内置操作符

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

内置函数

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

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

Hash 函数 hash、hash_murmur2 和 hash_fnv1a 接受一个输入值和一个可选的种子参数。如果未提供种子，则使用 :default_seed 的值，该值随机初始化，除非通过命令行 -D 选项设置。Hash 函数可以用来打散随机函数的分布，例如 random_zipfian 或 random_exponential。例如，以下 pgbench 脚本模拟了社交媒体和博客平台中可能出现的典型真实工作负载，其中少数账户产生了过多的负载：

\set r random_zipfian(0, 100000000, 1.07)
\set k abs(hash(:r)) % 1000000

某些情况下需要几个彼此不相关的不同分布，这时隐式种子参数就能派上用场：

\set k1 abs(hash(:r, :default_seed + 123)) % 1000000
\set k2 abs(hash(:r, :default_seed + 321)) % 1000000

作为一个示例，内置的类 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 开始的顺序编号。

日志格式如下：

client_id transaction_no time script_no time_epoch time_us [ schedule_lag ]

其中，client_id 表示运行该事务的客户端会话，transaction_no 记录该会话已运行的事务数，time 是事务经过的总时间，单位为微秒，script_no 标识使用的脚本文件（在通过 -f 或 -b 指定多个脚本时很有用），而 time_epoch/time_us 分别是 Unix 纪元时间戳和以微秒计的偏移量（适合用来生成带小数秒的 ISO 8601 时间戳），表示事务完成的时间。schedule_lag 字段是事务计划开始时间与实际开始时间之间的差值，单位为微秒。它仅在使用 --rate 选项时出现。如果同时使用 --rate 和 --latency-limit，则被跳过事务的 time 将报告为 skipped。

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

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 限制。接下来的两个事务被跳过，因为它们在开始之前就已经迟到了。

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

聚合日志记录

使用 --aggregate-interval 选项时，日志文件采用另一种格式：

interval_start num_transactions​ sum_latency sum_latency_2 min_latency max_latency​ [ sum_lag sum_lag_2 min_lag max_lag [ skipped ] ]

其中，interval_start 是时间区间的开始时间（以 Unix 纪元时间戳表示），num_transactions 是区间内的事务数，sum_latency 是区间内事务延迟的总和，sum_latency_2 是区间内事务延迟的平方和，min_latency 是区间内的最小延迟，而 max_latency 是区间内的最大延迟。接下来的字段 sum_lag、sum_lag_2、min_lag 和 max_lag 仅在使用 --rate 选项时出现。它们提供各事务等待前一事务完成的时间统计，即各事务计划开始时间与实际开始时间之间的差值。最后一个字段 skipped 仅在还使用 --latency-limit 选项时出现。它记录因开始时间过晚而被跳过的事务数。每个事务都计入其提交时所在的时间区间。

下面是一些输出示例：

1345828501 5601 1542744 483552416 61 2573
1345828503 7884 1979812 565806736 60 1479
1345828505 7208 1979422 567277552 59 1391
1345828507 7685 1980268 569784714 60 1398
1345828509 7073 1979779 573489941 236 1411

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

逐语句延迟

使用 -r 选项时，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
number of transactions per client: 1000
number of transactions actually processed: 10000/10000
latency average = 15.844 ms
latency stddev = 2.715 ms
tps = 618.764555 (including connections establishing)
tps = 622.977698 (excluding connections establishing)
statement latencies in milliseconds:
        0.002  \set aid random(1, 100000 * :scale)
        0.005  \set bid random(1, 1 * :scale)
        0.002  \set tid random(1, 10 * :scale)
        0.001  \set delta random(-5000, 5000)
        0.326  BEGIN;
        0.603  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
        0.454  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
        5.528  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
        7.335  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
        0.371  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
        1.212  END;

如果指定了多个脚本文件，则会分别为每个脚本文件报告平均值。

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

良好实践

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

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

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

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

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

安全性

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