Postgresql 中文操作指南

指定待测试的数据库的名称。如果不指定，则使用环境变量 PGDATABASE 。如果未设置，则使用为连接指定的用户名。

调用初始化模式时必填。

仅执行选择的常规初始化步骤集。 init_steps 指定要执行的初始化步骤，每一步使用一个字符。每个步骤按指定顺序调用。默认值为 dtgvp 。可用的步骤有：

使用给定的填充因子创建 pgbench_accounts 、 pgbench_tellers 和 pgbench_branches 表。默认值为100。

在此期间不执行真空。 （即使在 -I 中指定了此选项，此选项也会禁止执行 v 初始化步骤。）

将日志记录切换为安静模式，每5秒仅生成一条进度消息。默认日志记录每100,000行打印一条消息，这通常每秒会输出许多行（特别是在良好的硬件上）。

如果在 -I 中指定了 G ，则此设置无效。

将比例因子生成的行的数量相乘。例如， -s 100 会在 pgbench_accounts 表中创建10,000,000行。默认值为1。当比例为20,000或更大时，用于保存帐户标识符的列（ aid 列）将切换为使用更大的整数（ bigint ），以足够大以容纳帐户标识符范围。

在标准表之间创建外键约束。 （如果尚未添加，则此选项将 f 步骤添加到初始化步骤序列中。）

在指定表空间中创建索引，而不是默认表空间。

使用 NAME 方法创建分区 pgbench_accounts 表。预期值是 range 或 hash 。此选项要求将 —​partitions 设置为非零。如果未指定，则默认为 range 。

使用 NUM 个大小几乎相等的区块创建分区 pgbench_accounts 表，针对已调整数量的帐户。默认值为 0 ，表示无分区。

在指定表空间中创建表，而不是默认表空间。

将所有表创建为非日志表，而不是永久表。

删除任何现有的 pgbench 表。

创建标准 pgbench 方案中的表，即 pgbench_accounts 、 pgbench_branches 、 pgbench_history 和 pgbench_tellers 。

生成数据并将其加载到标准表中，替换已存在的任何数据。

使用 g （客户端数据生成），数据是在 pgbench 客户端生成，然后发送到服务器。这会通过 COPY 大量使用客户端/服务器带宽。 pgbench 使用 PostgreSQL 14 或更高版本的 FREEZE 选项来加速后续 VACUUM ，除非启用分区。使用 g 使得日志在为 pgbench_accounts 表生成数据时每 100,000 行打印一条消息。

使用 G （服务器端数据生成），仅从 pgbench 客户端发送少量查询，然后仅在服务器中生成数据。此变体不需要大量的带宽，但服务器的工作量会增加。使用 G 使得日志在生成数据时不会打印任何进度消息。

默认的初始化行为使用客户端数据生成（相当于 g ）。

对标准表调用 VACUUM 。

在标准表上创建主键索引。

在标准表之间创建外键约束。（请注意，默认情况下此步骤不会执行。）

将指定内置脚本添加到要执行的脚本列表中。可用的内置脚本为： tpcb-like 、 simple-update 和 select-only 。接受内置名称的明确前缀。使用特殊名称 list ，显示内置脚本列表，然后立即退出。

对于 @ ，可以选择写一个整数值的权重，用以调整相对于其他脚本选择该脚本的可能性。默认权重为 1。参见下文了解详细信息。

模拟的客户端数，即并发的数据库会话数。默认值为 1。

为每个事务建立一个新连接，而不是每个客户端会话只建立一个。这对于衡量连接开销很有用。

Print debugging output.

定义一个变量，供自定义脚本使用（参见下文）。允许使用多个 -D 选项。

向要执行的脚本列表中添加从 filename 读入的交易脚本。

您可以在 @ 后选择性地写入一个整数权重，以调整选择此脚本（与其它脚本相对）的概率。默认权重为 1。（若要使用包含 @ 字符的脚本文件名称，请附加权重，这样就没有歧义了，例如 filen@me@1 。）有关详细信息，请见下方。

pgbench 中的后台线程数。在多 CPU 机器上，使用一个以上的线程可能有所帮助。客户端会尽可能平均地分配给可用线程。默认值为 1。

将有关每个交易的信息写入日志文件。有关详细信息，请见下方。

持续时间超过 limit 毫秒的交易会被计数并单独报告，称为 late 。

当使用速控时（ —​rate=…​ ），落后计划 أكثر من limit 毫秒的交易，没有希望满足延迟极限，不会发送到服务器。它们会被计数并单独报告为 skipped 。

当使用 —​max-tries 选项时，如果交易因序列化异常或死锁而失败，则当所有尝试的总时间超过 limit 毫秒时，将不会重试。若要仅限制尝试的时间而不是尝试数，请使用 —​max-tries=0 。默认情况下，选项 —​max-tries 设置为 1，有序列化/死锁错误的交易不会重试。请参阅 Failures and Serialization/Deadlock Retries ，以获取有关重试此类交易的更多信息。

用于向服务器提交查询的协议：

在 prepared 模式下，pgbench 从第二次查询迭代开始重新使用解析分析结果，因此，pgbench 比其它模式下运行速度更快。

默认值为简单查询协议。（请参阅 Chapter 55 了解更多信息。）

在运行测试之前不执行 VACUUM 操作。如果您正在运行不包含标准表 pgbench_accounts 、 pgbench_branches 、 pgbench_history 和 pgbench_tellers 的自定义测试场景，则此选项为 necessary 。

运行内置的简单更新脚本。相当于 -b simple-update 。

每 sec 秒显示进度报告。此报告包括从运行开始以来的时间、自上一次报告以来的 TPS、交易延迟平均值、标准差和自上一次报告以来的失败事务数。在速控（ -R ）下，延迟是相对于交易计划的开始时间（而不是实际的交易开始时间）计算的，因此还包括平均计划延迟时间。当 —​max-tries 用于在序列化/死锁错误后启用事务重试时，此报告包括重试事务的数量和所有重试的总和。

基准完成后为每个命令报告以下统计数据：每个语句的平均延迟（从客户端角度来看的执行时间）、失败的数量和此命令中序列化或死锁错误后的重试次数。仅当 —​max-tries 选项不等于 1 时，此报告才会显示重试统计数据。

执行针对指定速率的事务，而不是尽可能快地运行（默认情况）。速率以每秒交易数为单位。如果目标速率高于最大可能速率，则速率限制不会影响结果。

通过沿着泊松分布的计划时间线启动交易来设定速率的目标。预期的开始时间计划会根据客户端首次启动的时间向前移动，而不是根据前一个交易结束的时间移动。这意味着当交易超出其原始计划结束时间时，后面的交易有可能赶上来。

在速控处于活动状态时，运行结束时报告的交易延迟是从计划的开始时间计算的，因此它包括了每个交易为等待前一个交易结束而不得不等待的时间。等待时间称为计划延迟时间，它的平均值和最大值也单独报告。相对于实际交易开始时间的交易延迟（即在数据库中执行交易时花费的时间），可以通过从报告的延迟中减去计划延迟时间计算。

如果 —​latency-limit 与 —​rate 一起使用，则交易可能会延迟很多，以致当前一个交易结束时，它已经超过延迟限制，因为延迟是从计划的开始时间计算的。此类交易不会发送到服务器，而是直接跳过并单独计数。

较长的计划延迟时间表明系统无法以所选的客户端和线程数以指定速率处理交易。当平均交易执行时间长于每个交易之间的计划间隔时，每个连续的交易都会进一步落后，计划延迟时间将随着测试运行时间的延长而持续增加。发生这种情况时，您必须降低指定的交易速率。

在 pgbench 的输出中报告指定比例因子。对于内置的测试，这没有必要；正确的比例因子将通过计算 pgbench_branches 表中的行数来检测。然而，当仅测试自定义 benchmark（ -f 选项）时，此比例因子将被报告为 1，除非使用了此选项。

运行内置的仅选择脚本。 -b select-only 的简写。

每个客户端运行的事务数。默认值为 10。

运行测试的时间为这么长（以秒为单位），而不是每个客户端的固定事务数。 -t 和 -T 互斥。

在运行测试之前对所有四个标准表进行 Vacuum。如果没有 -n 或 -v ，pgbench 将对 pgbench_tellers 和 pgbench_branches 表进行 Vacuum，并将截断 pgbench_history 。

聚合间隔的长度（以秒为单位）。仅可与 -l 选项一起使用。使用此选项，日志将包含按间隔划分的摘要数据，如下所述。

按以下类型对每个事务和聚合日志中的故障、以及在主报告和每个脚本报告中进行分组：

有关更多信息，请参阅 Failures and Serialization/Deadlock Retries 。

设置 —​log 创建的日志文件的 filename 前缀。默认值为 pgbench_log 。

对具有序列化/死锁错误的事务启用重试，并设置这些尝试的最大次数。此选项可以与 —​latency-limit 选项结合使用，该选项限制所有事务尝试的总时间；此外，如果没有 —​latency-limit 或 —​time ，则不能使用无限次数的尝试（ —​max-tries=0 ）。默认值为 1，且不会重试具有序列化/死锁错误的事务。有关重试此类事务的更多信息，请参阅 Failures and Serialization/Deadlock Retries 。

在显示进度（选项 -P ）时，使用时间戳（Unix 纪元）而不是从运行开始以来的秒数。单位为秒，小数点后为毫秒精度。这有助于比较各种工具生成的日志。

设置随机生成器的种子。为系统随机数生成器设置种子，然后生成一系列初始生成器状态，每个线程一个。 seed 的值可能为： time （默认值，种子基于当前时间）、 rand （使用强随机源，如果不可用则失败）或一个无符号十进制整数值。随机生成器从 pgbench 脚本（ random…​ 函数）显式调用或隐式调用（例如，选项 —​rate 用它来安排事务）。显式设置时，用于播种的值将显示在终端上。允许 seed 的任何值也可以通过环境变量 PGBENCH_RANDOM_SEED 提供。为确保提供的种子影响所有可能的用途，请将此选项放在第一位或使用环境变量。

显式设置种子允许准确重现 pgbench 运行，只要涉及到随机数。由于随机状态由每个线程管理，这意味着对于相同的调用，如果每个线程有一个客户端且没有外部或数据依赖关系，则 pgbench 运行完全相同。从统计学的角度来看，精确重现运行是不好的，因为它可以掩盖性能差异或不恰当地提高性能，例如，访问与之前运行相同的页面。但是，它对调试也可能很有帮助，例如重新运行导致错误的棘手案例。请谨慎使用。

在将数据写入日志时使用的采样率，以减少生成的日志量。如果给出了此选项，则只记录指定部分的事务。1.0 表示将记录所有事务，0.05 表示将只记录 5% 的事务。

处理日志文件时，请记住考虑采样率。例如，当计算 TPS 值时，您需要相应地乘以这些数字（例如，采样率为 0.01 时，您将只获得实际 TPS 的 1/100）。

在 stderr 上显示内置脚本 scriptname 的实际代码，然后立即退出。

打印所有错误和故障（未重试的错误）的消息，包括超过了哪个重试限制以及对于序列化/死锁故障超出了多少。（请注意，在这种情况下，输出可能会显著增加。）。有关更多信息，请参阅 Failures and Serialization/Deadlock Retries 。

数据库服务器的主机名

数据库服务器端口号

用户连接名

打印 pgbench 版本并退出。

显示帮助，有关 pgbench 命令行参数，然后退出。

这些命令可用来结束 SQL 查询，代替终止分号 ( ; )。

当使用了 \gset 命令时，前面的 SQL 查询预计返回一行，其列存储到以列名为名的变量中，并且在提供的情况下以 prefix 为前缀。

当使用了 \aset 命令时，所有合并的 SQL 查询（由 \; 分隔）的列都存储到以列名为名的变量中，并且在提供的情况下以 prefix 为前缀。如果查询没有返回任何行，则不会进行分配并且可测试变量是否存在以检测这种情况。如果查询返回多行，则保持最后的值。

\gset 和 \aset 不能在管道模式中使用，因为在需要用到命令时查询结果尚不可用。

下面的示例将第一个查询的最终帐户余额放入变量 abalance ，并将变量 p_two 和 p_three 填入第三个查询中的整数。第二个查询的结果被丢弃。最后两个合并查询的结果存储在变量 four 和 five 中。

这组命令实现可嵌套条件块，类似于 psql 的 \if expression 。条件表达式与 \set 中的一样，其中非零值解释为真。

将变量 varname 设置为根据 expression 计算的值。表达式可能包含 NULL 常量、布尔常量 TRUE 和 FALSE 、整数常量（如 5432 ）、双精度常量（如 3.14159 ）、对变量 :__variablename 、 operators 的引用（具有其通常的 SQL 优先级和关联性）、 function calls 、SQL CASE generic conditional expressions 和括号。

函数和大多数运算符在 NULL 输入上返回 NULL 。

出于条件目的，非零数值为 TRUE ，零数值和 NULL 为 FALSE 。

太大或太小的整数和双精度常量，以及整数算术运算符（ + 、 - 、 * 和 / ）会在溢出时引发错误。

当没有为 CASE 提供 ELSE 子句时，默认值是 NULL 。

Examples:

导致脚本执行休眠，休眠持续时间以微秒 ( us )、毫秒 ( ms ) 或秒 ( s ) 为单位。如果忽略单位，则默认为秒。 number 可以是整数常量或对具有整数值的变量的 :__variablename 引用。

Example:

将变量 varname 设置为带有给定 argument (s) 的 shell 命令 command 的结果。该命令必须通过其标准输出返回整数值。

command 和每个 argument 可以是文本常量或对变量的 :__variablename 引用。如果你想使用以冒号开头的 argument ，请在 argument 开头写一个附加的冒号。

Example:

与 \setshell 相同，但会丢弃该命令的结果。

Example:

这些命令限定了一系列 SQL 语句的开始和结束。在管道模式中，语句被发送到服务器，而无需等待前一条语句的结果。有关更多详细信息，请参见 Section 34.5 。管道模式需要使用扩展查询协议。

识别运行了事务的客户端会话

计算该会话已运行多少个事务

事务的经过时间（以微秒计）

识别用于事务的脚本文件（当使用 -f 或 -b 指定多个脚本时非常有用）

事务完成时间，以 Unix epoch 时间戳表示

事务完成时间的几分之一秒部分（以微秒计）

事务启动延迟，即事务的预定启动时间与它实际启动的时间之间的差值（以微秒计）（仅当指定了 —​rate 时才显示）

事务期间序列化或死锁错误后的重试次数（仅当 —​max-tries 不等于 1 时才显示）

间隔的开始时间，以 Unix 纪元时间戳形式

间隔内的交易数量

sum of transaction latencies

交易延迟的平方和

minimum transaction latency

maximum transaction latency

交易开始延迟的总和（除非指定了 —​rate 否则为零）

交易开始时间的平方总和（除非指定了 —​rate 否则为零）

最小交易开始延迟（除非指定了 —​rate 否则为零）

最大交易开始延迟（除非指定了 —​rate 否则为零）

因为开始太晚而被跳过的交易数量（除非指定了 —​rate 和 —​latency-limit 否则为零）

重试交易的数量（除非 —​max-tries 不等于一，否则为零）

序列化或死锁错误后的重试次数（除非 —​max-tries 不等于一，否则为零）

发生序列化错误且之后未重试的交易数量（除非指定了 —​failures-detailed 否则为零）

发生死锁错误且之后未重试的交易数量（除非指定了 —​failures-detailed 否则为零）