initdb

initdb — 创建一个新的 PostgreSQL 数据库集簇

当前查看 PostgreSQL 18.6。

说明

initdb — 创建一个新的 PostgreSQL 数据库集簇

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

用法

initdb [ option ...] [ --pgdata | -D ] directory

手册中的选项

选项与参数	说明
-A authmethod --auth= authmethod	该选项指定 pg_hba.conf 中本地用户默认使用的认证方法（ host 和 local 行）。有效值概览见第 20.1 节。
--auth-host= authmethod	该选项指定 pg_hba.conf 中本地用户通过 TCP/IP 连接时（ host 行）使用的认证方法。
--auth-local= authmethod	该选项指定 pg_hba.conf 中本地用户通过 Unix 域套接字连接时（ local 行）使用的认证方法。
-D directory --pgdata= directory	该选项指定数据库集簇应存放的目录。这是 initdb 所需的唯一信息，但也可以通过设置 PGDATA 环境变量来省去显式写出它；这通常更方便，因为数据库服务器（ postgres ）之后也可以通过同一变量找到数据目录。
-E encoding --encoding= encoding	选择模板数据库的编码。这也将成为以后创建的任何数据库的默认编码，除非在创建时覆盖它。 PostgreSQL 服务器支持的字符集见第 23.3.1 节。
-g --allow-group-access	允许与集簇拥有者同组的用户读取由 initdb 创建的所有集簇文件。该选项在 Windows 上会被忽略，因为它不支持 POSIX 风格的组权限。
--icu-locale= locale	当使用 ICU 提供程序时，指定 ICU 区域设置。区域设置支持见第 23.1 节。
--icu-rules= rules	指定附加的排序规则，以定制默认排序规则的行为。该选项仅支持 ICU。
-k --data-checksums	对数据页启用校验和，以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。该项默认启用；使用 --no-data-checksums 可禁用校验和。
--locale= locale	设置数据库集簇的默认区域设置。如果未指定该选项，区域设置将继承自 initdb 运行时所在的环境。区域设置支持见第 23.1 节。
--lc-collate= locale --lc-ctype= locale --lc-messages= locale --lc-monetary= locale --lc-numeric= locale --lc-time= locale	类似于 --locale ，但只在指定的类别中设置区域设置。
--no-locale	等价于 --locale=C 。
--builtin-locale= locale	当使用 builtin 提供程序时，指定区域设置名称。区域设置支持见第 23.1 节。
--locale-provider={ builtin \| libc \| icu }	该选项设置新集簇中创建的数据库所使用的区域设置提供程序。后续创建新数据库时，可以在 CREATE DATABASE 命令中覆盖它。默认值为 libc （见第 23.1.4 节）。
--no-data-checksums	不启用数据校验和。
--pwfile= filename	使 initdb 从文件中读取引导超级用户的密码。文件的第一行会被当作密码。
-T config --text-search-config= config	设置默认文本检索配置。更多信息见 default_text_search_config 。
-U username --username= username	设置引导超级用户的用户名。默认值是运行 initdb 的操作系统用户名。
-W --pwprompt	使 initdb 提示输入要赋给引导超级用户的密码。如果不打算使用密码认证，这一点并不重要。否则，在设置密码之前将无法使用密码认证。
-X directory --waldir= directory	该选项指定预写式日志（WAL）应存放的目录。
--wal-segsize= size	设置 WAL 段大小，单位为兆字节。这是 WAL 日志中每个独立文件的大小。默认大小为 16 兆字节。取值必须是 1 到 1024（兆字节）之间的 2 的幂。此选项只能在初始化时设置，之后无法更改。
-c name = value --set name = value	在 initdb 期间强制将服务器参数 name 设为 value，并把该设置写入生成的 postgresql.conf 文件，使其在之后的服务器运行中也生效。此选项可多次使用，以设置多个参数。它主要用于环境条件导致服务器完全无法使用默认参数启动的情况。
-d --debug	打印引导后端的调试输出，以及少量普通用户通常不感兴趣的其他消息。引导后端是 initdb 用来创建系统目录表的程序。该选项会产生大量极其乏味的输出。
--discard-caches	使用 debug_discard_caches=1 选项运行引导后端。这会花费很长时间，只对深度调试有用。
-L directory	指定 initdb 初始化数据库集簇时应到哪里查找其输入文件。通常不需要这样做。若需要显式指定其位置，系统会提示。
-n --no-clean	默认情况下，如果 initdb 发现某个错误使其无法完整创建数据库集簇，就会删除它在发现无法完成任务之前可能已创建的所有文件。该选项会禁止这种清理，因此对调试有用。
-N --no-sync	默认情况下， initdb 会等待所有文件都安全写入磁盘。该选项使 initdb 在不等待的情况下返回，速度更快，但这意味着如果后续操作系统崩溃，数据目录可能会损坏。通常，该选项适用于测试，但不应用于创建生产环境安装。
--no-sync-data-files	默认情况下， initdb 会将所有数据库文件安全地写入磁盘。该选项指示 initdb 跳过同步各个数据库目录中的所有文件、这些数据库目录本身以及表空间目录，也就是 base 子目录中的所有内容和任何其他表空间目录。其他文件，例如 pg_wal 和 pg_xact 中的文件，仍会被同步，除非也指定了 --no-sync 。
--no-instructions	默认情况下， initdb 会在其输出末尾写出如何启动集簇的说明。该选项会省略这些说明。它主要供那些对 initdb 进行平台特定封装的工具使用，因为在这种情况下那些说明很可能并不正确。
-s --show	显示内部设置并退出，不执行其他操作。可用于调试 initdb 的安装。
--sync-method= method	设为 fsync （默认值）时， initdb 会递归打开并同步数据目录中的所有文件。查找文件时会跟随 WAL 目录和每个已配置表空间的符号链接。
-S --sync-only	将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 initdb 操作。通常，该选项可用于在将 fsync 从 off 改为 on 后，确保能够可靠恢复。
-V --version	打印 initdb 版本并退出。
-? --help	显示有关 initdb 命令行参数的帮助并退出。

环境变量

变量	含义
PGDATA	指定数据库集簇应存放的目录；可使用 -D 选项覆盖。
PG_COLOR	指定诊断消息是否使用颜色。可选值为 always 、 auto 和 never 。
TZ	指定所创建数据库集簇的默认时区。该值应为完整的时区名称（见第 8.5.3 节）。

手册定义

initdb

initdb — 创建一个新的PostgreSQL数据库集簇

大纲

initdb [option...] [ --pgdata | -D ] directory

说明

initdb创建一个新的PostgreSQL 数据库集簇。

创建数据库集簇包括创建用于存放集簇数据的目录，生成共享系统目录表（属于整个集簇而不是某个特定数据库的表），以及创建 postgres、template1 和 template0 数据库。postgres 数据库是一个默认数据库，供用户、工具程序和第三方应用程序使用。template1 和 template0 用作后续CREATE DATABASE命令复制的源数据库。template0 不应被修改，但可以向 template1 中添加对象，这些对象默认会被复制到以后创建的数据库中。更多细节见第 22.3 节。

虽然initdb会尝试创建指定的数据目录，但如果所需数据目录的父目录归 root 所有，它可能没有足够的权限。要在这种环境中初始化，可先由 root 创建一个空的数据目录，然后用chown将该目录的所有权赋予数据库用户账户，再用 su切换为该数据库用户来运行initdb。

initdb必须以将拥有服务器进程的用户身份运行，因为服务器需要访问 initdb创建的文件和目录。由于服务器不能以 root 身份运行，因此也绝不能以 root 身份运行initdb。（实际上它会拒绝这样做。）

出于安全原因，initdb创建的新集簇默认只有集簇拥有者可以访问。--allow-group-access 选项允许与集簇拥有者同组的任何用户读取集簇中的文件。这对由非特权用户执行备份很有用。

initdb会初始化数据库集簇的默认区域设置和字符集编码。这些设置也可以在创建每个数据库时分别设置。initdb为模板数据库确定这些设置，它们将作为所有其他数据库的默认值。

默认情况下，initdb使用libc区域设置提供程序（见第 23.1.4 节）。libc区域设置提供程序会从环境中获取区域设置，并根据区域设置确定编码。

要为集簇选择不同的区域设置，请使用--locale。此外还有单独的 --lc-* 和 --icu-locale 选项（见下文），用于为各个区域设置类别设置值。请注意，不同区域设置类别之间若设置不一致，可能产生不合理的结果，因此应谨慎使用。

也可以指定 --locale-provider=icu，让 initdb 使用 ICU 库提供区域设置服务。服务器必须在构建时启用 ICU 支持。使用 --icu-locale 选项选择具体的 ICU 区域 ID。注意，出于实现方面的原因以及对旧代码的兼容，即使使用 ICU 区域设置提供者，initdb 仍会选择并初始化 libc 区域设置。

initdb运行时会打印出它选择的区域设置。如果有复杂需求或者指定了多个选项，建议检查结果是否符合预期。

有关区域设置的更多细节见第 23.1 节。

要修改默认编码，请使用--encoding。更多细节见第 23.3 节。

选项

-A authmethod --auth=authmethod

该选项指定pg_hba.conf中本地用户默认使用的认证方法（host 和 local 行）。有效值概览见第 20.1 节。

initdb会使用指定的认证方法预填充pg_hba.conf 条目，既用于非复制连接，也用于复制连接。

除非信任系统上的所有本地用户，否则不要使用trust。为了便于安装，默认使用trust。

--auth-host=authmethod

该选项指定pg_hba.conf中本地用户通过 TCP/IP 连接时（host 行）使用的认证方法。

--auth-local=authmethod

该选项指定pg_hba.conf中本地用户通过 Unix 域套接字连接时（local 行）使用的认证方法。

-D directory --pgdata=directory

该选项指定数据库集簇应存放的目录。这是initdb所需的唯一信息，但也可以通过设置PGDATA环境变量来省去显式写出它；这通常更方便，因为数据库服务器（postgres）之后也可以通过同一变量找到数据目录。

-E encoding --encoding=encoding

选择模板数据库的编码。这也将成为以后创建的任何数据库的默认编码，除非在创建时覆盖它。PostgreSQL服务器支持的字符集见第 23.3.1 节。

默认情况下，模板数据库的编码由区域设置决定。如果指定 --no-locale（或等价地将区域设置设为 C 或 POSIX），则 ICU 提供者的默认编码为 UTF8，libc 提供者的默认编码为 SQL_ASCII。

-g --allow-group-access

允许与集群所有者同组的用户读取 initdb 创建的所有集群文件。Windows 不支持 POSIX 风格的组权限，因此会忽略此选项。

--icu-locale=locale

当使用 ICU 提供程序时，指定 ICU 区域设置。区域设置支持见第 23.1 节。

--icu-rules=rules

指定附加的排序规则，以定制默认排序规则的行为。该选项仅支持 ICU。

-k --data-checksums

对数据页启用校验和，以帮助检测原本会悄无声息发生的、由 I/O 系统导致的损坏。该项默认启用；使用--no-data-checksums可禁用校验和。

启用校验和可能会带来小幅性能损失。如果启用，就会为所有数据库中的所有对象计算校验和。所有校验和失败都会在 pg_stat_database视图中报告。详见第 28.2 节。

--locale=locale

设置数据库集簇的默认区域设置。如果未指定该选项，区域设置将继承自 initdb运行时所在的环境。区域设置支持见第 23.1 节。

如果--locale-provider为builtin，则必须指定--locale或--builtin-locale，并将其设置为C、C.UTF-8或 PG_UNICODE_FAST。

--lc-collate=locale --lc-ctype=locale --lc-messages=locale --lc-monetary=locale --lc-numeric=locale --lc-time=locale

类似于--locale，但只在指定的类别中设置区域设置。

--no-locale

等价于--locale=C。

--builtin-locale=locale

当使用 builtin 提供程序时，指定区域设置名称。区域设置支持见第 23.1 节。

--locale-provider={builtin|libc|icu}

该选项设置新集簇中创建的数据库所使用的区域设置提供程序。后续创建新数据库时，可以在CREATE DATABASE命令中覆盖它。默认值为 libc（见第 23.1.4 节）。

--no-data-checksums

不启用数据校验和。

--pwfile=filename

使initdb从文件中读取引导超级用户的密码。文件的第一行会被当作密码。

-T config --text-search-config=config

设置默认文本检索配置。更多信息见default_text_search_config。

-U username --username=username

设置引导超级用户的用户名。默认值是运行initdb的操作系统用户名。

-W --pwprompt

使initdb提示输入要赋给引导超级用户的密码。如果不打算使用密码认证，这一点并不重要。否则，在设置密码之前将无法使用密码认证。

-X directory --waldir=directory

该选项指定预写式日志（WAL）应存放的目录。

--wal-segsize=size

设置 WAL 段大小，单位为兆字节。这是 WAL 日志中每个独立文件的大小。默认大小为 16 兆字节。取值必须是 1 到 1024（兆字节）之间的 2 的幂。此选项只能在初始化时设置，之后无法更改。

调整该大小可能有助于控制 WAL 日志传送或归档的粒度。此外，在 WAL 量很大的数据库中，每个目录中的 WAL 文件数量可能会成为性能和管理问题。增大 WAL 文件大小会减少 WAL 文件数量。

还提供了其他一些较少使用的选项：

-c name=value --set name=value

在 initdb 期间强制将服务器参数 name 设为 value，并把该设置写入生成的 postgresql.conf 文件，使其在之后的服务器运行中也生效。此选项可多次使用，以设置多个参数。它主要用于环境条件导致服务器完全无法使用默认参数启动的情况。

-d --debug

打印引导后端的调试输出，以及少量普通用户通常不感兴趣的其他消息。引导后端是 initdb用来创建系统目录表的程序。该选项会产生大量极其乏味的输出。

--discard-caches

使用debug_discard_caches=1选项运行引导后端。这会花费很长时间，只对深度调试有用。

-L directory

指定initdb初始化数据库集簇时应到哪里查找其输入文件。通常不需要这样做。若需要显式指定其位置，系统会提示。

-n --no-clean

默认情况下，如果initdb发现某个错误使其无法完整创建数据库集簇，就会删除它在发现无法完成任务之前可能已创建的所有文件。该选项会禁止这种清理，因此对调试有用。

-N --no-sync

默认情况下，initdb会等待所有文件都安全写入磁盘。该选项使 initdb在不等待的情况下返回，速度更快，但这意味着如果后续操作系统崩溃，数据目录可能会损坏。通常，该选项适用于测试，但不应用于创建生产环境安装。

--no-sync-data-files

默认情况下，initdb会将所有数据库文件安全地写入磁盘。该选项指示initdb跳过同步各个数据库目录中的所有文件、这些数据库目录本身以及表空间目录，也就是base子目录中的所有内容和任何其他表空间目录。其他文件，例如pg_wal和pg_xact中的文件，仍会被同步，除非也指定了--no-sync。

请注意，如果--no-sync-data-files与 --sync-method=syncfs一起使用，上述部分或全部文件与目录仍会被同步，因为syncfs处理的是整个文件系统。

该选项主要供那些会另行确保这些被跳过文件已同步到磁盘的工具在内部使用。

--no-instructions

默认情况下，initdb会在其输出末尾写出如何启动集簇的说明。该选项会省略这些说明。它主要供那些对initdb进行平台特定封装的工具使用，因为在这种情况下那些说明很可能并不正确。

-s --show

显示内部设置并退出，不执行其他操作。可用于调试initdb的安装。

--sync-method=method

设为fsync（默认值）时，initdb会递归打开并同步数据目录中的所有文件。查找文件时会跟随 WAL 目录和每个已配置表空间的符号链接。

在 Linux 上，也可以改用syncfs，请求操作系统同步包含数据目录、WAL 文件以及每个表空间的整个文件系统。使用syncfs时需注意的事项见recovery_init_sync_method。

使用--no-sync时，该选项不起作用。

-S --sync-only

将所有数据库文件安全地写入磁盘并退出。这不会执行任何常规的 initdb操作。通常，该选项可用于在将fsync从off改为on后，确保能够可靠恢复。

其他选项：

-V --version

打印initdb版本并退出。

-? --help

显示有关initdb命令行参数的帮助并退出。

环境

PGDATA

指定数据库集簇应存放的目录；可使用-D选项覆盖。

PG_COLOR

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

TZ

指定所创建数据库集簇的默认时区。该值应为完整的时区名称（见第 8.5.3 节）。

注解

也可以通过 pg_ctl initdb 调用 initdb。

另见

pg_ctl, postgres, Section 20.1

文档与源码

来源构建

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

版本比较

PostgreSQL 14 → 15: 属性变化。

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

--- PostgreSQL 14
+++ PostgreSQL 15
@@ -15,7 +15,7 @@
   ],
   "options": [
     {
-      "description": "This option specifies the default authentication method for local users used in pg_hba.conf ( host and local lines). initdb will prepopulate pg_hba.conf entries using the specified authentication method for non-replication as well as replication connections. Do not use trust unless you trust all local users on your system. trust is the default for ease of installation.",
+      "description": "This option specifies the default authentication method for local users used in pg_hba.conf ( host and local lines). See Section 21.1 for an overview of valid values. initdb will prepopulate pg_hba.conf entries using the specified authentication method for non-replication as well as replication connections. Do not use trust unless you trust all local users on your system. trust is the default for ease of installation.",
       "names": [
         "-A authmethod",
         "--auth= authmethod"
@@ -45,7 +45,7 @@
       "signature": "-D directory --pgdata= directory"
     },
     {
-      "description": "Selects the encoding of the template database. This will also be the default encoding of any database you create later, unless you override it there. The default is derived from the locale, or SQL_ASCII if that does not work. The character sets supported by the PostgreSQL server are described in Section 24.3.1 .",
+      "description": "Selects the encoding of the template databases. This will also be the default encoding of any database you create later, unless you override it then. The default is derived from the locale, if the libc locale provider is used, or UTF8 if the ICU locale provider is used. The character sets supported by the PostgreSQL server are described in Section 24.3.1 .",
       "names": [
         "-E encoding",
         "--encoding= encoding"
@@ -59,6 +59,13 @@
         "--allow-group-access"
       ],
       "signature": "-g --allow-group-access"
+    },
+    {
+      "description": "Specifies the ICU locale ID, if the ICU locale provider is used.",
+      "names": [
+        "--icu-locale= locale"
+      ],
+      "signature": "--icu-locale= locale"
     },
     {
       "description": "Use checksums on data pages to help detect corruption by the I/O system that would otherwise be silent. Enabling checksums may incur a noticeable performance penalty. If set, checksums are calculated for all objects, in all databases. All checksum failures will be reported in the pg_stat_database view. See Section 30.2 for details.",
@@ -95,6 +102,13 @@
       "signature": "--no-locale"
     },
     {
+      "description": "This option sets the locale provider for databases created in the new cluster. It can be overridden in the CREATE DATABASE command when new databases are subsequently created. The default is libc .",
+      "names": [
+        "--locale-provider={ libc | icu }"
+      ],
+      "signature": "--locale-provider={ libc | icu }"
+    },
+    {
       "description": "By default, initdb will wait for all files to be written safely to disk. This option causes initdb to return without waiting, which is faster, but means that a subsequent operating system crash can leave the data directory corrupt. Generally, this option is useful for testing, but should not be used when creating a production installation.",
       "names": [
         "-N",
@@ -117,7 +131,7 @@
       "signature": "--pwfile= filename"
     },
     {
-      "description": "Safely write all database files to disk and exit. This does not perform any of the normal initdb operations.",
+      "description": "Safely write all database files to disk and exit. This does not perform any of the normal initdb operations. Generally, this option is useful for ensuring reliable recovery after changing fsync from off to on .",
       "names": [
         "-S",
         "--sync-only"

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

快速链接

initdb

说明

用法

手册中的选项

环境变量

手册定义

initdb

大纲

说明

选项

环境

注解

另见

文档与源码

版本比较

相关条目