pgbench
描述 pgbench 是一个用于对 PostgreSQL 执行基准测试的简单程序。它会反复执行同一组 SQL 命令，也可在多个并发数据库会话中运行，然后计算平均事务速率（每秒事务数）。默认情况下， pgbench 测试的是一个大体上基于 TPC-B 的场景，每个事务包含五条 SELECT 、 UPDATE 和 INSERT 命令。不过，通过编写自己的事务脚本文件，也很容易测试其他场景。 典型的 pgbench 输出如下： transaction type: <builtin: TPC-B (s…
当前查看 PostgreSQL 18。
中文定义与说明
命令行工具 pgbench -i [ option ...] [ dbname ] pgbench [ option ...] [ dbname ]。
同版本中文手册节选
描述
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 事务测试要求预先建立特定的表。应使用 -i（初始化）选项调用 pgbench 来创建并填充这些表。（测试自定义脚本时不需要这一步，但需要自行完成测试所需的准备工作。）初始化命令如下：
pgbench -i [other-options]dbname
其中 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（fillfactor）选项。
完成必要的准备后，就可以使用不带 -i 的命令运行基准测试，也就是：
pgbench [options]dbname
几乎在所有情况下，都需要附加一些选项才能得到有意义的测试。最重要的选项是 -c（客户端数）、-t（事务数）、-T（时间限制）以及 -f（指定自定义脚本文件）。完整列表见下文。
选项
以下内容分为三个小节。数据库初始化和运行基准测试时使用不同的选项，但有些选项在这两种情况下都适用。
初始化选项
pgbench 接受以下命令行初始化参数：
[-d]dbname[--dbname=]dbname指定要测试的数据库名称。如果未指定，则使用环境变量
PGDATABASE。如果未设置该变量，则使用连接指定的用户名。-i--initialize进入初始化模式所必需。
-Iinit_steps--init-steps=init_steps仅执行正常初始化步骤中的选定部分。
init_steps指定要执行的初始化步骤，每个步骤用一个字符表示。各步骤会按照指定顺序调用。默认值为dtgvp。可用步骤如下：d（删除）删除任何现有的 pgbench 表。
t（创建表）创建标准 pgbench 场景使用的表，即
pgbench_accounts、pgbench_branches、pgbench_history和pgbench_tellers。g或G（在客户端或服务器端生成数据）生成数据并将其装载到标准表中，替换其中任何已有数据。
使用
g（客户端生成数据）时，数据由pgbench客户端生成，再通过COPY发送到服务器，因此会大量占用客户端/服务器带宽。对于 14 及以上版本的 PostgreSQL，pgbench会在普通（非分区）表上使用FREEZE选项装载数据，以加快后续的VACUUM。使用g时，在为所有表生成数据的过程中，每生成 100,000 行会输出一条日志消息。使用
G（服务器端生成数据）时，pgbench客户端只发送较小的查询，随后实际数据在服务器端生成。这种方式不需要大量带宽，但服务器会承担更多工作。使用G时，生成数据期间不会打印任何进度消息。默认初始化行为使用客户端生成数据（等同于
g）。v（清理）在标准表上调用
VACUUM。p（创建主键）在标准表上创建主键索引。
f（创建外键）在标准表之间创建外键约束。（请注意，默认情况下不执行此步骤。）
-Ffillfactor--fillfactor=fillfactor以给定的 fillfactor 创建
pgbench_accounts、pgbench_tellers和pgbench_branches表。默认值为 100。-n--no-vacuum初始化期间不执行任何清理。（即使在
-I中指定了v步骤，此选项也会抑制它。）-q--quiet将日志切换为静默模式，每 5 秒只输出一条进度消息。默认日志每生成 100,000 行输出一条消息，因而往往会在每秒输出多行（尤其是在较好的硬件上）。
如果在
-I中指定了G，则此设置无效。-sscale_factor--scale=scale_factor将生成的行数乘以比例因子。例如，
-s 100会在pgbench_accounts表中创建 10,000,000 行。默认值为 1。当比例达到 20,000 或更大时，用于保存账户标识符的列（aid列）将切换到使用更大的整数（bigint），以便容纳账户标识符的取值范围。--foreign-keys在标准表之间创建外键约束。（如果初始化步骤序列中尚未包含
f步骤，则此选项会把它加入进去。）--index-tablespace=index_tablespace在指定的表空间中创建索引，而不是默认的表空间。
--partition-method=NAME使用
NAME方法创建分区的pgbench_accounts表。预期值为range或hash。此选项要求--partitions设置为非零值。若未指定，默认为range。--partitions=NUM创建带有
NUM个大小近乎相等分区的pgbench_accounts分区表，这些分区用于容纳按比例扩展后的账户数。默认值为0，表示不分区。--tablespace=tablespace在指定的表空间中创建表，而不是默认的表空间。
--unlogged-tables将所有表创建为不记录 WAL 的表，而不是永久表。
基准测试选项
pgbench 接受以下命令行基准测试参数：
-bscriptname[@weight]--builtin=scriptname[@weight]将指定的内置脚本添加到待执行脚本列表中。可用的内置脚本包括：
tpcb-like、simple-update和select-only。也接受内置名称的无歧义前缀。使用特殊名称list时，会显示内置脚本列表并立即退出。可选地，可在
@后写一个整数权重，以调整此脚本相对于其他脚本的选中概率。默认权重为 1。详情请参见下文。-cclients--client=clients模拟的客户端数量，也就是并发数据库会话的数量。默认值为 1。
-C--connect为每个事务建立一个新连接，而不是仅在每个客户端会话中执行一次。这对于测量连接开销很有用。
-Dvarname=value--define=varname=value定义一个变量，供自定义脚本使用（见下文）。允许使用多个
-D选项。-ffilename[@weight]--file=filename[@weight]将从
filename读取的事务脚本添加到要执行的脚本列表中。可选地，可在
@后写一个整数权重，以调整此脚本相对于其他脚本的选中概率。默认权重为 1。（如果脚本文件名本身包含@字符，可追加一个权重以消除歧义，例如filen@me@1。）详情见下文。-jthreads--jobs=threadspgbench 中的工作线程数。在多 CPU 机器上使用多个线程可能会有所帮助。客户端尽可能均匀地分布在可用线程中。默认值为 1。
-l--log将每个事务的信息写入日志文件。详情见下文。
-Llimit--latency-limit=limit持续时间超过
limit毫秒的事务会被单独计数和报告，称为 late。使用限流（
--rate=...）时，若某个事务落后于计划时间超过limit毫秒，从而已经不可能满足延迟限制，则它根本不会被发送到服务器。此类事务会被单独计数并报告为 skipped。使用
--max-tries选项时，若某个事务因串行化异常或死锁而失败，且其所有尝试的总耗时大于limit毫秒，则不会再重试。若只想限制尝试总时间而不限制尝试次数，请使用--max-tries=0。默认情况下，--max-tries为 1，出现串行化/死锁错误的事务不会重试。有关此类事务重试的更多信息，见失败和串行化/死锁重试。-Mquerymode--protocol=querymode用于向服务器提交查询的协议：
simple：使用简单查询协议。extended：使用扩展查询协议。prepared：使用带有预备语句的扩展查询协议。
在
prepared模式下，pgbench 从第二次查询迭代开始复用解析分析结果，因此 pgbench 比其他模式运行得更快。默认值是简单查询协议。（更多信息见第 54 章。）
-n--no-vacuum在运行测试前不执行任何清理。如果运行的是不包含标准表
pgbench_accounts、pgbench_branches、pgbench_history和pgbench_tellers的自定义测试场景，则此选项是必需的。-N--skip-some-updates运行内置的 simple-update 脚本。是
-b simple-update的简写。-Psec--progress=sec每
sec秒显示一次进度报告。报告包括自运行开始以来的时间、自上次报告以来的 TPS、自上次报告以来事务延迟的平均值和标准差，以及失败事务数。使用限流（-R）时，延迟是相对于事务计划开始时间计算的，而不是实际开始时间，因此其中也包含平均计划滞后时间。当使用--max-tries启用事务在串行化/死锁错误后的重试时，报告还会包含发生过重试的事务数以及总重试次数。-r--report-per-command在基准测试完成后，报告每条命令的以下统计信息：平均延迟（从客户端视角看到的语句执行时间）、失败次数，以及该命令因串行化或死锁错误而发生的重试次数。仅当
--max-tries选项不等于 1 时，报告才会显示重试统计信息。-Rrate--rate=rate以指定速率执行事务，而不是像默认行为那样尽可能快地运行。速率以每秒事务数表示。如果目标速率高于可达到的最大速率，则速率限制不会影响结果。
该速率通过让事务沿着一条符合泊松分布的时间线启动来实现。预期开始时间表是根据客户端首次启动的时间向前推进的，而不是根据前一个事务结束的时间。这意味着，当某些事务超过其原定结束时间时，后续事务仍有可能重新赶上计划。
启用限流后，运行结束时报告的事务延迟是从计划开始时间计算的，因此它包含每个事务等待前一个事务完成的时间。这段等待时间称为计划滞后时间，其平均值和最大值也会单独报告。若要得到相对于事务实际开始时间的延迟，也就是事务在数据库中实际执行所花费的时间，可以用报告中的延迟减去计划滞后时间。
如果同时使用
--latency-limit和--rate，一个事务可能会落后太多，以至于在前一个事务结束时已经超过了延迟限制，因为延迟是从计划开始时间计算的。这样的事务不会发送到服务器，而是完全跳过并单独计数。较高的计划滞后时间表明，在所选客户端数和线程数下，系统无法以指定速率处理事务。当平均事务执行时间长于事务之间的计划间隔时，后续事务会不断进一步落后，而计划滞后时间也会随着测试持续时间增加。在这种情况下，需要降低指定的事务速率。
-sscale_factor--scale=scale_factor在 pgbench 输出中报告指定的比例因子。对于内置测试，这没有必要；系统会通过统计
pgbench_branches表中的行数来检测正确的比例因子。但在只测试自定义基准（-f选项）时，除非使用此选项，否则比例因子会被报告为 1。-S--select-only运行内置的 select-only 脚本。是
-b select-only的简写。-ttransactions--transactions=transactions每个客户端运行的事务数量。默认值为 10。
-Tseconds--time=seconds让测试运行指定的秒数，而不是让每个客户端执行固定数量的事务。
-t和-T是互斥的。-v--vacuum-all在运行测试之前，对四个标准表全部执行清理。如果既不使用
-n也不使用-v，pgbench 会对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将内置脚本
scriptname的实际代码输出到 stderr，然后立即退出。--verbose-errors打印关于所有错误和失败（不再重试的错误）的消息，包括超出了哪一种重试限制，以及对于串行化/死锁失败超出的幅度。（请注意，这种情况下输出量可能会显著增加。）更多信息见失败和串行化/死锁重试。
公共选项
pgbench 还接受以下用于连接参数及其他通用设置的命令行参数：
--debug打印调试输出。
-hhostname--host=hostname数据库服务器的主机名。
-pport--port=port数据库服务器的端口号。
-Ulogin--username=login连接时使用的用户名。
-V--version打印 pgbench 版本并退出。
-?--help显示 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 事务测试要求预先建立特定的表。应使用 -i （初始
- 手册中的可执行程序
- “ 事务 ”
- 程序版本
- 18.6
- 参考清单
- 客户端程序
- 选项定义组
- 47
用法
pgbench -i [ option ...] [ dbname ]
pgbench [ option ...] [ dbname ]手册中的选项
| 选项与参数 | 说明 |
|---|---|
| -i --initialize | 进入初始化模式所必需。 |
| -I init_steps --init-steps= init_steps | 仅执行正常初始化步骤中的选定部分。 init_steps 指定要执行的初始化步骤，每个步骤用一个字符表示。各步骤会按照指定顺序调用。默认值为 dtgvp 。可用步骤如下： |
| -F fillfactor --fillfactor= fillfactor | 使用给定的 fillfactor 创建 pgbench_accounts、pgbench_tellers 和 pgbench_branches 表。默认值为 100。 |
| -n --no-vacuum | 初始化期间不执行清理。（此选项会抑制 v 初始化步骤，即使 -I 中已指定该步骤。） |
| -q --quiet | 将日志切换为静默模式，每 5 秒只输出一条进度消息。默认日志每生成 100,000 行输出一条消息，因而往往会在每秒输出多行（尤其是在较好的硬件上）。 |
| -s scale_factor --scale= scale_factor | 将生成的行数乘以规模因子。例如，-s 100 会在 pgbench_accounts 表中创建 10,000,000 行。默认值为 1。当规模因子达到 20,000 或更大时，存放账户标识符的列（aid 列）会改用更大的整数类型（bigint），以容纳所需的账户标识符范围。 |
| --foreign-keys | 在标准表之间创建外键约束。（如果初始化步骤序列中尚未包含 f 步骤，则此选项会把它加入进去。） |
| --index-tablespace= index_tablespace | 在指定的表空间中创建索引，而不是默认的表空间。 |
| --partition-method= NAME | 使用 NAME 方法创建分区的 pgbench_accounts 表。可选值为 range 或 hash。此选项要求 --partitions 为非零值。未指定时默认为 range。 |
| --partitions= NUM | 为按规模因子确定的账户数量创建具有 NUM 个分区的 pgbench_accounts 表，各分区大小大致相等。默认值为 0，表示不分区。 |
| --tablespace= tablespace | 在指定的表空间中创建表，而不是默认的表空间。 |
| --unlogged-tables | 将所有表创建为不记录 WAL 的表，而不是永久表。 |
| -b scriptname[@weight] --builtin = scriptname[@weight] | 将指定的内置脚本添加到待执行脚本列表中。可用的内置脚本包括： tpcb-like 、 simple-update 和 select-only 。也接受内置名称的无歧义前缀。使用特殊名称 list 时，会显示内置脚本列表并立即退出。 |
| -c clients --client= clients | 模拟的客户端数量，即并发数据库会话数。默认值为 1。 |
| -C --connect | 为每个事务建立一个新连接，而不是仅在每个客户端会话中执行一次。这对于测量连接开销很有用。 |
| -D varname = value --define= varname = value | 定义一个变量，供自定义脚本使用（见下文）。允许使用多个 -D 选项。 |
| -f filename[@weight] --file= filename[@weight] | 将从 filename 读取的事务脚本添加到要执行的脚本列表中。 |
| -j threads --jobs= threads | pgbench 内部的工作线程数。在多 CPU 机器上，使用多个线程可能有帮助。客户端会尽可能均匀地分配到可用线程中。默认值为 1。 |
| -l --log | 将每个事务的信息写入日志文件。详情见下文。 |
| -L limit --latency-limit= limit | 持续时间超过 limit 毫秒的事务会被单独计数和报告，称为 late 。 |
| -M querymode --protocol= querymode | 用于向服务器提交查询的协议： |
| -n --no-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 | 以指定速率执行事务，而不是像默认行为那样尽可能快地运行。速率以每秒事务数表示。如果目标速率高于可达到的最大速率，则速率限制不会影响结果。 |
| -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 | 在运行测试之前，对四个标准表全部执行清理。如果既不使用 -n 也不使用 -v ， pgbench 会对 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 提供。为确保提供的种子影响所有可能的用途，将此选项放在第一位或使用环境变量。 |
| --sampling-rate= rate | 写入日志时使用的采样率，用于减少生成的日志量。如果给定此选项，则只记录指定比例的事务。1.0 表示记录全部事务，0.05 表示只记录 5% 的事务。 |
| --show-script= scriptname | 将内置脚本 scriptname 的实际代码输出到 stderr，然后立即退出。 |
| --verbose-errors | 打印关于所有错误和失败（不再重试的错误）的消息，包括超出了哪一种重试限制，以及对于串行化/死锁失败超出的幅度。（请注意，这种情况下输出量可能会显著增加。）更多信息见 失败和串行化/死锁重试 。 |
| --debug | 打印调试输出。 |
| -h hostname --host= hostname | 数据库服务器的主机名。 |
| -p port --port= port | 数据库服务器的端口号。 |
| -U login --username= login | 连接时使用的用户名。 |
| -V --version | 打印 pgbench 版本并退出。 |
| -? --help | 显示 pgbench 命令行参数的帮助信息并退出。 |
环境变量
| 变量 | 含义 |
|---|---|
| PGDATABASE PGHOST PGPORT PGUSER | 默认连接参数。 |
文档与源码
来源构建
- 版本
- 18.6
- 构建
- https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
- 来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8
版本比较
PostgreSQL 16 → 17: 属性变化。
以下差异保留原始字段名与英文源描述。
--- PostgreSQL 16
+++ PostgreSQL 17
@@ -15,7 +15,7 @@
"signature": "-i --initialize"
},
{
- "description": "Perform just a selected set of the normal initialization steps. init_steps specifies the initialization steps to be performed, using one character per step. Each step is invoked in the specified order. The default is dtgvp . The available steps are: d (Drop) Drop any existing pgbench tables. t (create Tables) Create the tables used by the standard pgbench scenario, namely pgbench_accounts , pgbench_branches , pgbench_history , and pgbench_tellers . g or G (Generate data, client-side or server-side) Generate data and load it into the standard tables, replacing any data already present. With g (client-side data generation), data is generated in pgbench client and then sent to the server. This uses the client/server bandwidth extensively through a COPY . pgbench uses the FREEZE option with version 14 or later of PostgreSQL to speed up subsequent VACUUM , unless partitions are enabled. Using g causes logging to print one message every 100,000 rows while generating data for the pgbench_accounts table. With G (server-side data generation), only small queries are sent from the pgbench client and then data is actually generated in the server. No significant bandwidth is required for this variant, but the server will do more work. Using G causes logging not to print any progress message while generating data. The default initialization behavior uses client-side data generation (equivalent to g ). v (Vacuum) Invoke VACUUM on the standard tables. p (create Primary keys) Create primary key indexes on the standard tables. f (create Foreign keys) Create foreign key constraints between the standard tables. (Note that this step is not performed by default.)",
+ "description": "Perform just a selected set of the normal initialization steps. init_steps specifies the initialization steps to be performed, using one character per step. Each step is invoked in the specified order. The default is dtgvp . The available steps are: d (Drop) Drop any existing pgbench tables. t (create Tables) Create the tables used by the standard pgbench scenario, namely pgbench_accounts , pgbench_branches , pgbench_history , and pgbench_tellers . g or G (Generate data, client-side or server-side) Generate data and load it into the standard tables, replacing any data already present. With g (client-side data generation), data is generated in pgbench client and then sent to the server. This uses the client/server bandwidth extensively through a COPY . pgbench uses the FREEZE option with version 14 or later of PostgreSQL to speed up subsequent VACUUM , except on the pgbench_accounts table if partitions are enabled. Using g causes logging to print one message every 100,000 rows while generating data for all tables. With G (server-side data generation), only small queries are sent from the pgbench client and then data is actually generated in the server. No significant bandwidth is required for this variant, but the server will do more work. Using G causes logging not to print any progress message while generating data. The default initialization behavior uses client-side data generation (equivalent to g ). v (Vacuum) Invoke VACUUM on the standard tables. p (create Primary keys) Create primary key indexes on the standard tables. f (create Foreign keys) Create foreign key constraints between the standard tables. (Note that this step is not performed by default.)",
"names": [
"-I init_steps",
"--init-steps= init_steps"
@@ -121,14 +121,6 @@
"signature": "-C --connect"
},
{
- "description": "Print debugging output.",
- "names": [
- "-d",
- "--debug"
- ],
- "signature": "-d --debug"
- },
- {
"description": "Define a variable for use by a custom script (see below). Multiple -D options are allowed.",
"names": [
"-D",
@@ -169,7 +161,7 @@
"signature": "-L limit --latency-limit= limit"
},
{
- "description": "Protocol to use for submitting queries to the server: simple : use simple query protocol. extended : use extended query protocol. prepared : use extended query protocol with prepared statements. In the prepared mode, pgbench reuses the parse analysis result starting from the second query iteration, so pgbench runs faster than in other modes. The default is simple query protocol. (See Chapter 55 for more information.)",
+ "description": "Protocol to use for submitting queries to the server: simple : use simple query protocol. extended : use extended query protocol. prepared : use extended query protocol with prepared statements. In the prepared mode, pgbench reuses the parse analysis result starting from the second query iteration, so pgbench runs faster than in other modes. The default is simple query protocol. (See Chapter 53 for more information.)",
"names": [
"-M",
"--protocol="
@@ -264,6 +256,13 @@
"signature": "--aggregate-interval= seconds"
},
{
+ "description": "Exit immediately when any client is aborted due to some error. Without this option, even when a client is aborted, other clients could continue their run as specified by -t or -T option, and pgbench will print an incomplete results in this case. Note that serialization failures or deadlock failures do not abort the client, so they are not affected by this option. See Failures and Serialization/Deadlock Retries for more information.",
+ "names": [
+ "--exit-on-abort"
+ ],
+ "signature": "--exit-on-abort"
+ },
+ {
"description": "Report failures in per-transaction and aggregation logs, as well as in the main and per-script reports, grouped by the following types: serialization failures; deadlock failures; See Failures and Serialization/Deadlock Retries for more information.",
"names": [
"--failures-detailed"
@@ -318,6 +317,13 @@
"--verbose-errors"
],
"signature": "--verbose-errors"
+ },
+ {
+ "description": "Print debugging output.",
+ "names": [
+ "--debug"
+ ],
+ "signature": "--debug"
},
{
"description": "The database server's host name",比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。
相关条目
导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。