pgbench — 在 PostgreSQL 上运行基准测试
pgbench -i [选项...] [数据库名]
pgbench [选项...] [数据库名]
pgbench 是一个用于在 PostgreSQL 上运行基准测试的简单程序。它重复运行相同的 SQL 命令序列，可能在多个并发数据库会话中运行，然后计算平均事务速率（每秒事务数）。默认情况下，pgbench 测试一个松散地基于 TPC-B 的场景，每个事务涉及五个 SELECT、UPDATE 和 INSERT 命令。但是，通过编写您自己的事务脚本文件，可以轻松测试其他情况。
pgbench 的典型输出如下所示
transaction type: <builtin: TPC-B (sort of)> scaling factor: 10 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%) latency average = 11.013 ms latency stddev = 7.351 ms initial connection time = 45.758 ms tps = 896.967014 (without initial connection time)
前七行报告了一些最重要的参数设置。第六行报告了事务在出现序列化或死锁错误时尝试的最大次数（有关更多信息，请参阅失败和序列化/死锁重试）。第八行报告已完成和预期的事务数（后者只是客户端数和每个客户端事务数的乘积）；除非运行在完成前失败或某些 SQL 命令失败，否则它们将相等。（在 -T 模式下，仅打印实际的事务数。）下一行报告由于序列化或死锁错误而导致的事务失败数（有关更多信息，请参阅失败和序列化/死锁重试）。最后一行报告每秒事务数。
默认的类 TPC-B 事务测试需要预先设置特定的表。pgbench 应使用 -i（初始化）选项调用以创建和填充这些表。（当您正在测试自定义脚本时，不需要此步骤，而是需要执行测试所需的任何设置。）初始化如下所示
pgbench -i [other-options]dbname
其中 数据库名 是要测试的已创建数据库的名称。（您可能还需要 -h、-p 和/或 -U 选项来指定如何连接到数据库服务器。）
pgbench -i 创建四个表 pgbench_accounts、pgbench_branches、pgbench_history 和 pgbench_tellers，并销毁任何现有同名表。如果您有同名表，请务必使用另一个数据库！
在默认的 “扩展因子” 为 1 时，表最初包含以下行数
table # of rows --------------------------------- pgbench_branches 1 pgbench_tellers 10 pgbench_accounts 100000 pgbench_history 0
您可以（并且出于大多数目的，可能应该）使用 -s（扩展因子）选项来增加行数。-F（填充因子）选项也可以在此处使用。
完成必要的设置后，您可以使用不包含 -i 的命令运行基准测试，即
pgbench [options]dbname
在几乎所有情况下，您都需要一些选项来进行有用的测试。最重要的选项是 -c（客户端数）、-t（事务数）、-T（时间限制）和 -f（指定自定义脚本文件）。有关完整列表，请参见下文。
以下内容分为三个小节。在数据库初始化和运行基准测试期间使用了不同的选项，但某些选项在这两种情况下都很有用。
pgbench 接受以下命令行初始化参数
[-d] 数据库名[--dbname=]数据库名 #指定要测试的数据库的名称。如果未指定，则使用环境变量 PGDATABASE。如果未设置，则使用为连接指定的用户名。
-i--initialize #需要调用初始化模式。
-I 初始化步骤--init-steps=初始化步骤 #仅执行选定的正常初始化步骤集。初始化步骤 使用每个步骤一个字符来指定要执行的初始化步骤。每个步骤都按指定的顺序调用。默认值为 dtgvp。可用的步骤如下
d (删除) #删除任何现有的 pgbench 表。
t (创建表) #创建标准 pgbench 场景使用的表，即 pgbench_accounts、pgbench_branches、pgbench_history 和 pgbench_tellers。
g 或 G (生成数据，客户端或服务器端) #生成数据并将其加载到标准表中，替换任何已存在的数据。
使用 g（客户端数据生成），数据在 pgbench 客户端中生成，然后发送到服务器。这通过 COPY 大量使用客户端/服务器带宽。pgbench 使用版本 14 或更高版本的 PostgreSQL 中的 FREEZE 选项来加快随后的 VACUUM，但如果启用了分区，则在 pgbench_accounts 表上除外。使用 g 会导致日志在为所有表生成数据时每 100,000 行打印一条消息。
使用 G（服务器端数据生成），只有少量查询从 pgbench 客户端发送，然后数据实际上在服务器中生成。此变体不需要大量的带宽，但服务器将执行更多工作。使用 G 会导致日志在生成数据时不打印任何进度消息。
默认初始化行为使用客户端数据生成（等效于 g）。
v (真空) #在标准表上调用 VACUUM。
p (创建主键) #在标准表上创建主键索引。
f (创建外键) #在标准表之间创建外键约束。（请注意，此步骤不是默认执行的。）
-F 填充因子--fillfactor=填充因子 #使用给定的填充因子创建 pgbench_accounts、pgbench_tellers 和 pgbench_branches 表。默认值为 100。
-n--no-vacuum #在初始化期间不执行任何真空操作。（此选项即使在 -I 中指定了 v 初始化步骤，也会抑制该步骤。）
-q--quiet #将日志切换到静默模式，每 5 秒仅生成一条进度消息。默认日志记录每 100,000 行打印一条消息，这通常每秒输出多行（尤其是在良好的硬件上）。
如果在 -I 中指定了 G，则此设置无效。
-s 扩展因子--scale=扩展因子 #将生成的行的数量乘以扩展因子。例如，-s 100 将在 pgbench_accounts 表中创建 10,000,000 行。默认值为 1。当扩展因子为 20,000 或更大时，用于保存帐户标识符（aid 列）的列将切换为使用更大的整数（bigint），以便能够容纳帐户标识符的范围。
--foreign-keys #在标准表之间创建外键约束。（此选项会将 f 步骤添加到初始化步骤序列中，如果它尚不存在。）
--index-tablespace=索引表空间 #在指定的表空间中创建索引，而不是默认表空间。
--partition-method=名称 #使用 名称 方法创建分区 pgbench_accounts 表。预期值为 range 或 hash。此选项要求 --partitions 设置为非零值。如果未指定，则默认为 range。
--partitions=数字 #为扩展的帐户数量创建具有几乎相等大小的 数字 个分区的 pgbench_accounts 表。默认值为 0，表示不进行分区。
--tablespace=表空间 #在指定的表空间中创建表，而不是默认表空间。
--unlogged-tables #将所有表创建为非日志表，而不是永久表。
pgbench 接受以下命令行基准测试参数
-b scriptname[@weight]--builtin=scriptname[@weight] #将指定的内置脚本添加到要执行的脚本列表中。可用的内置脚本有：tpcb-like、simple-update 和 select-only。接受内置名称的无歧义前缀。使用特殊名称 list，显示内置脚本列表并立即退出。
可选地，在 @ 后面写一个整数权重，以调整选择此脚本相对于其他脚本的概率。默认权重为 1。有关详细信息，请参见下文。
-c clients--client=clients #模拟的客户端数量，即并发数据库会话的数量。默认为 1。
-C--connect #为每个事务建立一个新连接，而不是每个客户端会话只建立一次。这对于测量连接开销很有用。
-D varname=value--define=varname=value #定义一个变量供自定义脚本使用（见下文）。允许多个 -D 选项。
-f filename[@weight]--file=filename[@weight] #将从 filename 读取的事务脚本添加到要执行的脚本列表中。
可选地，在 @ 后面写一个整数权重，以调整选择此脚本相对于其他脚本的概率。默认权重为 1。（要使用包含 @ 字符的脚本文件名，请附加一个权重以避免歧义，例如 filen@me@1。）有关详细信息，请参见下文。
-j threads--jobs=threads #在 pgbench 中的工作线程数。在多 CPU 机器上使用多个线程可能会有所帮助。客户端尽可能均匀地分布在可用线程之间。默认为 1。
-l--log #将每个事务的信息写入日志文件。有关详细信息，请参见下文。
-L limit--latency-limit=limit #持续时间超过 limit 毫秒的事务将被单独计数和报告，作为 延迟。
当使用节流时 (--rate=...)，如果事务落后于计划超过 limit 毫秒，并且因此无法满足延迟限制，则根本不会将其发送到服务器。它们将被单独计数和报告为 跳过。
当使用 --max-tries 选项时，如果由于序列化异常或死锁而导致事务失败，则如果所有尝试的总时间大于 limit 毫秒，则不会重试该事务。要仅限制尝试的时间而不是尝试次数，请使用 --max-tries=0。默认情况下，选项 --max-tries 设置为 1，并且不会重试发生序列化/死锁错误的事务。有关重试此类事务的更多信息，请参阅 失败和序列化/死锁重试。
-M querymode--protocol=querymode #用于向服务器提交查询的协议
simple：使用简单查询协议。
extended：使用扩展查询协议。
prepared：使用带有预准备语句的扩展查询协议。
在 prepared 模式下，pgbench 从第二次查询迭代开始重用解析分析结果，因此 pgbench 的运行速度比其他模式快。
默认为简单查询协议。（有关更多信息，请参阅 第 53 章。）
-n--no-vacuum #在运行测试之前不执行 vacuum 操作。如果您正在运行不包含标准表 pgbench_accounts、pgbench_branches、pgbench_history 和 pgbench_tellers 的自定义测试场景，则此选项 必要。
-N--skip-some-updates #运行内置的 simple-update 脚本。是 -b simple-update 的简写。
-P sec--progress=sec #每隔 sec 秒显示进度报告。该报告包括运行开始以来的时间、上次报告以来的 TPS 以及事务延迟的平均值、标准差和上次报告以来的失败事务数。在节流 (-R) 下，延迟是相对于事务计划开始时间计算的，而不是相对于实际事务开始时间计算的，因此它还包括平均计划延迟时间。当使用 --max-tries 启用序列化/死锁错误后的事务重试时，报告将包含重试事务的数量以及所有重试的总和。
-r--report-per-command #在基准测试完成后，为每个命令报告以下统计信息：每个语句的平均延迟（从客户端的角度来看的执行时间）、失败次数以及在此命令中序列化或死锁错误后的重试次数。仅当 --max-tries 选项不等于 1 时，报告才会显示重试统计信息。
-R rate--rate=rate #执行事务以针对指定的速率，而不是尽可能快地运行（默认值）。速率以每秒事务数给出。如果目标速率高于最大可能速率，则速率限制不会影响结果。
通过沿着泊松分布的计划时间线启动事务来实现目标速率。预期开始时间计划根据客户端首次启动的时间向前推进，而不是根据上一个事务结束的时间向前推进。这种方法意味着，当事务超过其最初的计划结束时间时，以后的事务可能再次赶上。
当节流处于活动状态时，在运行结束时报告的事务延迟是从计划开始时间计算的，因此它包括每个事务必须等待前一个事务完成的时间。等待时间称为计划延迟时间，并且还会分别报告其平均值和最大值。相对于实际事务开始时间的事务延迟，即在数据库中执行事务所花费的时间，可以通过从报告的延迟中减去计划延迟时间来计算。
如果将 --latency-limit 与 --rate 一起使用，则事务可能会滞后太多，以至于在上一个事务结束时已经超过了延迟限制，因为延迟是从计划开始时间计算的。此类事务不会发送到服务器，而是完全跳过并单独计数。
较高的计划延迟时间表明系统无法以指定的速率处理事务，并且选择了客户端和线程数量。当平均事务执行时间长于每个事务之间计划的时间间隔时，每个后续事务将进一步落后，并且计划延迟时间将随着测试运行时间的延长而持续增加。发生这种情况时，您将需要降低指定的事务速率。
-s scale_factor--scale=scale_factor #在 pgbench 的输出中报告指定的比例因子。对于内置测试，这不是必需的；通过计算 pgbench_branches 表中的行数可以检测到正确的比例因子。但是，当仅测试自定义基准测试 (-f 选项) 时，除非使用此选项，否则比例因子将报告为 1。
-S--select-only #运行内置的 select-only 脚本。是 -b select-only 的简写。
-t transactions--transactions=transactions #每个客户端运行的事务数。默认为 10。
-T seconds--time=seconds #运行测试持续这么多秒，而不是每个客户端运行固定数量的事务。-t 和 -T 是互斥的。
-v--vacuum-all #在运行测试之前 vacuum 所有四个标准表。如果没有 -n 或 -v，pgbench 将 vacuum pgbench_tellers 和 pgbench_branches 表，并将截断 pgbench_history。
--aggregate-interval=seconds #聚合间隔的长度（以秒为单位）。只能与 -l 选项一起使用。使用此选项，日志将包含每个间隔的汇总数据，如下所述。
--exit-on-abort #当任何客户端由于某些错误而中止时，立即退出。如果没有此选项，即使客户端中止，其他客户端仍会根据 -t 或 -T 选项继续运行，并且在这种情况下，pgbench 将打印不完整的结果。
请注意，序列化失败或死锁失败不会中止客户端，因此不受此选项的影响。有关更多信息，请参阅故障和序列化/死锁重试。
--failures-detailed #在每个事务和聚合日志中报告故障，以及在主报告和每个脚本报告中报告故障，并按以下类型分组
序列化失败；
死锁失败；
有关更多信息，请参阅故障和序列化/死锁重试。
--log-prefix=prefix #设置由 --log 创建的日志文件的名称前缀。默认值为 pgbench_log。
--max-tries=number_of_tries #启用对具有序列化/死锁错误的事务进行重试，并设置这些重试的最大次数。此选项可以与 --latency-limit 选项结合使用，该选项限制所有事务重试的总时间；此外，如果不使用 --latency-limit 或 --time，则不能使用无限次重试 (--max-tries=0)。默认值为 1，并且不会重试具有序列化/死锁错误的事务。有关重试此类事务的更多信息，请参阅故障和序列化/死锁重试。
--progress-timestamp #在显示进度（选项 -P）时，使用时间戳（Unix纪元）而不是自运行开始以来的秒数。单位为秒，小数点后为毫秒精度。这有助于比较各种工具生成的日志。
--random-seed=seed #设置随机生成器种子。为系统随机数生成器播种，然后为每个线程生成一系列初始生成器状态。 seed 的值可以是：time（默认值，种子基于当前时间）、rand（使用强大的随机源，如果不可用则失败）或无符号十进制整数。随机生成器是从 pgbench 脚本 (random... 函数) 中显式调用，或隐式调用（例如，选项 --rate 使用它来调度事务）。当显式设置时，用于播种的值将在终端上显示。seed 允许的任何值也可以通过环境变量 PGBENCH_RANDOM_SEED 提供。为了确保提供的种子影响所有可能的用途，请将此选项放在第一位或使用环境变量。
显式设置种子允许精确地重现 pgbench 运行，就随机数而言。由于随机状态是按线程管理的，这意味着如果每个线程有一个客户端并且没有外部或数据依赖项，则对于相同的调用，pgbench 运行完全相同。从统计学角度来看，精确地重现运行不是一个好主意，因为它可能会隐藏性能变化或过分提高性能，例如，通过命中与先前运行相同的页面。但是，它也可能对调试非常有帮助，例如重新运行导致错误的棘手案例。请明智地使用。
--sampling-rate=rate #采样率，用于将数据写入日志时，以减少生成的日志量。如果给出此选项，则仅记录指定部分的事务。1.0 表示将记录所有事务，0.05 表示仅记录 5% 的事务。
请记住在处理日志文件时考虑采样率。例如，在计算 TPS 值时，需要相应地乘以数字（例如，使用 0.01 采样率，您将只能获得实际 TPS 的 1/100）。
--show-script=scriptname #在 stderr 上显示内置脚本 scriptname 的实际代码，并立即退出。
--verbose-errors #打印有关所有错误和故障（不重试的错误）的消息，包括超过了哪个重试限制以及对于序列化/死锁故障超过了多远。（请注意，在这种情况下，输出可能会大大增加）。有关更多信息，请参阅故障和序列化/死锁重试。
成功运行将以状态 0 退出。退出状态 1 表示静态问题，例如无效的命令行选项或内部错误，这些错误应该永远不会发生。在启动基准测试时发生的早期错误（例如初始连接失败）也会以状态 1 退出。运行期间发生的错误（例如数据库错误或脚本中的问题）将导致退出状态 2。在后一种情况下，如果未指定 --exit-on-abort 选项，pgbench 将打印部分结果。
PGDATABASEPGHOSTPGPORTPGUSER #默认连接参数。
此实用程序与大多数其他 PostgreSQL 实用程序一样，使用 libpq 支持的环境变量（请参阅第 32.15 节）。
环境变量 PG_COLOR 指定是否在诊断消息中使用颜色。可能的值为 always、auto 和 never。
pgbench 从指定的列表中随机选择测试脚本并执行。脚本可能包括使用 -b 指定的内置脚本和使用 -f 指定的用户提供的脚本。可以为每个脚本指定一个相对权重，该权重在 @ 后指定，以便更改其选择概率。默认权重为 1。权重为 0 的脚本将被忽略。
默认内置事务脚本（也通过 -b tpcb-like 调用）在每个事务中对随机选择的 aid、tid、bid 和 delta 发出七个命令。该场景受 TPC-B 基准测试的启发，但实际上并非 TPC-B，因此得名。
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;
如果您选择 simple-update 内置（也为 -N），则事务中不包含步骤 4 和 5。这将避免对这些表的更新争用，但使测试用例更不像 TPC-B。
如果您选择 select-only 内置（也为 -S），则仅发出 SELECT。
pgbench 支持通过用从文件读取的事务脚本 (-f 选项) 替换默认事务脚本（如上所述）来运行自定义基准测试场景。在这种情况下，“事务” 计为脚本文件的一次执行。
脚本文件包含一个或多个以分号结尾的 SQL 命令。空行和以 -- 开头的行将被忽略。脚本文件还可以包含 “元命令”，这些命令由 pgbench 本身解释，如下所述。
在 PostgreSQL 9.6 之前，脚本文件中的 SQL 命令以换行符结尾，因此它们不能跨行继续。现在，分号是 必需的 用于分隔连续的 SQL 命令（尽管如果 SQL 命令后跟元命令，则不需要分号）。如果您需要创建可在旧版和新版 pgbench 中使用的脚本文件，请确保将每个 SQL 命令写入以分号结尾的单行。
假设 pgbench 脚本不包含不完整的 SQL 事务块。如果在运行时客户端到达脚本末尾而未完成最后一个事务块，它将被中止。
脚本文件有一个简单的变量替换功能。变量名必须由字母（包括非拉丁字母）、数字和下划线组成，第一个字符不能是数字。可以通过命令行 -D 选项设置变量，如上所述，或通过下面解释的元命令设置变量。除了任何由 -D 命令行选项预设的变量之外，还有一些变量会自动预设，如表 298中列出。使用 -D 为这些变量指定的值优先于自动预设。一旦设置，可以通过编写 :variablename 将变量的值插入 SQL 命令中。当运行多个客户端会话时，每个会话都有自己的一组变量。pgbench 支持在一个语句中最多使用 255 个变量。
表 298. pgbench 自动变量
| 变量 | 描述 |
|---|---|
client_id |
标识客户端会话的唯一编号（从零开始） |
default_seed |
默认情况下在哈希和伪随机排列函数中使用的种子 |
random_seed |
随机生成器种子（除非使用 -D 覆盖） |
scale |
当前比例因子 |
脚本文件元命令以反斜杠 (\) 开头，通常扩展到该行的末尾，尽管可以通过编写反斜杠-回车将其继续到其他行。元命令的参数由空格分隔。支持以下元命令：
\gset [prefix] \aset [prefix] #这些命令可用于结束 SQL 查询，替代终止分号 (;)。
当使用 \gset 命令时，预期前面的 SQL 查询返回一行，其列将存储到以列名命名的变量中，如果提供了 prefix，则在其前面加上前缀。
当使用 \aset 命令时，所有组合的 SQL 查询（用 \; 分隔）的列都将存储到以列名命名的变量中，如果提供了 prefix，则在其前面加上前缀。如果查询不返回任何行，则不进行赋值，并且可以测试变量是否存在以检测到这一点。如果查询返回多行，则保留最后一个值。
\gset 和 \aset 不能在管道模式下使用，因为在命令需要查询结果时，查询结果尚不可用。
以下示例将第一个查询的最终账户余额放入变量 abalance 中，并将变量 p_two 和 p_three 填充为第三个查询中的整数。第二个查询的结果被丢弃。最后两个组合查询的结果存储在变量 four 和 five 中。
UPDATE pgbench_accounts SET abalance = abalance + :delta WHERE aid = :aid RETURNING abalance \gset -- compound of two queries SELECT 1 \; SELECT 2 AS two, 3 AS three \gset p_ SELECT 4 AS four \; SELECT 5 AS five \aset
\if expression\elif expression\else\endif #这组命令实现了可嵌套的条件块，类似于 psql 的 \if expression。条件表达式与 \set 中的表达式相同，非零值被解释为真。
\set varname expression #将变量 varname 设置为根据 expression 计算的值。表达式可以包含 NULL 常量、布尔常量 TRUE 和 FALSE、整数常量（如 5432）、双精度常量（如 3.14159）、对变量 :variablename 的引用、运算符（具有其通常的 SQL 优先级和结合性）、函数调用、SQL CASE 通用条件表达式 和括号。
函数和大多数运算符在 NULL 输入上返回 NULL。
出于条件目的，非零数值为 TRUE，零数值和 NULL 为 FALSE。
过大或过小的整数和双精度常量，以及整数算术运算符 (+、-、* 和 /) 在溢出时会引发错误。
当 CASE 未提供最终的 ELSE 子句时，默认值为 NULL。
示例
\set ntellers 10 * :scale
\set aid (1021 * random(1, 100000 * :scale)) % \
(100000 * :scale) + 1
\set divx CASE WHEN :x <> 0 THEN :y/:x ELSE NULL END
\sleep number [ us | ms | s ] #导致脚本执行休眠指定持续时间（以微秒 (us)、毫秒 (ms) 或秒 (s) 为单位）。如果省略单位，则默认为秒。number 可以是整数常量，也可以是 :variablename 对具有整数值的变量的引用。
示例
\sleep 10 ms
\setshell varname command [ argument ... ] #将变量 varname 设置为使用给定 argument(s) 的 shell 命令 command 的结果。该命令必须通过其标准输出返回一个整数值。
command 和每个 argument 可以是文本常量，也可以是 :variablename 对变量的引用。如果要使用以冒号开头的 argument，请在 argument 的开头写一个额外的冒号。
示例
\setshell variable_to_be_assigned command literal_argument :variable ::literal_starting_with_colon
\shell command [ argument ... ] #与 \setshell 相同，但命令的结果被丢弃。
示例
\shell command literal_argument :variable ::literal_starting_with_colon
\startpipeline\syncpipeline\endpipeline #这组命令实现了 SQL 语句的管道化。管道必须以 \startpipeline 开头，以 \endpipeline 结束。在两者之间可以有任意数量的 \syncpipeline 命令，这些命令发送 同步消息，而不会结束正在进行的管道并刷新发送缓冲区。在管道模式下，语句被发送到服务器，而无需等待先前语句的结果。有关更多详细信息，请参阅 第 32.5 节。管道模式需要使用扩展查询协议。
表 299 中列出的算术、按位、比较和逻辑运算符内置于 pgbench 中，并且可以在出现在 \set 中的表达式中使用。运算符按优先级递增顺序列出。除非另有说明，否则采用两个数值输入的运算符，如果任一输入为双精度，则生成双精度值，否则生成整数结果。
表 299. pgbench 运算符
|
运算符 描述 示例 |
|---|
|
逻辑或
|
|
逻辑与
|
|
逻辑非
|
|
布尔值测试
|
|
空值测试
|
|
等于
|
|
不等于
|
|
不等于
|
|
小于
|
|
小于或等于
|
|
大于
|
|
大于或等于
|
|
按位或
|
|
按位异或
|
|
按位与
|
|
按位非
|
|
按位左移
|
|
按位右移
|
|
加法
|
|
减法
|
|
乘法
|
|
除法（如果两个输入都是整数，则将结果截断为零）
|
|
取模（余数）
|
|
取反
|
表 300 中列出的函数内置于 pgbench 中，并且可以在出现在 \set 中的表达式中使用。
表 300. pgbench 函数
|
函数 描述 示例 |
|---|
|
绝对值
|
|
将参数打印到 stderr，并返回该参数。
|
|
转换为 double 类型。
|
|
指数 (
|
|
从参数中选择最大值。
|
|
这是
|
|
计算 FNV-1a 哈希。
|
|
计算 MurmurHash2 哈希。
|
|
转换为 integer 类型。
|
|
从参数中选择最小值。
|
|
自然对数
|
|
取模（余数）
|
|
|
|
π 的近似值
|
|
|
|
计算
|
|
计算
|
|
计算
|
|
计算
|
|
平方根
|
random 函数使用均匀分布生成值，也就是说所有值都在指定范围内以相等的概率被抽取。 random_exponential、random_gaussian 和 random_zipfian 函数需要一个额外的 double 参数来确定分布的精确形状。
对于指数分布，参数 通过在 参数 处截断快速下降的指数分布，然后投影到边界之间的整数上来控制分布。准确地说，
f(x) = exp(-parameter * (x - min) / (max - min + 1)) / (1 - exp(-parameter))
然后在 min 和 max（包括）之间的值 i 以概率：f(i) - f(i + 1) 被抽取。
直观地说，参数 越大，越频繁地访问接近 min 的值，越少频繁地访问接近 max 的值。参数 越接近 0，访问分布越平坦（越均匀）。分布的一个粗略近似是，范围内最频繁的 1% 的值（接近 min）被抽取的时间占 参数%。参数 值必须严格为正。
对于高斯分布，区间被映射到标准正态分布（经典的钟形高斯曲线），在左侧 -参数 处截断，在右侧 +参数 处截断。区间中间的值更有可能被抽取。准确地说，如果 PHI(x) 是标准正态分布的累积分布函数，均值 mu 定义为 (max + min) / 2.0，
f(x) = PHI(2.0 * parameter * (x - mu) / (max - min + 1)) /
(2.0 * PHI(parameter) - 1)
然后在 min 和 max（包括）之间的值 i 以概率：f(i + 0.5) - f(i - 0.5) 被抽取。直观地说，参数 越大，越频繁地抽取接近区间中间的值，越少频繁地抽取接近 min 和 max 边界的值。大约 67% 的值是从中间 1.0 / 参数 抽取的，即围绕均值的相对 0.5 / 参数，95% 的值是从中间 2.0 / 参数 抽取的，即围绕均值的相对 1.0 / 参数；例如，如果 参数 为 4.0，则 67% 的值是从区间的中间四分之一（1.0 / 4.0）（即从 3.0 / 8.0 到 5.0 / 8.0）抽取的，95% 的值是从区间的中间一半（2.0 / 4.0）（第二和第三四分位数）抽取的。参数 的最小允许值为 2.0。
random_zipfian 生成有界齐夫分布。参数 定义了分布的偏斜程度。参数 越大，越频繁地抽取接近区间开始的值。分布是这样的，假设范围从 1 开始，抽取 k 相对于抽取 k+1 的概率之比为 ((。例如，k+1)/k)**参数random_zipfian(1, ..., 2.5) 生成值 1 的频率大约是 2 的 (2/1)**2.5 = 5.66 倍，而 2 本身生成的频率大约是 3 的 (3/2)**2.5 = 2.76 倍，依此类推。
pgbench 的实现基于“非均匀随机变量生成”，Luc Devroye，第 550-551 页，Springer 1986。由于该算法的限制，参数 值被限制在 [1.001, 1000] 范围内。
在设计非均匀选择行的基准测试时，请注意，所选的行可能与其他数据相关联，例如来自序列的 ID 或物理行顺序，这可能会使性能测量产生偏差。
为了避免这种情况，您可能希望使用 permute 函数或其他具有类似效果的步骤来洗牌所选的行并消除此类相关性。
哈希函数 hash、hash_murmur2 和 hash_fnv1a 接受输入值和可选的种子参数。如果未提供种子，则使用 :default_seed 的值，除非由命令行 -D 选项设置，否则该值会随机初始化。
permute 函数接收一个输入值、一个大小以及一个可选的种子参数。它生成一个伪随机整数排列，范围在 [0, size) 内，并返回输入值在排列后的值中的索引。所选排列由种子参数化，如果未指定，则默认为 :default_seed。与哈希函数不同，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.nnnprefix 默认为 pgbench_log，nnn 是 pgbench 进程的 PID。可以使用 --log-prefix 选项更改前缀。如果 -j 选项为 2 或更高，则存在多个工作线程，每个线程将拥有自己的日志文件。第一个工作线程将使用与标准单工作线程情况相同的文件名来命名其日志文件。其他工作线程的其他日志文件将命名为 prefix.nnn.mmmmmm 是每个工作线程的顺序编号，从 1 开始。
日志文件中的每一行描述一个事务。它包含以下用空格分隔的字段：
client_id标识运行事务的客户端会话。
transaction_no统计该会话已运行的事务数量。
time事务的经过时间，单位为微秒。
script_no标识用于事务的脚本文件（在使用 -f 或 -b 指定多个脚本时很有用）。
time_epoch事务的完成时间，作为 Unix 时间戳。
time_us事务完成时间的毫秒级部分，单位为微秒。
schedule_lag事务启动延迟，即事务的计划启动时间与其实际启动时间之间的差值，单位为微秒（仅当指定了 --rate 时才会出现）。
retries在事务期间发生序列化或死锁错误后重试的次数（仅当 --max-tries 不等于 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 毫秒）超过了 5 毫秒的限制。接下来的两个事务被跳过了，因为它们在开始之前就已经延迟了。
以下示例显示了带有失败和重试的日志文件片段，最大重试次数设置为 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 选项时，日志文件将使用不同的格式。每行日志描述一个聚合间隔。它包含以下用空格分隔的字段：
interval_start间隔的开始时间，作为 Unix 时间戳。
num_transactions间隔内的事务数量。
sum_latency事务延迟的总和。
sum_latency_2事务延迟平方的总和。
min_latency最小事务延迟。
max_latency最大事务延迟。
sum_lag事务启动延迟的总和（除非指定了 --rate，否则为零）。
sum_lag_2事务启动延迟平方的总和（除非指定了 --rate，否则为零）。
min_lag最小事务启动延迟（除非指定了 --rate，否则为零）。
max_lag最大事务启动延迟（除非指定了 --rate，否则为零）。
skipped由于开始得太晚而跳过的事务数量（除非指定了 --rate 和 --latency-limit，否则为零）。
retried重试的事务数量（除非 --max-tries 不等于 1，否则为零）。
retries序列化或死锁错误后的重试次数（除非 --max-tries 不等于 1，否则为零）。
serialization_failures发生序列化错误且之后未重试的事务数量（除非指定了 --failures-detailed，否则为零）。
deadlock_failures发生死锁错误且之后未重试的事务数量（除非指定了 --failures-detailed，否则为零）。
以下是使用此选项生成的一些示例输出：
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 会为每个语句收集以下统计信息：
latency — 每个语句的经过时间。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 时，主要有三种类型的错误：
主程序的错误。它们是最严重的错误，总是会导致 pgbench 立即退出并显示相应的错误消息。它们包括：
pgbench 开始时的错误（例如，无效的选项值）；
初始化模式中的错误（例如，为内置脚本创建表的查询失败）；
启动线程之前的错误（例如，无法连接到数据库服务器、元命令中的语法错误、线程创建失败）；
内部 pgbench 错误（应该永远不会发生……）。
线程管理其客户端时的错误（例如，客户端无法启动到数据库服务器的连接/连接客户端到数据库服务器的套接字已失效）。在这种情况下，此线程的所有客户端都将停止，而其他线程将继续工作。但是，如果指定了 --exit-on-abort，则所有线程都会立即停止。
直接客户端错误。在内部 pgbench 错误（应该永远不会发生……）或指定了 --exit-on-abort 的情况下，它们会导致 pgbench 立即退出并显示相应的错误消息。否则，在最坏的情况下，它们只会导致失败的客户端中止，而其他客户端将继续运行（但某些客户端错误在没有客户端中止的情况下进行处理并单独报告，请参见下文）。在本节的后面部分，假设讨论的错误仅是直接客户端错误，并且它们不是内部 pgbench 错误。
如果发生严重错误，客户端运行将中止；例如，与数据库服务器的连接丢失或脚本结束时未完成最后一个事务。此外，如果 SQL 或元命令的执行失败（序列化或死锁错误除外），客户端将中止。否则，如果 SQL 命令因序列化或死锁错误而失败，客户端不会中止。在这种情况下，当前事务将回滚，这还包括将客户端变量设置为事务运行之前的状态（假设一个事务脚本只包含一个事务；有关更多信息，请参阅pgbench 中实际执行的“事务”是什么？）。发生序列化或死锁错误的事务将在回滚后重复，直到成功完成或达到最大尝试次数（由 --max-tries 选项指定）/最大重试时间（由 --latency-limit 选项指定）/基准测试结束（由 --time 选项指定）。如果最后一次尝试运行失败，则此事务将被报告为失败，但客户端不会中止并继续工作。
如果不指定 --max-tries 选项，则在发生序列化或死锁错误后，事务将永远不会重试，因为其默认值为 1。使用无限次尝试 (--max-tries=0) 和 --latency-limit 选项仅限制最大重试时间。您还可以使用 --time 选项在无限次尝试下限制基准测试持续时间。
重复包含多个事务的脚本时要小心：脚本始终完全重试，因此成功的事务可能会执行多次。
重复包含 shell 命令的事务时要小心。与 SQL 命令的结果不同，shell 命令的结果不会回滚，除了 \setshell 命令的变量值。
成功事务的延迟包括事务执行、回滚和重试的整个时间。延迟仅针对成功的事务和命令进行测量，而不针对失败的事务或命令。
主报告包含失败事务的数量。如果 --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) 一样大；否则，您主要是在测量更新争用。 -s 表中只有 pgbench_branches 行，并且每个事务都希望更新其中一行，因此超过 -s 的 -c 值无疑会导致大量事务阻塞等待其他事务。
默认测试场景也对自表初始化以来经过的时间非常敏感：表中死行的积累和死空间会改变结果。要理解结果，您必须跟踪更新总数和何时发生 vacuum 操作。如果启用了 autovacuum，它可能会导致测量的性能发生不可预测的变化。
pgbench 的一个限制是，当尝试测试大量客户端会话时，它本身可能会成为瓶颈。可以通过在与数据库服务器不同的机器上运行 pgbench 来缓解这种情况，尽管低网络延迟至关重要。甚至可能有用的是，在多台客户端机器上同时运行多个 pgbench 实例，针对同一台数据库服务器。
如果不受信任的用户可以访问尚未采用安全模式的数据库，请勿在该数据库中运行 pgbench。 pgbench 使用非限定名称，并且不操作搜索路径。
如果您在文档中发现任何不正确的内容、与您对特定功能的体验不符的内容或需要进一步澄清的内容，请使用此表单报告文档问题。