↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 命令行工具 / 客户端程序

vacuumdb

vacuumdb — 清理并分析一个 PostgreSQL 数据库

当前查看 PostgreSQL 18.6。

说明

vacuumdb — 清理并分析一个 PostgreSQL 数据库

手册中的可执行程序
vacuumdb
程序版本
18.6
参考清单
客户端程序
选项定义组
33

用法

vacuumdb [ connection-option ...] [ option ...] [ -t | --table table [( column [,...] )] ] ... [ dbname | -a | --all ]
vacuumdb [ connection-option ...] [ option ...] [ -n | --schema schema ] ... [ dbname | -a | --all ]
vacuumdb [ connection-option ...] [ option ...] [ -N | --exclude-schema schema ] ... [ dbname | -a | --all ]

手册中的选项

选项与参数说明
-a --all清理所有数据库。
--buffer-usage-limit size为一次给定的 vacuumdb 调用指定 缓冲区访问策略（Buffer Access Strategy） 环形缓冲区大小。这个大小用于计算将作为该策略一部分被重用的共享缓冲区数量。参见 VACUUM 。
--disable-page-skipping禁止基于可见性映射内容跳过页面。
-e --echo回显 vacuumdb 生成并发送给服务器的命令。
-f --full执行 “ 完全 ” 清理。
-F --freeze激进地 “ 冻结 ” 元组。
--force-index-cleanup始终删除指向死元组的索引条目。
-j njobs --jobs= njobs通过同时运行 njobs 条命令，并行执行清理或分析命令。该选项可能会缩短处理时间，但也会增加数据库服务器上的负载。
--min-mxid-age mxid_age仅对多事务 ID 年龄至少为 mxid_age 的表执行清理或分析命令。此设置可用于优先处理表，以防止多事务 ID 回卷（见 第 24.1.5.1 节 ）。
--min-xid-age xid_age仅对事务 ID 年龄至少为 xid_age 的表执行清理或分析命令。此设置可用于优先处理表，以防止事务 ID 回卷（见 第 24.1.5 节 ）。
--missing-stats-only仅分析那些在列、索引表达式或扩展统计信息对象上缺少统计信息的关系。与 --analyze-in-stages 一起使用时，此选项可防止 vacuumdb 临时用按较低统计目标生成的统计信息替换现有统计信息，从而避免查询优化器短暂地作出更差的选择。
-n schema --schema= schema仅清理或分析 schema 中的所有表。可以通过多次指定 -n 来清理多个模式。
-N schema --exclude-schema= schema不清理或分析 schema 中的任何表。可以通过多次指定 -N 来排除多个模式。
--no-index-cleanup不删除指向死元组的索引条目。
--no-process-main跳过主关系。
--no-process-toast如果有，跳过与待清理表关联的 TOAST 表。
--no-truncate不截断表末尾的空页。
-P parallel_workers --parallel= parallel_workers指定 并行清理 的并行工作进程数量。这样可以让清理利用多个 CPU 处理索引。参见 VACUUM 。
-q --quiet不显示进度消息。
--skip-locked跳过那些无法立即加锁并进行处理的关系。
-t table [ ( column [,...]) ] --table= table [ ( column [,...]) ]仅清理或分析 table 。只有与 --analyze 或 --analyze-only 选项一起使用时，才能指定列名。可以通过多次指定 -t 来清理多个表。
-v --verbose在处理过程中输出详细信息。
-V --version输出 vacuumdb 的版本并退出。
-z --analyze同时计算供优化器使用的统计信息。
-Z --analyze-only仅计算供优化器使用的统计信息（不执行清理）。
--analyze-in-stages类似 --analyze-only ，仅计算供优化器使用的统计信息（不执行清理）。该选项会运行三个阶段的分析；第一阶段使用尽可能低的统计目标（见 default_statistics_target ），以便更快地生成可用统计信息，随后的阶段再构建完整统计信息。
-? --help显示 vacuumdb 命令行参数的帮助并退出。
-h host --host= host指定服务器所在机器的主机名。如果该值以斜杠开头，则它会被用作 Unix 域套接字目录。
-p port --port= port指定服务器监听连接所用的 TCP 端口，或本地 Unix 域套接字文件扩展名。
-U username --username= username连接时使用的用户名。
-w --no-password绝不提示输入密码。如果服务器要求密码认证，而又无法通过其他方式获得密码，例如 .pgpass 文件，则连接尝试将失败。此选项可用于无人输入密码的批处理作业和脚本。
-W --password强制 vacuumdb 在连接数据库之前提示输入密码。
--maintenance-db= dbname当使用 -a / --all 时，连接到该数据库以收集要清理的数据库列表。如果未指定，则使用 postgres 数据库；若该数据库不存在，则使用 template1 。这可以是一个 连接字符串 。如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。此外，除数据库名本身外，连接字符串中的其他参数在连接到其他数据库时也会被复用。

环境变量

变量含义
PGDATABASE PGHOST PGPORT PGUSER默认连接参数
PG_COLOR指定诊断消息是否使用颜色。可选值为 always 、 auto 和 never 。

手册定义

vacuumdb

vacuumdb — 清理并分析一个 PostgreSQL 数据库

大纲

vacuumdb [connection-option...] [option...] [ -t | --table table [( column [,...] )] ] ... [ dbname | -a | --all ]

vacuumdb [connection-option...] [option...] [ -n | --schema schema ] ... [ dbname | -a | --all ]

vacuumdb [connection-option...] [option...] [ -N | --exclude-schema schema ] ... [ dbname | -a | --all ]

说明

vacuumdb 是用于清理 PostgreSQL 数据库的工具。vacuumdb 还会生成供 PostgreSQL 查询优化器使用的内部统计信息。

vacuumdb 是 SQL 命令 VACUUM 的包装器。通过该工具或通过访问服务器的其他方式来清理和分析数据库，在效果上没有区别。

选项

vacuumdb 接受下列命令行参数：

-a
--all

清理所有数据库。

--buffer-usage-limit size

为一次给定的 vacuumdb 调用指定缓冲区访问策略（Buffer Access Strategy）环形缓冲区大小。这个大小用于计算将作为该策略一部分被重用的共享缓冲区数量。参见VACUUM。

[-d] dbname
[--dbname=]dbname

当未使用 -a/--all 时，指定要清理或分析的数据库名称。如果未指定，则从环境变量 PGDATABASE 中读取数据库名。如果该变量未设置，则使用连接时指定的用户名。dbname 可以是连接字符串。如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。

--disable-page-skipping

禁止基于可见性映射内容跳过页面。

-e
--echo

回显 vacuumdb 生成并发送给服务器的命令。

-f
--full

执行“完全”清理。

-F
--freeze

激进地“冻结”元组。

--force-index-cleanup

始终删除指向死元组的索引条目。

-j njobs
--jobs=njobs

通过同时运行 njobs 条命令，并行执行清理或分析命令。该选项可能会缩短处理时间，但也会增加数据库服务器上的负载。

vacuumdb 将打开 njobs 个到数据库的连接，因此请确保max_connections的设置足够高，能够容纳所有这些连接。

注意，如果将此模式与 -f（FULL）选项一起使用，某些系统目录被并行处理时可能会因死锁而失败。

--min-mxid-age mxid_age

仅对多事务 ID 年龄至少为 mxid_age 的表执行清理或分析命令。此设置可用于优先处理表，以防止多事务 ID 回卷（见第 24.1.5.1 节）。

就此选项而言，一个关系的多事务 ID 年龄，是其主关系及其关联的 TOAST 表（如果存在）年龄中的较大者。由于 vacuumdb 发出的命令在必要时也会处理该关系的 TOAST 表，因此无需单独考虑它。

--min-xid-age xid_age

仅对事务 ID 年龄至少为 xid_age 的表执行清理或分析命令。此设置可用于优先处理表，以防止事务 ID 回卷（见第 24.1.5 节）。

就此选项而言，一个关系的事务 ID 年龄，是其主关系及其关联的 TOAST 表（如果存在）年龄中的较大者。由于 vacuumdb 发出的命令在必要时也会处理该关系的 TOAST 表，因此无需单独考虑它。

--missing-stats-only

仅分析那些在列、索引表达式或扩展统计信息对象上缺少统计信息的关系。与 --analyze-in-stages 一起使用时，此选项可防止 vacuumdb 临时用按较低统计目标生成的统计信息替换现有统计信息，从而避免查询优化器短暂地作出更差的选择。

此选项只能与 --analyze-only 或 --analyze-in-stages 配合使用。

注意，--missing-stats-only 要求拥有 SELECT 权限，以访问 pg_statistic 和 pg_statistic_ext_data，而这些权限默认只授予超级用户。

-n schema
--schema=schema

仅清理或分析 schema 中的所有表。可以通过多次指定 -n 来清理多个模式。

-N schema
--exclude-schema=schema

不清理或分析 schema 中的任何表。可以通过多次指定 -N 来排除多个模式。

--no-index-cleanup

不删除指向死元组的索引条目。

--no-process-main

跳过主关系。

--no-process-toast

如果有，跳过与待清理表关联的 TOAST 表。

--no-truncate

不截断表末尾的空页。

-P parallel_workers
--parallel=parallel_workers

指定并行清理的并行工作进程数量。这样可以让清理利用多个 CPU 处理索引。参见VACUUM。

-q
--quiet

不显示进度消息。

--skip-locked

跳过那些无法立即加锁并进行处理的关系。

-t table [ (column [,...]) ]
--table=table [ (column [,...]) ]

仅清理或分析 table。只有与 --analyze 或 --analyze-only 选项一起使用时，才能指定列名。可以通过多次指定 -t 来清理多个表。

提示

如果指定了列，你很可能需要在 shell 中转义括号。（见下面的示例。）

-v
--verbose

在处理过程中输出详细信息。

-V
--version

输出 vacuumdb 的版本并退出。

-z
--analyze

同时计算供优化器使用的统计信息。

-Z
--analyze-only

仅计算供优化器使用的统计信息（不执行清理）。

--analyze-in-stages

类似 --analyze-only，仅计算供优化器使用的统计信息（不执行清理）。该选项会运行三个阶段的分析；第一阶段使用尽可能低的统计目标（见default_statistics_target），以便更快地生成可用统计信息，随后的阶段再构建完整统计信息。

此选项仅在分析当前没有统计信息，或现有统计信息完全错误的数据库时才有用，例如数据库刚通过恢复转储重新填充，或刚通过 pg_upgrade 升级得到。注意，在已有统计信息的数据库上使用此选项，可能会因为早期阶段采用较低统计目标，导致查询优化器的选择暂时变差。

-?
--help

显示 vacuumdb 命令行参数的帮助并退出。

vacuumdb 还接受下列用于连接参数的命令行参数：

-h host
--host=host

指定服务器所在机器的主机名。如果该值以斜杠开头，则它会被用作 Unix 域套接字目录。

-p port
--port=port

指定服务器监听连接所用的 TCP 端口，或本地 Unix 域套接字文件扩展名。

-U username
--username=username

连接时使用的用户名。

-w
--no-password

绝不提示输入密码。如果服务器要求密码认证，而又无法通过其他方式获得密码，例如 .pgpass 文件，则连接尝试将失败。此选项可用于无人输入密码的批处理作业和脚本。

-W
--password

强制 vacuumdb 在连接数据库之前提示输入密码。

这个选项绝非必需，因为如果服务器要求密码认证，vacuumdb 会自动提示输入密码。不过，vacuumdb 会先浪费一次连接尝试，才得知服务器需要密码。在某些情况下，输入 -W 以避免这次额外的连接尝试是值得的。

--maintenance-db=dbname

当使用 -a/--all 时，连接到该数据库以收集要清理的数据库列表。如果未指定，则使用 postgres 数据库；若该数据库不存在，则使用 template1。这可以是一个连接字符串。如果是这样，连接字符串参数将覆盖任何冲突的命令行选项。此外，除数据库名本身外，连接字符串中的其他参数在连接到其他数据库时也会被复用。

环境

PGDATABASE
PGHOST
PGPORT
PGUSER

默认连接参数

PG_COLOR

指定诊断消息是否使用颜色。可选值为 always、auto和 never。

与大多数其他 PostgreSQL 工具一样，此工具也使用 libpq 支持的环境变量（见第 32.15 节）。

诊断

如果遇到问题，请参见VACUUM和psql中关于潜在问题和错误消息的讨论。数据库服务器必须在目标主机上运行。此外，libpq前端库所使用的任何默认连接设置和环境变量都会生效。

示例

清理数据库 test：

$ vacuumdb test

清理并分析名为 bigdb 的数据库，以供优化器使用：

$ vacuumdb --analyze bigdb

清理名为 xyzzy 的数据库中的单个表 foo，并分析该表的单列 bar，以供优化器使用：

$ vacuumdb --analyze --verbose --table='foo(bar)' xyzzy

清理名为 xyzzy 的数据库中 foo 和 bar 模式内的所有表：

$ vacuumdb --schema='foo' --schema='bar' xyzzy

另见

VACUUM

文档与源码

来源构建
版本
18.6
构建
https://ftp.postgresql.org/pub/source/v18.6/postgresql-18.6.tar.bz2
来源指纹
ee8d1a3612338fd9adf250730cb640fcc5233b5491337cc00a316a44e3a0b9f8

版本比较

PostgreSQL 14 → 15: 属性变化。

以下差异保留原始字段名与英文源描述。

--- PostgreSQL 14
+++ PostgreSQL 15
@@ -163,7 +163,7 @@
       "signature": "-Z --analyze-only"
     },
     {
-      "description": "Only calculate statistics for use by the optimizer (no vacuum), like --analyze-only . Run several (currently three) stages of analyze with different configuration settings, to produce usable statistics faster. This option is useful to analyze a database that was newly populated from a restored dump or by pg_upgrade . This option will try to create some statistics as fast as possible, to make the database usable, and then produce full statistics in the subsequent stages.",
+      "description": "Only calculate statistics for use by the optimizer (no vacuum), like --analyze-only . Run three stages of analyze; the first stage uses the lowest possible statistics target (see default_statistics_target ) to produce usable statistics faster, and subsequent stages build the full statistics. This option is only useful to analyze a database that currently has no statistics or has wholly incorrect ones, such as if it is newly populated from a restored dump or by pg_upgrade . Be aware that running with this option in a database with existing statistics may cause the query optimizer choices to become transiently worse due to the low statistics targets of the early stages.",
       "names": [
         "--analyze-in-stages"
       ],

比较已记录的接口与属性，排除来源指纹和构建元数据。某个样本中没有记录，不能据此判断实际引入或移除的版本。

相关条目

导出 JSON · 返回命令行工具 · 收录范围为 PostgreSQL 10 至 20；最早采样版本不一定是实际引入版本。