1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2010-09-20 22:08:53 +02:00
|
|
|
doc/src/sgml/ref/initdb.sgml
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refentry id="app-initdb">
|
2014-02-24 03:25:35 +01:00
|
|
|
<indexterm zone="app-initdb">
|
|
|
|
<primary>initdb</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmeta>
|
2020-07-10 16:51:29 +02:00
|
|
|
<refentrytitle><application>initdb</application></refentrytitle>
|
2000-11-12 00:01:45 +01:00
|
|
|
<manvolnum>1</manvolnum>
|
1999-07-06 19:16:42 +02:00
|
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
|
|
</refmeta>
|
2000-11-12 00:01:45 +01:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refnamediv>
|
2000-11-12 00:01:45 +01:00
|
|
|
<refname>initdb</refname>
|
2001-09-03 14:57:50 +02:00
|
|
|
<refpurpose>create a new <productname>PostgreSQL</productname> database cluster</refpurpose>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refnamediv>
|
2000-11-12 00:01:45 +01:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2000-11-12 00:01:45 +01:00
|
|
|
<cmdsynopsis>
|
|
|
|
<command>initdb</command>
|
2011-03-09 15:18:44 +01:00
|
|
|
<arg rep="repeat"><replaceable>option</replaceable></arg>
|
2002-10-12 01:03:48 +02:00
|
|
|
<group choice="plain">
|
2012-04-30 20:15:48 +02:00
|
|
|
<group choice="opt">
|
2012-05-03 21:50:04 +02:00
|
|
|
<arg choice="plain"><option>--pgdata</option></arg>
|
|
|
|
<arg choice="plain"><option>-D</option></arg>
|
2012-04-30 20:15:48 +02:00
|
|
|
</group>
|
|
|
|
<replaceable> directory</replaceable>
|
2002-10-12 01:03:48 +02:00
|
|
|
</group>
|
2000-11-12 00:01:45 +01:00
|
|
|
</cmdsynopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
2017-10-20 03:16:39 +02:00
|
|
|
<refsect1 id="r1-app-initdb-1">
|
2020-06-07 13:10:18 +02:00
|
|
|
<title>Description</title>
|
2000-11-12 00:01:45 +01:00
|
|
|
<para>
|
2001-09-08 17:24:00 +02:00
|
|
|
<command>initdb</command> creates a new
|
2022-11-18 11:59:26 +01:00
|
|
|
<productname>PostgreSQL</productname> <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
|
2000-11-12 00:01:45 +01:00
|
|
|
</para>
|
2001-09-08 17:24:00 +02:00
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
<para>
|
2022-11-18 11:59:26 +01:00
|
|
|
Creating a database cluster consists of creating the
|
|
|
|
<glossterm linkend="glossary-data-directory">directories</glossterm> in
|
|
|
|
which the cluster data will live, generating the shared catalog
|
2005-02-22 03:54:19 +01:00
|
|
|
tables (tables that belong to the whole cluster rather than to any
|
2021-11-02 17:54:35 +01:00
|
|
|
particular database), and creating the <literal>postgres</literal>,
|
|
|
|
<literal>template1</literal>, and <literal>template0</literal> databases.
|
2005-06-21 06:02:34 +02:00
|
|
|
The <literal>postgres</literal> database is a default database meant
|
|
|
|
for use by users, utilities and third party applications.
|
2021-11-02 17:54:35 +01:00
|
|
|
<literal>template1</literal> and <literal>template0</literal> are
|
|
|
|
meant as source databases to be copied by later <command>CREATE
|
|
|
|
DATABASE</command> commands. <literal>template0</literal> should never
|
|
|
|
be modified, but you can add objects to <literal>template1</literal>,
|
|
|
|
which by default will be copied into databases created later. See
|
|
|
|
<xref linkend="manage-ag-templatedbs"/> for more details.
|
2000-11-12 00:01:45 +01:00
|
|
|
</para>
|
|
|
|
|
2002-04-03 07:39:33 +02:00
|
|
|
<para>
|
2005-02-22 03:54:19 +01:00
|
|
|
Although <command>initdb</command> will attempt to create the
|
|
|
|
specified data directory, it might not have permission if the parent
|
|
|
|
directory of the desired data directory is root-owned. To initialize
|
|
|
|
in such a setup, create an empty data directory as root, then use
|
|
|
|
<command>chown</command> to assign ownership of that directory to the
|
|
|
|
database user account, then <command>su</command> to become the
|
|
|
|
database user to run <command>initdb</command>.
|
2002-04-03 07:39:33 +02:00
|
|
|
</para>
|
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
<para>
|
2001-09-08 17:24:00 +02:00
|
|
|
<command>initdb</command> must be run as the user that will own the
|
|
|
|
server process, because the server needs to have access to the
|
|
|
|
files and directories that <command>initdb</command> creates.
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
Since the server cannot be run as root, you must not run
|
2001-09-08 17:24:00 +02:00
|
|
|
<command>initdb</command> as root either. (It will in fact refuse
|
|
|
|
to do so.)
|
2000-11-12 00:01:45 +01:00
|
|
|
</para>
|
|
|
|
|
2018-04-07 23:45:39 +02:00
|
|
|
<para>
|
|
|
|
For security reasons the new cluster created by <command>initdb</command>
|
|
|
|
will only be accessible by the cluster owner by default. The
|
|
|
|
<option>--allow-group-access</option> option allows any user in the same
|
|
|
|
group as the cluster owner to read files in the cluster. This is useful
|
|
|
|
for performing backups as a non-privileged user.
|
|
|
|
</para>
|
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
<para>
|
2022-03-17 11:11:21 +01:00
|
|
|
<command>initdb</command> initializes the database cluster's default locale
|
|
|
|
and character set encoding. These can also be set separately for each
|
|
|
|
database when it is created. <command>initdb</command> determines those
|
|
|
|
settings for the template databases, which will serve as the default for
|
2023-03-09 19:52:41 +01:00
|
|
|
all other databases.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
By default, <command>initdb</command> uses the ICU library to provide
|
|
|
|
locale services if the server was built with ICU support; otherwise it uses
|
|
|
|
the <literal>libc</literal> locale provider (see <xref
|
|
|
|
linkend="locale-providers"/>). To choose the specific ICU locale ID to
|
|
|
|
apply, use the option <option>--icu-locale</option>. Note that for
|
|
|
|
implementation reasons and to support legacy code,
|
|
|
|
<command>initdb</command> will still select and initialize libc locale
|
|
|
|
settings when the ICU locale provider is used.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Alternatively, <command>initdb</command> can use the locale provider
|
|
|
|
<literal>libc</literal>. To select this option, specify
|
|
|
|
<literal>--locale-provider=libc</literal>, or build the server without ICU
|
|
|
|
support. The <literal>libc</literal> locale provider takes the locale
|
|
|
|
settings from the environment, and determines the encoding from the locale
|
|
|
|
settings. This is almost always sufficient, unless there are special
|
|
|
|
requirements.
|
2008-09-23 11:20:39 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2022-03-17 11:11:21 +01:00
|
|
|
To choose a different locale for the cluster, use the option
|
|
|
|
<option>--locale</option>. There are also individual options
|
|
|
|
<option>--lc-*</option> (see below) to set values for the individual locale
|
|
|
|
categories. Note that inconsistent settings for different locale
|
|
|
|
categories can give nonsensical results, so this should be used with care.
|
2008-09-23 11:20:39 +02:00
|
|
|
</para>
|
|
|
|
|
2022-03-17 11:11:21 +01:00
|
|
|
<para>
|
|
|
|
When <command>initdb</command> runs, it will print out the locale settings
|
|
|
|
it has chosen. If you have complex requirements or specified multiple
|
|
|
|
options, it is advisable to check that the result matches what was
|
|
|
|
intended.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
More details about locale settings can be found in <xref
|
|
|
|
linkend="locale"/>.
|
2000-11-12 00:01:45 +01:00
|
|
|
</para>
|
2005-02-22 03:54:19 +01:00
|
|
|
|
|
|
|
<para>
|
2008-09-23 11:20:39 +02:00
|
|
|
To alter the default encoding, use the <option>--encoding</option>.
|
2017-11-23 15:39:47 +01:00
|
|
|
More details can be found in <xref linkend="multibyte"/>.
|
2005-02-22 03:54:19 +01:00
|
|
|
</para>
|
|
|
|
|
2002-10-12 01:03:48 +02:00
|
|
|
</refsect1>
|
2000-11-12 00:01:45 +01:00
|
|
|
|
2002-10-12 01:03:48 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>Options</title>
|
1998-10-05 04:54:45 +02:00
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
<para>
|
1999-07-06 19:16:42 +02:00
|
|
|
<variablelist>
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-auth">
|
2004-08-01 08:19:26 +02:00
|
|
|
<term><option>-A <replaceable class="parameter">authmethod</replaceable></option></term>
|
|
|
|
<term><option>--auth=<replaceable class="parameter">authmethod</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-03-09 14:27:16 +01:00
|
|
|
This option specifies the default authentication method for local
|
2017-10-09 03:44:17 +02:00
|
|
|
users used in <filename>pg_hba.conf</filename> (<literal>host</literal>
|
2022-05-14 09:57:03 +02:00
|
|
|
and <literal>local</literal> lines). See <xref linkend="auth-pg-hba-conf"/>
|
|
|
|
for an overview of valid values.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>initdb</command> will
|
2017-03-09 14:27:16 +01:00
|
|
|
prepopulate <filename>pg_hba.conf</filename> entries using the
|
|
|
|
specified authentication method for non-replication as well as
|
|
|
|
replication connections.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
Do not use <literal>trust</literal> unless you trust all local users on your
|
2019-07-22 19:28:25 +02:00
|
|
|
system. <literal>trust</literal> is the default for ease of installation.
|
2012-02-01 20:18:55 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-auth-host">
|
2012-02-01 20:18:55 +01:00
|
|
|
<term><option>--auth-host=<replaceable class="parameter">authmethod</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This option specifies the authentication method for local users via
|
2017-10-09 03:44:17 +02:00
|
|
|
TCP/IP connections used in <filename>pg_hba.conf</filename>
|
2012-02-01 20:18:55 +01:00
|
|
|
(<literal>host</literal> lines).
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-auth-local">
|
2012-02-01 20:18:55 +01:00
|
|
|
<term><option>--auth-local=<replaceable class="parameter">authmethod</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This option specifies the authentication method for local users via
|
2017-10-09 03:44:17 +02:00
|
|
|
Unix-domain socket connections used in <filename>pg_hba.conf</filename>
|
2012-02-01 20:18:55 +01:00
|
|
|
(<literal>local</literal> lines).
|
2004-08-01 08:19:26 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-pgdata">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
|
2002-10-12 01:03:48 +02:00
|
|
|
<term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-03-24 15:32:51 +01:00
|
|
|
This option specifies the directory where the database cluster
|
2000-12-26 00:15:27 +01:00
|
|
|
should be stored. This is the only information required by
|
2001-09-08 17:24:00 +02:00
|
|
|
<command>initdb</command>, but you can avoid writing it by
|
2000-12-26 00:15:27 +01:00
|
|
|
setting the <envar>PGDATA</envar> environment variable, which
|
|
|
|
can be convenient since the database server
|
2022-11-18 11:59:26 +01:00
|
|
|
(<command>postgres</command>) can find the data
|
2000-12-26 00:15:27 +01:00
|
|
|
directory later by the same variable.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
1998-10-05 04:54:45 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-encoding">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
|
2002-10-12 01:03:48 +02:00
|
|
|
<term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
|
1999-12-17 02:05:31 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2023-03-10 19:51:24 +01:00
|
|
|
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 character sets supported by the
|
|
|
|
<productname>PostgreSQL</productname> server are described in <xref
|
|
|
|
linkend="multibyte-charset-supported"/>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
By default, the template database encoding is derived from the
|
|
|
|
locale. If <xref linkend="app-initdb-option-no-locale"/> is specified
|
|
|
|
(or equivalently, if the locale is <literal>C</literal> or
|
|
|
|
<literal>POSIX</literal>), then the default is <literal>UTF8</literal>
|
|
|
|
for the ICU provider and <literal>SQL_ASCII</literal> for the
|
|
|
|
<literal>libc</literal> provider.
|
1999-12-17 02:05:31 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2018-04-07 23:45:39 +02:00
|
|
|
<varlistentry id="app-initdb-allow-group-access" xreflabel="group access">
|
|
|
|
<term><option>-g</option></term>
|
|
|
|
<term><option>--allow-group-access</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Allows users in the same group as the cluster owner to read all cluster
|
2019-02-04 01:57:20 +01:00
|
|
|
files created by <command>initdb</command>. This option is ignored
|
|
|
|
on <productname>Windows</productname> as it does not support
|
|
|
|
<acronym>POSIX</acronym>-style group permissions.
|
2018-04-07 23:45:39 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-icu-locale">
|
2022-03-17 11:11:21 +01:00
|
|
|
<term><option>--icu-locale=<replaceable>locale</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2023-03-09 19:52:41 +01:00
|
|
|
Specifies the ICU locale when the ICU provider is used. Locale support
|
|
|
|
is described in <xref linkend="locale"/>.
|
|
|
|
</para>
|
|
|
|
<para>
|
|
|
|
If this option is not specified, the locale is inherited from the
|
|
|
|
environment in which <command>initdb</command> runs. The environment's
|
|
|
|
locale is matched to a similar ICU locale name, if possible.
|
2022-03-17 11:11:21 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-03-08 16:35:42 +01:00
|
|
|
<varlistentry id="app-initdb-icu-rules">
|
|
|
|
<term><option>--icu-rules=<replaceable>rules</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Specifies additional collation rules to customize the behavior of the
|
|
|
|
default collation. This is supported for ICU only.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2013-03-22 14:54:07 +01:00
|
|
|
<varlistentry id="app-initdb-data-checksums" xreflabel="data checksums">
|
|
|
|
<term><option>-k</option></term>
|
|
|
|
<term><option>--data-checksums</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Use checksums on data pages to help detect corruption by the
|
|
|
|
I/O system that would otherwise be silent. Enabling checksums
|
2019-07-18 03:05:59 +02:00
|
|
|
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
|
2020-05-29 10:14:33 +02:00
|
|
|
<link linkend="monitoring-pg-stat-database-view">
|
|
|
|
<structname>pg_stat_database</structname></link> view.
|
2021-01-17 15:31:23 +01:00
|
|
|
See <xref linkend="checksums" /> for details.
|
2013-03-22 14:54:07 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-locale">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>--locale=<replaceable>locale</replaceable></option></term>
|
2002-04-03 07:39:33 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Sets the default locale for the database cluster. If this
|
|
|
|
option is not specified, the locale is inherited from the
|
2004-03-23 03:47:35 +01:00
|
|
|
environment that <command>initdb</command> runs in. Locale
|
2017-11-23 15:39:47 +01:00
|
|
|
support is described in <xref linkend="locale"/>.
|
2002-04-03 07:39:33 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-lc-collate">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>--lc-collate=<replaceable>locale</replaceable></option></term>
|
|
|
|
<term><option>--lc-ctype=<replaceable>locale</replaceable></option></term>
|
|
|
|
<term><option>--lc-messages=<replaceable>locale</replaceable></option></term>
|
|
|
|
<term><option>--lc-monetary=<replaceable>locale</replaceable></option></term>
|
|
|
|
<term><option>--lc-numeric=<replaceable>locale</replaceable></option></term>
|
|
|
|
<term><option>--lc-time=<replaceable>locale</replaceable></option></term>
|
2002-04-03 07:39:33 +02:00
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Like <option>--locale</option>, but only sets the locale in
|
|
|
|
the specified category.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2002-10-12 01:03:48 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-no-locale">
|
2012-03-11 00:23:20 +01:00
|
|
|
<term><option>--no-locale</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2012-03-12 15:13:42 +01:00
|
|
|
Equivalent to <option>--locale=C</option>.
|
2012-03-11 00:23:20 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-locale-provider">
|
2022-03-17 11:11:21 +01:00
|
|
|
<term><option>--locale-provider={<literal>libc</literal>|<literal>icu</literal>}</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2023-03-09 19:52:41 +01:00
|
|
|
This option sets the locale provider for databases created in the new
|
|
|
|
cluster. It can be overridden in the <command>CREATE
|
2022-03-17 11:11:21 +01:00
|
|
|
DATABASE</command> command when new databases are subsequently
|
2023-03-09 19:52:41 +01:00
|
|
|
created. The default is <literal>icu</literal> if the server was
|
|
|
|
built with ICU support; otherwise the default is
|
|
|
|
<literal>libc</literal> (see <xref linkend="locale-providers"/>).
|
2022-03-17 11:11:21 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-no-sync">
|
2012-07-13 23:16:58 +02:00
|
|
|
<term><option>-N</option></term>
|
2016-10-19 18:00:00 +02:00
|
|
|
<term><option>--no-sync</option></term>
|
2012-07-13 23:16:58 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
By default, <command>initdb</command> will wait for all files to be
|
|
|
|
written safely to disk. This option causes <command>initdb</command>
|
|
|
|
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.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-no-instructions">
|
2021-01-17 14:28:17 +01:00
|
|
|
<term><option>--no-instructions</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
By default, <command>initdb</command> will write instructions for how
|
|
|
|
to start the cluster at the end of its output. This option causes
|
|
|
|
those instructions to be left out. This is primarily intended for use
|
2021-09-29 04:56:13 +02:00
|
|
|
by tools that wrap <command>initdb</command> in platform-specific
|
2021-01-17 14:28:17 +01:00
|
|
|
behavior, where those instructions are likely to be incorrect.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-pwfile">
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><option>--pwfile=<replaceable>filename</replaceable></option></term>
|
2007-01-06 20:40:00 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2022-11-18 11:59:26 +01:00
|
|
|
Makes <command>initdb</command> read the bootstrap superuser's password
|
2011-03-09 15:18:44 +01:00
|
|
|
from a file. The first line of the file is taken as the password.
|
2007-01-06 20:40:00 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2012-03-11 00:23:20 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-sync-only">
|
2012-12-04 04:47:59 +01:00
|
|
|
<term><option>-S</option></term>
|
|
|
|
<term><option>--sync-only</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Safely write all database files to disk and exit. This does not
|
2017-10-09 03:44:17 +02:00
|
|
|
perform any of the normal <application>initdb</application> operations.
|
2021-08-16 13:38:01 +02:00
|
|
|
Generally, this option is useful for ensuring reliable recovery after
|
|
|
|
changing <xref linkend="guc-fsync"/> from <literal>off</literal> to
|
|
|
|
<literal>on</literal>.
|
2012-12-04 04:47:59 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-text-search-config">
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><option>-T <replaceable>config</replaceable></option></term>
|
|
|
|
<term><option>--text-search-config=<replaceable>config</replaceable></option></term>
|
2012-03-11 00:23:20 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2012-03-12 15:13:42 +01:00
|
|
|
Sets the default text search configuration.
|
2017-11-23 15:39:47 +01:00
|
|
|
See <xref linkend="guc-default-text-search-config"/> for further information.
|
2012-03-11 00:23:20 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-username">
|
2002-10-12 01:03:48 +02:00
|
|
|
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
|
|
|
|
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2022-11-18 11:59:26 +01:00
|
|
|
Selects the user name of the
|
2022-11-18 12:52:44 +01:00
|
|
|
<glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>.
|
2022-11-18 11:59:26 +01:00
|
|
|
This defaults to the name of the
|
|
|
|
<glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>.
|
2002-10-12 01:03:48 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2010-11-23 21:27:50 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-pwprompt">
|
2002-10-12 01:03:48 +02:00
|
|
|
<term><option>-W</option></term>
|
|
|
|
<term><option>--pwprompt</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Makes <command>initdb</command> prompt for a password
|
2022-11-18 11:59:26 +01:00
|
|
|
to give the bootstrap superuser. If you don't plan on using password
|
2002-10-12 01:03:48 +02:00
|
|
|
authentication, this is not important. Otherwise you won't be
|
|
|
|
able to use password authentication until you have a password
|
|
|
|
set up.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2004-06-24 21:26:59 +02:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-waldir">
|
2011-03-09 15:18:44 +01:00
|
|
|
<term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
|
2017-02-09 22:42:51 +01:00
|
|
|
<term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term>
|
2004-06-24 21:26:59 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2017-05-12 17:49:56 +02:00
|
|
|
This option specifies the directory where the write-ahead log
|
2011-03-09 15:18:44 +01:00
|
|
|
should be stored.
|
2004-06-24 21:26:59 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2011-03-09 15:18:44 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-wal-segsize">
|
2018-06-08 05:36:04 +02:00
|
|
|
<term><option>--wal-segsize=<replaceable>size</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Set the <firstterm>WAL segment size</firstterm>, in megabytes. This
|
|
|
|
is the size of each individual file in the WAL log. The default size
|
|
|
|
is 16 megabytes. The value must be a power of 2 between 1 and 1024
|
|
|
|
(megabytes). This option can only be set during initialization, and
|
|
|
|
cannot be changed later.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
It may be useful to adjust this size to control the granularity of
|
|
|
|
WAL log shipping or archiving. Also, in databases with a high volume
|
|
|
|
of WAL, the sheer number of WAL files per directory can become a
|
|
|
|
performance and management problem. Increasing the WAL file size
|
|
|
|
will reduce the number of WAL files.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2002-10-12 01:03:48 +02:00
|
|
|
</variablelist>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
2012-05-20 00:15:55 +02:00
|
|
|
Other, less commonly used, options are also available:
|
1999-07-06 19:16:42 +02:00
|
|
|
|
|
|
|
<variablelist>
|
2023-03-22 18:48:44 +01:00
|
|
|
<varlistentry id="app-initdb-option-set">
|
|
|
|
<term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
|
|
|
|
<term><option>--set <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Forcibly set the server parameter <replaceable>name</replaceable>
|
|
|
|
to <replaceable>value</replaceable> during <command>initdb</command>,
|
|
|
|
and also install that setting in the
|
|
|
|
generated <filename>postgresql.conf</filename> file,
|
|
|
|
so that it will apply during future server runs.
|
|
|
|
This option can be given more than once to set several parameters.
|
|
|
|
It is primarily useful when the environment is such that the server
|
|
|
|
will not start at all using the default parameters.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-debug">
|
2002-10-12 01:03:48 +02:00
|
|
|
<term><option>-d</option></term>
|
|
|
|
<term><option>--debug</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2007-02-22 00:21:12 +01:00
|
|
|
Print debugging output from the bootstrap backend and a few other
|
2002-10-12 01:03:48 +02:00
|
|
|
messages of lesser interest for the general public.
|
2007-02-22 00:21:12 +01:00
|
|
|
The bootstrap backend is the program <command>initdb</command>
|
|
|
|
uses to create the catalog tables. This option generates a tremendous
|
|
|
|
amount of extremely boring output.
|
2002-10-12 01:03:48 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-discard-caches">
|
2021-07-13 21:01:01 +02:00
|
|
|
<term><option>--discard-caches</option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Run the bootstrap backend with the
|
|
|
|
<literal>debug_discard_caches=1</literal> option.
|
|
|
|
This takes a very long time and is only of use for deep debugging.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-l">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>-L <replaceable class="parameter">directory</replaceable></option></term>
|
1999-12-17 02:05:31 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2001-09-08 17:24:00 +02:00
|
|
|
Specifies where <command>initdb</command> should find
|
2003-03-24 15:32:51 +01:00
|
|
|
its input files to initialize the database cluster. This is
|
2000-12-26 00:15:27 +01:00
|
|
|
normally not necessary. You will be told if you need to
|
|
|
|
specify their location explicitly.
|
1999-12-17 02:05:31 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-no-clean">
|
2002-09-21 20:32:54 +02:00
|
|
|
<term><option>-n</option></term>
|
2016-10-19 18:00:00 +02:00
|
|
|
<term><option>--no-clean</option></term>
|
1999-07-06 19:16:42 +02:00
|
|
|
<listitem>
|
|
|
|
<para>
|
2007-02-22 00:21:12 +01:00
|
|
|
By default, when <command>initdb</command>
|
|
|
|
determines that an error prevented it from completely creating the database
|
|
|
|
cluster, it removes any files it might have created before discovering
|
|
|
|
that it cannot finish the job. This option inhibits tidying-up and is
|
|
|
|
thus useful for debugging.
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2012-06-18 01:44:00 +02:00
|
|
|
</variablelist>
|
|
|
|
</para>
|
2010-02-19 15:36:45 +01:00
|
|
|
|
2012-06-18 01:44:00 +02:00
|
|
|
<para>
|
|
|
|
Other options:
|
|
|
|
|
|
|
|
<variablelist>
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-version">
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><option>-V</option></term>
|
|
|
|
<term><option>--version</option></term>
|
2010-02-19 15:36:45 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Print the <application>initdb</application> version and exit.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-option-help">
|
2017-10-09 03:44:17 +02:00
|
|
|
<term><option>-?</option></term>
|
|
|
|
<term><option>--help</option></term>
|
2010-02-19 15:36:45 +01:00
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
Show help about <application>initdb</application> command line
|
|
|
|
arguments, and exit.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</variablelist>
|
|
|
|
</para>
|
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
</refsect1>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2000-11-12 00:01:45 +01:00
|
|
|
<refsect1>
|
2001-09-08 17:24:00 +02:00
|
|
|
<title>Environment</title>
|
|
|
|
|
|
|
|
<variablelist>
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-environment-pgdata">
|
2001-09-08 17:24:00 +02:00
|
|
|
<term><envar>PGDATA</envar></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2003-03-24 15:32:51 +01:00
|
|
|
Specifies the directory where the database cluster is to be
|
Update reference documentation on may/can/might:
Standard English uses "may", "can", and "might" in different ways:
may - permission, "You may borrow my rake."
can - ability, "I can lift that log."
might - possibility, "It might rain today."
Unfortunately, in conversational English, their use is often mixed, as
in, "You may use this variable to do X", when in fact, "can" is a better
choice. Similarly, "It may crash" is better stated, "It might crash".
2007-02-01 00:26:05 +01:00
|
|
|
stored; can be overridden using the <option>-D</option> option.
|
2001-09-08 17:24:00 +02:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2014-11-16 15:48:30 +01:00
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-environment-pg-color">
|
Unified logging system for command-line programs
This unifies the various ad hoc logging (message printing, error
printing) systems used throughout the command-line programs.
Features:
- Program name is automatically prefixed.
- Message string does not end with newline. This removes a common
source of inconsistencies and omissions.
- Additionally, a final newline is automatically stripped, simplifying
use of PQerrorMessage() etc., another common source of mistakes.
- I converted error message strings to use %m where possible.
- As a result of the above several points, more translatable message
strings can be shared between different components and between
frontends and backend, without gratuitous punctuation or whitespace
differences.
- There is support for setting a "log level". This is not meant to be
user-facing, but can be used internally to implement debug or
verbose modes.
- Lazy argument evaluation, so no significant overhead if logging at
some level is disabled.
- Some color in the messages, similar to gcc and clang. Set
PG_COLOR=auto to try it out. Some colors are predefined, but can be
customized by setting PG_COLORS.
- Common files (common/, fe_utils/, etc.) can handle logging much more
simply by just using one API without worrying too much about the
context of the calling program, requiring callbacks, or having to
pass "progname" around everywhere.
- Some programs called setvbuf() to make sure that stderr is
unbuffered, even on Windows. But not all programs did that. This
is now done centrally.
Soft goals:
- Reduces vertical space use and visual complexity of error reporting
in the source code.
- Encourages more deliberate classification of messages. For example,
in some cases it wasn't clear without analyzing the surrounding code
whether a message was meant as an error or just an info.
- Concepts and terms are vaguely aligned with popular logging
frameworks such as log4j and Python logging.
This is all just about printing stuff out. Nothing affects program
flow (e.g., fatal exits). The uses are just too varied to do that.
Some existing code had wrappers that do some kind of print-and-exit,
and I adapted those.
I tried to keep the output mostly the same, but there is a lot of
historical baggage to unwind and special cases to consider, and I
might not always have succeeded. One significant change is that
pg_rewind used to write all error messages to stdout. That is now
changed to stderr.
Reviewed-by: Donald Dong <xdong@csumb.edu>
Reviewed-by: Arthur Zakirov <a.zakirov@postgrespro.ru>
Discussion: https://www.postgresql.org/message-id/flat/6a609b43-4f57-7348-6480-bd022f924310@2ndquadrant.com
2019-04-01 14:24:37 +02:00
|
|
|
<term><envar>PG_COLOR</envar></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2020-03-09 02:53:22 +01:00
|
|
|
Specifies whether to use color in diagnostic messages. Possible values
|
|
|
|
are <literal>always</literal>, <literal>auto</literal> and
|
Unified logging system for command-line programs
This unifies the various ad hoc logging (message printing, error
printing) systems used throughout the command-line programs.
Features:
- Program name is automatically prefixed.
- Message string does not end with newline. This removes a common
source of inconsistencies and omissions.
- Additionally, a final newline is automatically stripped, simplifying
use of PQerrorMessage() etc., another common source of mistakes.
- I converted error message strings to use %m where possible.
- As a result of the above several points, more translatable message
strings can be shared between different components and between
frontends and backend, without gratuitous punctuation or whitespace
differences.
- There is support for setting a "log level". This is not meant to be
user-facing, but can be used internally to implement debug or
verbose modes.
- Lazy argument evaluation, so no significant overhead if logging at
some level is disabled.
- Some color in the messages, similar to gcc and clang. Set
PG_COLOR=auto to try it out. Some colors are predefined, but can be
customized by setting PG_COLORS.
- Common files (common/, fe_utils/, etc.) can handle logging much more
simply by just using one API without worrying too much about the
context of the calling program, requiring callbacks, or having to
pass "progname" around everywhere.
- Some programs called setvbuf() to make sure that stderr is
unbuffered, even on Windows. But not all programs did that. This
is now done centrally.
Soft goals:
- Reduces vertical space use and visual complexity of error reporting
in the source code.
- Encourages more deliberate classification of messages. For example,
in some cases it wasn't clear without analyzing the surrounding code
whether a message was meant as an error or just an info.
- Concepts and terms are vaguely aligned with popular logging
frameworks such as log4j and Python logging.
This is all just about printing stuff out. Nothing affects program
flow (e.g., fatal exits). The uses are just too varied to do that.
Some existing code had wrappers that do some kind of print-and-exit,
and I adapted those.
I tried to keep the output mostly the same, but there is a lot of
historical baggage to unwind and special cases to consider, and I
might not always have succeeded. One significant change is that
pg_rewind used to write all error messages to stdout. That is now
changed to stderr.
Reviewed-by: Donald Dong <xdong@csumb.edu>
Reviewed-by: Arthur Zakirov <a.zakirov@postgrespro.ru>
Discussion: https://www.postgresql.org/message-id/flat/6a609b43-4f57-7348-6480-bd022f924310@2ndquadrant.com
2019-04-01 14:24:37 +02:00
|
|
|
<literal>never</literal>.
|
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
|
2023-01-09 21:08:24 +01:00
|
|
|
<varlistentry id="app-initdb-environment-tz">
|
2014-11-16 15:48:30 +01:00
|
|
|
<term><envar>TZ</envar></term>
|
|
|
|
|
|
|
|
<listitem>
|
|
|
|
<para>
|
2014-12-15 02:02:04 +01:00
|
|
|
Specifies the default time zone of the created database cluster. The
|
|
|
|
value should be a full time zone name
|
2017-11-23 15:39:47 +01:00
|
|
|
(see <xref linkend="datatype-timezones"/>).
|
2014-11-16 15:48:30 +01:00
|
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
</varlistentry>
|
2001-09-08 17:24:00 +02:00
|
|
|
</variablelist>
|
2007-02-20 19:10:59 +01:00
|
|
|
|
|
|
|
<para>
|
2017-10-09 03:44:17 +02:00
|
|
|
This utility, like most other <productname>PostgreSQL</productname> utilities,
|
|
|
|
also uses the environment variables supported by <application>libpq</application>
|
2017-11-23 15:39:47 +01:00
|
|
|
(see <xref linkend="libpq-envars"/>).
|
2007-02-20 19:10:59 +01:00
|
|
|
</para>
|
|
|
|
|
2001-09-08 17:24:00 +02:00
|
|
|
</refsect1>
|
|
|
|
|
2009-12-10 07:32:28 +01:00
|
|
|
<refsect1>
|
|
|
|
<title>Notes</title>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
<command>initdb</command> can also be invoked via
|
|
|
|
<command>pg_ctl initdb</command>.
|
|
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
|
2001-09-08 17:24:00 +02:00
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-09-08 17:24:00 +02:00
|
|
|
<simplelist type="inline">
|
2017-11-23 15:39:47 +01:00
|
|
|
<member><xref linkend="app-pg-ctl"/></member>
|
|
|
|
<member><xref linkend="app-postgres"/></member>
|
2022-05-14 09:57:03 +02:00
|
|
|
<member><xref linkend="auth-pg-hba-conf"/></member>
|
2001-09-08 17:24:00 +02:00
|
|
|
</simplelist>
|
1999-07-06 19:16:42 +02:00
|
|
|
</refsect1>
|
2000-11-12 00:01:45 +01:00
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
</refentry>
|