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
|
|
|
|
|
all other databases. By default, <command>initdb</command> uses the
|
|
|
|
|
locale provider <literal>libc</literal>, 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>
|
|
|
|
|
|
|
|
|
|
<para>
|
2022-03-17 11:11:21 +01:00
|
|
|
Alternatively, the ICU library can be used to provide locale services.
|
|
|
|
|
(Again, this only sets the default for subsequently created databases.) To
|
|
|
|
|
select this option, specify <literal>--locale-provider=icu</literal>.
|
2022-04-13 23:16:05 +02:00
|
|
|
To choose the specific ICU locale ID to apply, use the option
|
2022-03-17 11:11:21 +01:00
|
|
|
<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>
|
|
|
|
|
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>
|
2004-08-01 08:19:26 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
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
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
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>
|
2021-11-02 17:54:35 +01:00
|
|
|
Selects the encoding of the template databases. This will also
|
2004-03-23 03:47:35 +01:00
|
|
|
be the default encoding of any database you create later,
|
2022-09-16 09:37:54 +02:00
|
|
|
unless you override it then. The default is derived from the locale,
|
|
|
|
|
if the libc locale provider is used, or <literal>UTF8</literal> if the
|
|
|
|
|
ICU locale provider is used. The character sets supported by
|
2004-03-23 03:47:35 +01:00
|
|
|
the <productname>PostgreSQL</productname> server are described
|
2017-11-23 15:39:47 +01:00
|
|
|
in <xref linkend="multibyte-charset-supported"/>.
|
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>
|
|
|
|
|
|
2022-03-17 11:11:21 +01:00
|
|
|
<varlistentry>
|
|
|
|
|
<term><option>--icu-locale=<replaceable>locale</replaceable></option></term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
Specifies the ICU locale ID, if the ICU locale provider is used.
|
|
|
|
|
</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>
|
|
|
|
|
|
2002-04-03 07:39:33 +02:00
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
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
|
|
|
|
2012-03-11 00:23:20 +01:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
2022-03-17 11:11:21 +01:00
|
|
|
<varlistentry>
|
|
|
|
|
<term><option>--locale-provider={<literal>libc</literal>|<literal>icu</literal>}</option></term>
|
|
|
|
|
<listitem>
|
|
|
|
|
<para>
|
|
|
|
|
This option sets the locale provider for databases created in the
|
|
|
|
|
new cluster. It can be overridden in the <command>CREATE
|
|
|
|
|
DATABASE</command> command when new databases are subsequently
|
|
|
|
|
created. The default is <literal>libc</literal>.
|
|
|
|
|
</para>
|
|
|
|
|
</listitem>
|
|
|
|
|
</varlistentry>
|
|
|
|
|
|
2012-07-13 23:16:58 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
2021-01-17 14:28:17 +01:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
2007-01-06 20:40:00 +01:00
|
|
|
<varlistentry>
|
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
|
|
|
|
|
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
|
2002-10-12 01:03:48 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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
|
|
|
|
|
<glossterm linkend="glossary-bootstrap-superuser">boostrap superuser</glossterm>.
|
|
|
|
|
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
|
|
|
|
2002-10-12 01:03:48 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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
|
|
|
|
Make WAL segment size configurable at initdb time.
For performance reasons a larger segment size than the default 16MB
can be useful. A larger segment size has two main benefits: Firstly,
in setups using archiving, it makes it easier to write scripts that
can keep up with higher amounts of WAL, secondly, the WAL has to be
written and synced to disk less frequently.
But at the same time large segment size are disadvantageous for
smaller databases. So far the segment size had to be configured at
compile time, often making it unrealistic to choose one fitting to a
particularly load. Therefore change it to a initdb time setting.
This includes a breaking changes to the xlogreader.h API, which now
requires the current segment size to be configured. For that and
similar reasons a number of binaries had to be taught how to recognize
the current segment size.
Author: Beena Emerson, editorialized by Andres Freund
Reviewed-By: Andres Freund, David Steele, Kuntal Ghosh, Michael
Paquier, Peter Eisentraut, Robert Hass, Tushar Ahuja
Discussion: https://postgr.es/m/CAOG9ApEAcQ--1ieKbhFzXSQPw_YLmepaa4hNdnY5+ZULpt81Mw@mail.gmail.com
2017-09-20 07:03:48 +02:00
|
|
|
<varlistentry>
|
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
|
|
|
|
2018-06-08 05:36:04 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
2002-10-12 01:03:48 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
2021-07-13 21:01:01 +02:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<varlistentry>
|
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>
|
2010-02-19 15:36:45 +01:00
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
|
|
|
|
|
<varlistentry>
|
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>
|
|
|
|
|
<varlistentry>
|
|
|
|
|
<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
|
|
|
|
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
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
|
|
|
|
|
2014-11-16 15:48:30 +01:00
|
|
|
<varlistentry>
|
|
|
|
|
<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>
|
