<!--
doc/src/sgml/ref/initdb.sgml
PostgreSQL documentation
-->

<refentry id="app-initdb">
 <indexterm zone="app-initdb">
  <primary>initdb</primary>
 </indexterm>

 <refmeta>
  <refentrytitle><application>initdb</application></refentrytitle>
  <manvolnum>1</manvolnum>
  <refmiscinfo>Application</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>initdb</refname>
  <refpurpose>create a new <productname>PostgreSQL</productname> database cluster</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
  <cmdsynopsis>
   <command>initdb</command>
   <arg rep="repeat"><replaceable>option</replaceable></arg>
   <group choice="plain">
    <group choice="opt">
     <arg choice="plain"><option>--pgdata</option></arg>
     <arg choice="plain"><option>-D</option></arg>
    </group>
    <replaceable> directory</replaceable>
   </group>
  </cmdsynopsis>
 </refsynopsisdiv>

 <refsect1 id="r1-app-initdb-1">
  <title>Description</title>
  <para>
   <command>initdb</command> creates a new
   <productname>PostgreSQL</productname> <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
  </para>

  <para>
   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
   tables (tables that belong to the whole cluster rather than to any
   particular database), and creating the <literal>postgres</literal>,
   <literal>template1</literal>, and <literal>template0</literal> databases.
   The <literal>postgres</literal> database is a default database meant
   for use by users, utilities and third party applications.
   <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.
  </para>

  <para>
   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>.
  </para>

  <para>
   <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.
   Since the server cannot be run as root, you must not run
   <command>initdb</command> as root either.  (It will in fact refuse
   to do so.)
  </para>

  <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>

  <para>
   <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.
  </para>

  <para>
   By default, <command>initdb</command> uses the locale provider
   <literal>libc</literal> (see <xref linkend="locale-providers"/>). The
   <literal>libc</literal> locale provider takes the locale settings from the
   environment, and determines the encoding from the locale settings.
  </para>

  <para>
   To choose a different locale