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

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

百科 / 命令行工具 / 服务端程序

postgres

描述 postgres 是 PostgreSQL 数据库服务器。客户端应用要访问数据库时，会（通过网络或本地）连接到一个正在运行的 postgres 实例。该 postgres 实例随后会启动一个独立的服务器进程来处理该连接。 一个 postgres 实例始终只管理一个数据库集簇的数据。数据库集簇是一组存储在同一文件系统位置（ “ 数据区域 ” ）中的数据库。只要使用不同的数据区域和不同的通信端口（见下文），一个系统上就可以同时运行多个 postgres 实例。当 postgres 启动时，它…

当前查看 PostgreSQL 18。

中文定义与说明

命令行工具 postgres [ option ...]。

同版本中文手册节选

描述

postgres 是 PostgreSQL 数据库服务器。客户端应用要访问数据库时，会（通过网络或本地）连接到一个正在运行的 postgres 实例。该 postgres 实例随后会启动一个独立的服务器进程来处理该连接。

一个 postgres 实例始终只管理一个数据库集簇的数据。数据库集簇是一组存储在同一文件系统位置（“数据区域”）中的数据库。只要使用不同的数据区域和不同的通信端口（见下文），一个系统上就可以同时运行多个 postgres 实例。当 postgres 启动时，它需要知道数据区域的位置。该位置必须通过 -D 选项或 PGDATA 环境变量指定；没有默认值。通常，-D 或 PGDATA 会直接指向由 initdb 创建的数据区域目录。其他可能的文件布局见第 19.2 节。

默认情况下，postgres 在前台启动，并将日志消息打印到标准错误流。在实际应用中，postgres 应作为后台进程启动，例如在系统启动时启动。

postgres 命令也可以在单用户模式下调用。这种模式的主要用途是在 initdb 执行引导期间使用。有时也会用它来调试或进行灾难恢复；但请注意，运行单用户服务器其实并不适合调试服务器，因为不会发生真实的进程间通信和锁定。从 shell 以单用户模式调用时，用户可以输入查询，结果会打印到屏幕上，但其形式对开发者更有用，而非面向终端用户。在单用户模式下，会话用户会被设置为 ID 为 1 的用户，并向该用户隐式授予超级用户权限。该用户实际上不必存在，因此单用户模式可用于手工恢复系统目录遭受某些意外损坏的情况。

选项

postgres 接受以下命令行参数。有关这些选项的详细讨论，请参阅第 19 章。通过设置配置文件，你可以省去键入其中大多数选项的麻烦。某些（安全的）选项还可以由连接的客户端以应用相关的方式设置，并且仅对该会话生效。例如，如果设置了环境变量 PGOPTIONS，那么基于 libpq 的客户端就会将该字符串传给服务器，服务器会将其解释为 postgres 命令行选项。

通用选项

-B nbuffers

设置供服务器进程使用的共享缓冲区数量。该参数的默认值由 initdb 自动选择。指定此选项等效于设置 shared_buffers 配置参数。

-c name=value

设置一个命名的运行时参数。PostgreSQL 支持的配置参数见第 19 章。大多数其他命令行选项实际上都是这种参数赋值的简写形式。-c 可以出现多次以设置多个参数。

-C name

打印指定运行时参数的值并退出。（详情见上面的 -c 选项。）这会返回 postgresql.conf 中的值，并应用本次调用中提供的任何参数修改。它不反映集簇启动时提供的参数。

对于大多数参数，这个选项可以在运行中的服务器上使用。不过，对于某些在运行时计算出的参数，服务器必须先关闭（例如 shared_memory_size、shared_memory_size_in_huge_pages 和 wal_segment_size）。

该选项供其他与服务器实例交互的程序（例如 pg_ctl）查询配置参数值之用。面向用户的应用则应使用 SHOW 或 pg_settings 视图。

-d debug-level

设置调试级别。该值设得越高，写入服务器日志的调试输出就越多。取值范围是 1 到 5。还可以针对某个特定会话传入 -d 0，从而阻止父 postgres 进程的服务器日志级别传播到该会话。

-D datadir

指定数据库配置文件在文件系统中的位置。详见第 19.2 节。

-e

将默认日期风格设置为“European”，即输入日期字段采用 DMY 顺序。这也会在某些日期输出格式中使日期显示为日在月前。更多信息见第 8.5 节。

-F

禁用 fsync 调用以提高性能，但在系统崩溃时会有数据损坏的风险。指定此选项等效于禁用 fsync 配置参数。使用前请先阅读详细文档！

-h hostname

指定 postgres 用来侦听来自客户端应用的 TCP/IP 连接的 IP 主机名或地址。该值也可以是逗号分隔的地址列表，或者用* 指定侦听所有可用接口。空值表示不侦听任何 IP 地址，在这种情况下只能使用 Unix 域套接字连接到服务器。默认只侦听 localhost。指定此选项等效于设置 listen_addresses 配置参数。

-i

允许远程客户端通过 TCP/IP（Internet 域）连接。没有此选项时，只接受本地连接。该选项等效于在 postgresql.conf 中，或通过 -h 将 listen_addresses 设置为*。

该选项已被弃用，因为它无法访问 listen_addresses 的全部功能。通常最好直接设置 listen_addresses。

-k directory

指定 postgres 用来侦听客户端应用连接的 Unix 域套接字所在目录。该值也可以是逗号分隔的目录列表。空值表示不侦听任何 Unix 域套接字，在这种情况下只能使用 TCP/IP 套接字连接到服务器。默认值通常是 /tmp，但可以在编译时更改。指定此选项等效于设置 unix_socket_directories 配置参数。

-l

启用使用 SSL 的安全连接。若要使用此选项，PostgreSQL 必须在编译时启用 SSL 支持。关于使用 SSL 的更多信息，请参阅第 18.9 节。

-N max-connections

设置该服务器将接受的最大客户端连接数。该参数的默认值由 initdb 自动选择。指定此选项等效于设置 max_connections 配置参数。

-p port

指定 postgres 用来侦听客户端应用连接的 TCP/IP 端口或本地 Unix 域套接字文件扩展名。默认值取自 PGPORT 环境变量；如果 PGPORT 未设置，则默认值就是在编译期间确定的值（通常为 5432）。如果你指定了非默认端口，那么所有客户端应用都必须通过命令行选项或 PGPORT 指定相同的端口。

-s

在每条命令结束时打印时间信息和其他统计信息。这对基准测试或者调整缓冲区数量很有用。

-S work-mem

指定排序和 hash 表在转而使用临时磁盘文件之前可使用的基础内存量。请参阅第 19.4.1 节中对 work_mem 配置参数的说明。

-V
--version

打印 postgres 的版本并退出。

--name=value

设置一个命名的运行时参数；这是 -c 的较短形式。

--describe-config

该选项会以制表符分隔的 COPY 格式导出服务器内部配置变量、说明以及默认值。它主要是为管理工具设计的。

-?
--help

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

半内部选项

这里描述的选项主要用于调试，并且在某些情况下可协助恢复严重损坏的数据库。在生产数据库环境中没有理由使用它们。这里列出这些选项，仅供 PostgreSQL 系统开发者使用。此外，这些选项在未来版本中可能会更改或被移除，且不另行通知。

-f { s | i | o | b | t | n | m | h }

禁止使用某些扫描和连接方法：s 和 i 分别禁用顺序扫描和索引扫描，o、b 和 t 分别禁用仅索引扫描、位图索引扫描和 TID 扫描，而 n、m 和 h 则分别禁用嵌套循环连接、归并连接和哈希连接。

顺序扫描和嵌套循环连接都无法被完全禁用；-fs 和 -fn 选项只是在优化器有其他选择时，尽量不使用这些计划类型。

-O

允许修改系统表的结构。该选项由 initdb 使用。

-P

读取系统表时忽略系统索引，但在修改表时仍然更新这些索引。这在从损坏的系统索引中恢复时很有用。

-t pa[rser] | pl[anner] | e[xecutor]

打印与各个主要系统模块相关的每个查询的时间统计信息。该选项不能与 -s 选项一起使用。

-T

该选项用于调试导致服务器进程异常终止的问题。在这种情况下，通常的策略是通过向所有其他服务器进程发送 SIGQUIT 信号，通知它们必须终止。使用此选项时，则会改为发送 SIGABRT，从而生成核心转储文件。

-v protocol

指定特定会话要使用的前端/后端协议版本号。该选项仅供内部使用。

-W seconds

新服务器进程在完成认证过程后，会延迟这么多秒。这是为了给调试器附着到该服务器进程提供机会。

用于单用户模式的选项

以下选项仅适用于单用户模式（见下文单用户模式）。

--single

选择单用户模式。这必须是命令行上的第一个参数。

database

指定要访问的数据库名称。这必须是命令行上的最后一个参数。如果省略，则默认为用户名。

-E

在执行前将所有命令回显到标准输出。

-j

使用“分号后跟两个换行符”而不是单个换行符，作为命令输入终止符。

-r filename

将所有服务器日志输出发送到 filename。只有将此选项作为命令行选项提供时，它才会生效。

查看完整中文手册与上下文。

说明

描述 postgres 是 PostgreSQL 数据库服务器。客户端应用要访问数据库时，会（通过网络或本地）连接到一个正在运行的 postgres 实例。该 postgres 实例随后会启动一个独立的服务器进程来处理该连接。 一个 postgres 实例始终只管理一个数据库集簇的数据。数据库集簇是一组存储在同一文件系统位置（ “ 数据区域 ” ）中的数据库。只要使用不同的数据区域和不同的通信端口（见下文），一个系统上就可以同时运行多个 postgres 实例。当 postgres 启动时，它需要知道数据区域的位置。该位置必须通过 -D 选项或 PGDATA 环境变量指定；没有默认值。通常， -D 或 PGDATA 会直接指向由 initdb 创建的数据区域目录。其他可能的文件布局见 第 19.2 节 。 默认情况下， postgres 在前台启动，并将日志消息打印到标准错误流。在实际应用中， postgres 应作为后台进程启动，例如在系统启动时启动。 postgres 命令也可以在单用户模式下调用。这种模式的主要用途是在 initdb 执行引导期间使用。有时也会用它来调试或进行灾难恢复；但请注意，运行单用户服务器其实并不适合调试服务器，因为不会发生真实的进程间通信和锁定。从 shell 以单用户模式调用时，用户可以输入查询，结果会打印到屏幕上，但其形式对开发者更有用，而非面向终端用户。在单用户模式下，会话用户会被设置为 ID 为 1 的用户，并向该用户隐式授予超级用户权限。该用户实际上不必存在，因此单用户模式可用于手工恢复系统目录遭受某些意外损坏的情况。 选项 postgres 接受以下命令行参数。有关这些选项的详细讨论，请参阅 第 19 章 。通过设置配置文件，你可以省去键入其中大多数选项的麻烦。某些（安全的）选项还可以由连接的客户端以应用相关的方式设置，并且仅对该会话生效。例如，如果设置了环境变量 PGOPTIONS ，那么基于 libpq 的客户端就会将该字符串传给服务器，服务器会将其解释为 postgres 命令行选项。 通用选项 -B nbuffers 设

手册中的可执行程序
postgres
程序版本
18.6
参考清单
服务端程序
选项定义组
30

用法

postgres [ option ...]

手册中的选项

选项与参数说明
-B nbuffers设置供服务器进程使用的共享缓冲区数量。该参数的默认值由 initdb 自动选择。指定此选项等效于设置 shared_buffers 配置参数。
-c name = value设置一个命名的运行时参数。 PostgreSQL 支持的配置参数见 第 19 章 。大多数其他命令行选项实际上都是这种参数赋值的简写形式。 -c 可以出现多次以设置多个参数。
-C name打印指定运行时参数的值并退出。（详情见上面的 -c 选项。）这会返回 postgresql.conf 中的值，并应用本次调用中提供的任何参数修改。它不反映集簇启动时提供的参数。
-d debug-level设置调试级别。值越大，写入服务器日志的调试输出越多。取值范围为 1 到 5。也可以为特定会话传入 -d 0，阻止父 postgres 进程的服务器日志级别传播到该会话。
-D datadir指定数据库配置文件在文件系统中的位置。详见 第 19.2 节 。
-e将默认日期风格设置为 “ European ” ，即输入日期字段采用 DMY 顺序。这也会在某些日期输出格式中使日期显示为日在月前。更多信息见 第 8.5 节 。
-F禁用 fsync 调用以提高性能，但在系统崩溃时会有数据损坏的风险。指定此选项等效于禁用 fsync 配置参数。使用前请先阅读详细文档！
-h hostname指定 postgres 用来侦听来自客户端应用的 TCP/IP 连接的 IP 主机名或地址。该值也可以是逗号分隔的地址列表，或者用 * 指定侦听所有可用接口。空值表示不侦听任何 IP 地址，在这种情况下只能使用 Unix 域套接字连接到服务器。默认只侦听 localhost 。指定此选项等效于设置 listen_addresses 配置参数。
-i允许远程客户端通过 TCP/IP（互联网域）连接。没有此选项时，只接受本地连接。此选项等同于在 postgresql.conf 中或通过 -h 将 listen_addresses 设为 *。
-k directory指定 postgres 用来侦听客户端应用连接的 Unix 域套接字所在目录。该值也可以是逗号分隔的目录列表。空值表示不侦听任何 Unix 域套接字，在这种情况下只能使用 TCP/IP 套接字连接到服务器。默认值通常是 /tmp ，但可以在编译时更改。指定此选项等效于设置 unix_socket_directories 配置参数。
-l启用使用 SSL 的安全连接。若要使用此选项， PostgreSQL 必须在编译时启用 SSL 支持。关于使用 SSL 的更多信息，请参阅 第 18.9 节 。
-N max-connections设置该服务器将接受的最大客户端连接数。该参数的默认值由 initdb 自动选择。指定此选项等效于设置 max_connections 配置参数。
-p port指定 postgres 用来侦听客户端应用连接的 TCP/IP 端口或本地 Unix 域套接字文件扩展名。默认值取自 PGPORT 环境变量；如果 PGPORT 未设置，则默认值就是在编译期间确定的值（通常为 5432）。如果你指定了非默认端口，那么所有客户端应用都必须通过命令行选项或 PGPORT 指定相同的端口。
-s在每条命令结束时打印时间信息和其他统计信息。这对基准测试或者调整缓冲区数量很有用。
-S work-mem指定排序和 hash 表在转而使用临时磁盘文件之前可使用的基础内存量。请参阅 第 19.4.1 节 中对 work_mem 配置参数的说明。
-V --version打印 postgres 的版本并退出。
-- name = value设置一个命名的运行时参数；这是 -c 的较短形式。
--describe-config该选项会以制表符分隔的 COPY 格式导出服务器内部配置变量、说明以及默认值。它主要是为管理工具设计的。
-? --help显示 postgres 命令行参数的帮助并退出。
-f { s | i | o | b | t | n | m | h }禁止使用某些扫描和连接方法： s 和 i 分别禁用顺序扫描和索引扫描， o 、 b 和 t 分别禁用仅索引扫描、位图索引扫描和 TID 扫描，而 n 、 m 和 h 则分别禁用嵌套循环连接、归并连接和哈希连接。
-O允许修改系统表的结构。该选项由 initdb 使用。
-P读取系统表时忽略系统索引，但在修改表时仍然更新这些索引。这在从损坏的系统索引中恢复时很有用。
-t pa[rser] | pl[anner] | e[xecutor]打印与各个主要系统模块相关的每个查询的时间统计信息。该选项不能与 -s 选项一起使用。
-T该选项用于调试导致服务器进程异常终止的问题。在这种情况下，通常的策略是通过向所有其他服务器进程发送 SIGQUIT 信号，通知它们必须终止。使用此选项时，则会改为发送 SIGABRT ，从而生成核心转储文件。
-v protocol指定特定会话要使用的前端/后端协议版本号。该选项仅供内部使用。
-W seconds新服务器进程在完成认证过程后，会延迟这么多秒。这是为了给调试器附着到该服务器进程提供机会。
--single选择单用户模式。这必须是命令行上的第一个参数。
-E在执行前将所有命令回显到标准输出。
-j使用“分号后跟两个换行符”而不是单个换行符，作为命令输入终止符。
-r filename将所有服务器日志输出发送到 filename 。只有将此选项作为命令行选项提供时，它才会生效。

环境变量

变量含义
PGCLIENTENCODING客户端使用的默认字符编码。（客户端可以单独覆盖它。）该值也可以在配置文件中设置。
PGDATA默认数据目录位置
PGDATESTYLEDateStyle 运行时参数的默认值。（该环境变量的用法已被弃用。）
PGPORT默认端口号（最好在配置文件中设置）

文档与源码

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

版本比较

PostgreSQL 14 → 15: 属性变化。

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

--- PostgreSQL 14
+++ PostgreSQL 15
@@ -33,7 +33,7 @@
       "signature": "-c name = value"
     },
     {
-      "description": "Prints the value of the named run-time parameter, and exits. (See the -c option above for details.) This can be used on a running server, and returns values from postgresql.conf , modified by any parameters supplied in this invocation. It does not reflect parameters supplied when the cluster was started. This option is meant for other programs that interact with a server instance, such as pg_ctl , to query configuration parameter values. User-facing applications should instead use SHOW or the pg_settings view.",
+      "description": "Prints the value of the named run-time parameter, and exits. (See the -c option above for details.) This returns values from postgresql.conf , modified by any parameters supplied in this invocation. It does not reflect parameters supplied when the cluster was started. This can be used on a running server for most parameters. However, the server must be shut down for some runtime-computed parameters (e.g., shared_memory_size , shared_memory_size_in_huge_pages , and wal_segment_size ). This option is meant for other programs that interact with a server instance, such as pg_ctl , to query configuration parameter values. User-facing applications should instead use SHOW or the pg_settings view.",
       "names": [
         "-C name"
       ],

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

相关条目

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