初始化选项

pgbench 接受以下命令行初始化参数：

基准测试选项

pgbench 接受以下命令行基准测试参数：

公共选项

pgbench 接受以下通用命令行参数：

在 pgbench 中实际执行的“事务”是什么？

默认的事务脚本在每个事务中发出七条命令：

如果指定-N，事务中将不包含第 4 步和第 5 步。如果指定-S，则只执行SELECT。

自定义脚本

pgbench支持自定义基准测试场景：只需用从文件中读取的事务脚本（-f选项）替换默认事务脚本（见上文）即可。在这种情况下，一个“事务”就表示脚本文件的一次执行。你甚至可以指定多个脚本（多个-f选项），此时每次客户端会话开始新事务时，都会从这些脚本中随机选择一个。

脚本文件的格式是每行一条 SQL 命令；不支持跨多行的 SQL 命令。空行以及以--开头的行会被忽略。脚本文件的行还可以是“元命令”，它们由pgbench自身解释，详见下文。

脚本文件提供了简单的变量替换功能。变量可以通过前面介绍的命令行-D选项设置，也可以通过下面介绍的元命令设置。除了由-D命令行选项预设的变量外，还有一些自动预设的变量，列于表 G.1中。使用-D为这些变量指定的值优先于自动预设值。设置变量后，就可以通过书写:variablename将变量值插入 SQL 命令。在运行多个客户端会话时，每个会话都有自己的一组变量。

脚本文件中的元命令以反斜线（\）开头。元命令的参数以空白分隔。支持的元命令如下：

作为一个示例，内置的类 TPC-B 事务的全部定义是：

\set nbranches :scale
\set ntellers 10 * :scale
\set naccounts 100000 * :scale
\setrandom aid 1 :naccounts
\setrandom bid 1 :nbranches
\setrandom tid 1 :ntellers
\setrandom delta -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会将每个事务所花的时间写入日志文件。日志文件名为pgbench_log.nnn，其中nnn是 pgbench 进程的 PID。如果-j选项为 2 或更高（从而创建多个工作线程），则每个工作线程都有自己的日志文件。第一个工作线程的日志文件名与标准单工作线程情况相同。其他工作线程的附加日志文件名为pgbench_log.nnn.mmm，其中mmm是每个工作线程从 1 开始的顺序编号。

日志格式如下：

client_id transaction_no time file_no time_epoch time_us [schedule_lag]

其中，time 是事务经过的总时间，单位为微秒， file_no 标识使用的脚本文件（在通过 -f 指定多个脚本时很有用），而 time_epoch/time_us 分别是 Unix 纪元格式的时间戳和以微秒计的偏移量（适合用来生成带小数秒的 ISO 8601 时间戳），表示事务完成的时间。 schedule_lag 字段是事务计划开始时间与实际开始时间之间的差值，单位为微秒。它仅在使用 --rate 选项时出现。

示例输出如下：

 0 199 2241 0 1175850568 995598
 0 200 2465 0 1175850568 998079
 0 201 2513 0 1175850569 608
 0 202 2038 0 1175850569 2663

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

聚合日志记录

使用 --aggregate-interval 选项时，日志使用的格式略有不同：

interval_start num_of_transactions latency_sum latency_2_sum min_latency max_latency [lag_sum lag_2_sum min_lag max_lag]

其中，interval_start 是时间区间的开始时间（Unix 纪元格式时间戳）， num_of_transactions 是区间内的事务数， latency_sum 是延迟的总和（这样你可以方便地计算平均延迟）。 接下来的两个字段可用于方差估计——latency_sum 是延迟的总和， 而latency_2_sum 是延迟的平方和。再接下来的两个字段是 min_latency（区间内的最小延迟）和 max_latency（区间内的最大延迟）。事务在提交时计入其所在的时间区间。 最后四个字段lag_sum、lag_2_sum、 min_lag和max_lag仅在使用--rate选项时出现。 它们根据各事务等待前一事务完成的时间计算，即各事务计划开始时间与实际开始时间之间的差值。

下面是输出示例：

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: 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
tps = 618.764555 (including connections establishing)
tps = 622.977698 (excluding connections establishing)
statement latencies in milliseconds:
        0.004386        \set nbranches 1 * :scale
        0.001343        \set ntellers 10 * :scale
        0.001212        \set naccounts 100000 * :scale
        0.001310        \setrandom aid 1 :naccounts
        0.001073        \setrandom bid 1 :nbranches
        0.001005        \setrandom tid 1 :ntellers
        0.001078        \setrandom delta -5000 5000
        0.326152        BEGIN;
        0.603376        UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid;
        0.454643        SELECT abalance FROM pgbench_accounts WHERE aid = :aid;
        5.528491        UPDATE pgbench_tellers SET tbalance = tbalance + :delta WHERE tid = :tid;
        7.335435        UPDATE pgbench_branches SET bbalance = bbalance + :delta WHERE bid = :bid;
        0.371851        INSERT INTO pgbench_history (tid, bid, aid, delta, mtime) VALUES (:tid, :bid, :aid, :delta, CURRENT_TIMESTAMP);
        1.212976        END;

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

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

良好实践

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

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

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

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

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

安全性

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