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

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

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

postgres

postgres — PostgreSQL 数据库服务器

当前查看 PostgreSQL 18.6。

说明

postgres — PostgreSQL 数据库服务器

手册中的可执行程序
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默认端口号（最好在配置文件中设置）

手册定义

postgres

postgres — PostgreSQL数据库服务器

大纲

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（互联网域）连接。没有此选项时，只接受本地连接。此选项等同于在 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-User Mode）。

--single

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

database

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

-E

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

-j

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

-r filename

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

环境

PGCLIENTENCODING

客户端使用的默认字符编码。（客户端可以单独覆盖它。）该值也可以在配置文件中设置。

PGDATA

默认数据目录位置

PGDATESTYLE

DateStyle运行时参数的默认值。（该环境变量的用法已被弃用。）

PGPORT

默认端口号（最好在配置文件中设置）

诊断

提到semget或 shmget的失败消息，很可能表明你需要配置内核，以提供足够的共享内存和信号量。更多讨论见第 18.4 节。你也许可以通过降低shared_buffers来减少PostgreSQL的共享内存消耗，以及/或通过降低max_connections来减少信号量消耗，从而推迟重新配置内核。

表明另一个服务器已经在运行的失败消息应仔细检查，例如可根据你的系统使用下面的命令：

$ ps ax | grep postgres

或

$ ps -ef | grep postgres

如果你确信没有冲突的服务器在运行，可以删除消息中提到的锁文件，然后重试。

表明无法绑定端口的失败消息，可能意味着该端口已经被某个非PostgreSQL进程占用。你在终止postgres 后如果立即使用同一端口重新启动它，也可能会得到这个错误；在这种情况下，你只需等待几秒钟，直到操作系统关闭该端口后再重试。最后，如果你指定了一个操作系统认为是保留的端口号，也可能会收到这个错误。例如，许多版本的 Unix 认为低于 1024 的端口号是“受信任的”，并且只允许 Unix 超级用户访问它们。

注解

实用命令pg_ctl可用于安全、便捷地启动和关闭postgres服务器。

只要有可能，就不要使用 SIGKILL杀死主 postgres服务器。这样会阻止 postgres在终止前释放其持有的系统资源（例如共享内存和信号量）。这可能会导致新的postgres实例在启动时出现问题。

要正常终止postgres服务器，可以使用 SIGTERM、SIGINT或 SIGQUIT信号。第一个会在退出前等待所有客户端终止，第二个会强制断开所有客户端，而第三个会在不进行正确关闭的情况下立即退出，从而在重启期间导致一次恢复运行。

SIGHUP信号会重新加载服务器配置文件。也可以向单个服务器进程发送 SIGHUP，但这通常没有意义。

要取消一个正在运行的查询，可以向执行该命令的进程发送SIGINT信号。要干净地终止一个后端进程，可以向该进程发送SIGTERM。这两种操作在 SQL 中可调用的等效形式，见第 9.28.2 节中的pg_cancel_backend和pg_terminate_backend。

postgres服务器使用SIGQUIT 通知从属服务器进程在不进行正常清理的情况下终止。用户不应该使用这个信号。向某个服务器进程发送SIGKILL也是不明智的 — 主postgres进程会将其解释为一次崩溃，并作为其标准崩溃恢复过程的一部分强制所有同级进程退出。

缺陷

--选项在FreeBSD或OpenBSD上不起作用。请改用-c。这是受影响操作系统中的一个缺陷；如果这个问题未被修复，未来版本的PostgreSQL 将提供变通方案。

单用户模式

要启动单用户模式服务器，可以使用类似下面的命令：

postgres --single -D /usr/local/pgsql/data other-options my_database

使用-D提供正确的数据库目录路径，或者确保已经设置了环境变量PGDATA。还要指定你想要操作的那个数据库的名称。

通常，单用户模式服务器将换行视为命令输入终止符；它不像psql那样会对分号进行智能处理。要让一个命令跨越多行，必须在除最后一个换行之外的每个换行前输入反斜线。反斜线和紧邻的换行都会从输入命令中删除。注意，即使在字符串字面量或注释中也会如此。

但是，如果你使用-j命令行开关，单个换行并不会终止命令输入；取而代之的是使用“分号-换行-换行”这一序列。也就是说，输入一个分号，后面立刻跟着一个完全空白的行。在这种模式下，反斜线-换行不会被特殊处理。同样，对于这种序列出现在字符串字面量或注释中的情况，也不会有特殊处理。

在任一种输入模式中，如果你输入的分号既不恰好位于命令输入终止符之前，也不是命令输入终止符的一部分，那么它就会被视为命令分隔符。当你输入命令输入终止符时，已输入的多条语句会作为单个事务执行。

要退出会话，输入EOF（通常是Control+D）。如果自上一个命令输入终止符以来你已经输入了任何文本，那么EOF会被视为命令输入终止符，你还需要再输入一次EOF才能退出。

请注意，单用户模式服务器不提供复杂的行编辑功能（例如没有命令历史）。单用户模式也不会执行任何后台处理，例如自动检查点或复制。

示例

要使用默认值在后台启动postgres，输入：

$ nohup postgres >logfile 2>&1 </dev/null &

要用指定端口启动postgres，例如 1234：

$ postgres -p 1234

使用 psql 连接此服务器时，用 -p 选项指定该端口：

$ psql -p 1234

或者设置环境变量PGPORT：

$ export PGPORT=1234
$ psql

命名的运行时参数可以采用以下任一种形式设置：

$ postgres -c work_mem=1234
$ postgres --work-mem=1234

这两种形式都会覆盖 postgresql.conf 中可能存在的 work_mem 设置。注意，命令行上的参数名可以用下划线或连字符表示原有的下划线。除了短期试验，通常更好的做法是修改 postgresql.conf 中的设置，而不是依赖命令行选项设置参数。

另见

initdb, pg_ctl

文档与源码

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

版本比较

PostgreSQL 13 → 14: 属性变化。

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

--- PostgreSQL 13
+++ PostgreSQL 14
@@ -26,7 +26,7 @@
       "signature": "-B nbuffers"
     },
     {
-      "description": "Sets a named run-time parameter. The configuration parameters supported by PostgreSQL are described in Chapter 19 . Most of the other command line options are in fact short forms of such a parameter assignment. -c can appear multiple times to set multiple parameters.",
+      "description": "Sets a named run-time parameter. The configuration parameters supported by PostgreSQL are described in Chapter 20 . Most of the other command line options are in fact short forms of such a parameter assignment. -c can appear multiple times to set multiple parameters.",
       "names": [
         "-c name = value"
       ],
@@ -47,7 +47,7 @@
       "signature": "-d debug-level"
     },
     {
-      "description": "Specifies the file system location of the database configuration files. See Section 19.2 for details.",
+      "description": "Specifies the file system location of the database configuration files. See Section 20.2 for details.",
       "names": [
         "-D datadir"
       ],
@@ -89,7 +89,7 @@
       "signature": "-k directory"
     },
     {
-      "description": "Enables secure connections using SSL . PostgreSQL must have been compiled with support for SSL for this option to be available. For more information on using SSL , refer to Section 18.9 .",
+      "description": "Enables secure connections using SSL . PostgreSQL must have been compiled with support for SSL for this option to be available. For more information on using SSL , refer to Section 19.9 .",
       "names": [
         "-l"
       ],
@@ -103,13 +103,6 @@
       "signature": "-N max-connections"
     },
     {
-      "description": "The command-line-style arguments specified in extra-options are passed to all server processes started by this postgres process. Spaces within extra-options are considered to separate arguments, unless escaped with a backslash ( \\ ); write \\\\ to represent a literal backslash. Multiple arguments can also be specified via multiple uses of -o . The use of this option is obsolete; all command-line options for server processes can be specified directly on the postgres command line.",
-      "names": [
-        "-o extra-options"
-      ],
-      "signature": "-o extra-options"
-    },
-    {
       "description": "Specifies the TCP/IP port or local Unix domain socket file extension on which postgres is to listen for connections from client applications. Defaults to the value of the PGPORT environment variable, or if PGPORT is not set, then defaults to the value established during compilation (normally 5432). If you specify a port other than the default port, then all client applications must specify the same port using either command-line options or PGPORT .",
       "names": [
         "-p port"
@@ -124,7 +117,7 @@
       "signature": "-s"
     },
     {
-      "description": "Specifies the base amount of memory to be used by sorts and hash tables before resorting to temporary disk files. See the description of the work_mem configuration parameter in Section 19.4.1 .",
+      "description": "Specifies the base amount of memory to be used by sorts and hash tables before resorting to temporary disk files. See the description of the work_mem configuration parameter in Section 20.4.1 .",
       "names": [
         "-S"
       ],

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

相关条目

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