初始化选项

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命令行选项预先设置的任何变量之外，还有一些被自动预先设置的变量，它们被列在表 282中。 一个用-D为这些变量值指定的值会优先于自动的预设值。 一旦被设置，可以在 SQL 命令中写:variablename来插入一个变量的值。 当运行多于一个客户端会话时，每一个会话拥有它自己的变量集合。 pgbench在一个语句中支持使用多达255个变量。

脚本文件元命令以反斜线（\）开始并且通常延伸到行的末尾，不过它们也能够通过写一个反斜线回车继续到额外行。一个元命令和它的参数用空白分隔。支持的元命令是：

内建操作符

表 283中列举的算数、按位、比较以及逻辑操作符都被编译到了pgbench中并且可以被用于\set中出现的表达式中。 运算符以升序排列。 除非另有说明，如果任一输入为双精度，则采用两个数字输入的运算符将产生双精度值，否则产生整数结果。

内建函数

表 284中列出的函数被编译在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开始编。

日志的格式是：

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 = 10.870 ms
latency stddev = 7.341 ms
initial connection time = 30.954 ms
tps = 907.949122 (without initial connection time)
statement latencies in milliseconds:
    0.001  \set aid random(1, 100000 * :scale)
    0.001  \set bid random(1, 1 * :scale)
    0.001  \set tid random(1, 10 * :scale)
    0.000  \set delta random(-5000, 5000)
    0.046  BEGIN;
    0.151  UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
    0.107  SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
    4.241  UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
    5.245  UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
    0.102  INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
    0.974  END;

如果指定了多个脚本文件，会为每一个脚本文件单独报告平均值。

注意为每个语句的延迟计算收集额外的时间信息会增加一些负荷。这将拖慢平均执行速度并且降低计算出的 TPS。降低的总量会很显著地依赖于平台和硬件。对比使用和不适用延迟报告时的平均 TPS 值是评估时间开销是否明显的好方法。

良好的做法

很容易使用pgbench产生完全没有意义的数字。这里有一些指导可以帮你得到有用的结果。

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

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

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

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

安全性

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