doc/src/sgml/ref/initdb.sgml

   1 <!--
   2 doc/src/sgml/ref/initdb.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="app-initdb">
   7  <indexterm zone="app-initdb">
   8   <primary>initdb</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle><application>initdb</application></refentrytitle>
  13   <manvolnum>1</manvolnum>
  14   <refmiscinfo>Application</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>initdb</refname>
  19   <refpurpose>create a new <productname>PostgreSQL</productname> database cluster</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23   <cmdsynopsis>
  24    <command>initdb</command>
  25    <arg rep="repeat"><replaceable>option</replaceable></arg>
  26    <group choice="plain">
  27     <group choice="opt">
  28      <arg choice="plain"><option>--pgdata</option></arg>
  29      <arg choice="plain"><option>-D</option></arg>
  30     </group>
  31     <replaceable> directory</replaceable>
  32    </group>
  33   </cmdsynopsis>
  34  </refsynopsisdiv>
  35
  36  <refsect1 id="r1-app-initdb-1">
  37   <title>Description</title>
  38   <para>
  39    <command>initdb</command> creates a new
  40    <productname>PostgreSQL</productname> <glossterm linkend="glossary-db-cluster">database cluster</glossterm>.
  41   </para>
  42
  43   <para>
  44    Creating a database cluster consists of creating the
  45    <glossterm linkend="glossary-data-directory">directories</glossterm> in
  46    which the cluster data will live, generating the shared catalog
  47    tables (tables that belong to the whole cluster rather than to any
  48    particular database), and creating the <literal>postgres</literal>,
  49    <literal>template1</literal>, and <literal>template0</literal> databases.
  50    The <literal>postgres</literal> database is a default database meant
  51    for use by users, utilities and third party applications.
  52    <literal>template1</literal> and <literal>template0</literal> are
  53    meant as source databases to be copied by later <command>CREATE
  54    DATABASE</command> commands.  <literal>template0</literal> should never
  55    be modified, but you can add objects to <literal>template1</literal>,
  56    which by default will be copied into databases created later.  See
  57    <xref linkend="manage-ag-templatedbs"/> for more details.
  58   </para>
  59
  60   <para>
  61    Although <command>initdb</command> will attempt to create the
  62    specified data directory, it might not have permission if the parent
  63    directory of the desired data directory is root-owned. To initialize
  64    in such a setup, create an empty data directory as root, then use
  65    <command>chown</command> to assign ownership of that directory to the
  66    database user account, then <command>su</command> to become the
  67    database user to run <command>initdb</command>.
  68   </para>
  69
  70   <para>
  71    <command>initdb</command> must be run as the user that will own the
  72    server process, because the server needs to have access to the
  73    files and directories that <command>initdb</command> creates.
  74    Since the server cannot be run as root, you must not run
  75    <command>initdb</command> as root either.  (It will in fact refuse
  76    to do so.)
  77   </para>
  78
  79   <para>
  80     For security reasons the new cluster created by <command>initdb</command>
  81     will only be accessible by the cluster owner by default.  The
  82     <option>--allow-group-access</option> option allows any user in the same
  83     group as the cluster owner to read files in the cluster.  This is useful
  84     for performing backups as a non-privileged user.
  85   </para>
  86
  87   <para>
  88    <command>initdb</command> initializes the database cluster's default locale
  89    and character set encoding. These can also be set separately for each
  90    database when it is created. <command>initdb</command> determines those
  91    settings for the template databases, which will serve as the default for
  92    all other databases.
  93   </para>
  94
  95   <para>
  96    By default, <command>initdb</command> uses the locale provider
  97    <literal>libc</literal> (see <xref linkend="locale-providers"/>). The
  98    <literal>libc</literal> locale provider takes the locale settings from the
  99    environment, and determines the encoding from the locale settings.
 100   </para>
 101
 102   <para>
 103    To choose a different locale for the cluster, use the option
 104    <option>--locale</option>.  There are also individual options
 105    <option>--lc-*</option> and <option>--icu-locale</option> (see below) to
 106    set values for the individual locale categories.  Note that inconsistent
 107    settings for different locale categories can give nonsensical results, so
 108    this should be used with care.
 109   </para>
 110
 111   <para>
 112    Alternatively, <command>initdb</command> can use the ICU library to provide
 113    locale services by specifying <literal>--locale-provider=icu</literal>. The
 114    server must be built with ICU support. To choose the specific ICU locale ID
 115    to apply, use the option <option>--icu-locale</option>.  Note that for
 116    implementation reasons and to support legacy code,
 117    <command>initdb</command> will still select and initialize libc locale
 118    settings when the ICU locale provider is used.
 119   </para>
 120
 121   <para>
 122    When <command>initdb</command> runs, it will print out the locale settings
 123    it has chosen.  If you have complex requirements or specified multiple
 124    options, it is advisable to check that the result matches what was
 125    intended.
 126   </para>
 127
 128   <para>
 129    More details about locale settings can be found in <xref
 130    linkend="locale"/>.
 131   </para>
 132
 133   <para>
 134    To alter the default encoding, use the <option>--encoding</option>.
 135    More details can be found in <xref linkend="multibyte"/>.
 136   </para>
 137
 138  </refsect1>
 139
 140  <refsect1>
 141   <title>Options</title>
 142
 143    <para>
 144     <variablelist>
 145      <varlistentry id="app-initdb-option-auth">
 146       <term><option>-A <replaceable class="parameter">authmethod</replaceable></option></term>
 147       <term><option>--auth=<replaceable class="parameter">authmethod</replaceable></option></term>
 148       <listitem>
 149        <para>
 150         This option specifies the default authentication method for local
 151         users used in <filename>pg_hba.conf</filename> (<literal>host</literal>
 152         and <literal>local</literal> lines).  See <xref linkend="auth-pg-hba-conf"/>
 153         for an overview of valid values.
 154        </para>
 155
 156        <para>
 157         <command>initdb</command> will
 158         prepopulate <filename>pg_hba.conf</filename> entries using the
 159         specified authentication method for non-replication as well as
 160         replication connections.
 161        </para>
 162
 163        <para>
 164         Do not use <literal>trust</literal> unless you trust all local users on your
 165         system.  <literal>trust</literal> is the default for ease of installation.
 166        </para>
 167       </listitem>
 168      </varlistentry>
 169
 170      <varlistentry id="app-initdb-option-auth-host">
 171       <term><option>--auth-host=<replaceable class="parameter">authmethod</replaceable></option></term>
 172       <listitem>
 173        <para>
 174         This option specifies the authentication method for local users via
 175         TCP/IP connections used in <filename>pg_hba.conf</filename>
 176         (<literal>host</literal> lines).
 177        </para>
 178       </listitem>
 179      </varlistentry>
 180
 181      <varlistentry id="app-initdb-option-auth-local">
 182       <term><option>--auth-local=<replaceable class="parameter">authmethod</replaceable></option></term>
 183       <listitem>
 184        <para>
 185         This option specifies the authentication method for local users via
 186         Unix-domain socket connections used in <filename>pg_hba.conf</filename>
 187         (<literal>local</literal> lines).
 188        </para>
 189       </listitem>
 190      </varlistentry>
 191
 192      <varlistentry id="app-initdb-option-pgdata">
 193       <term><option>-D <replaceable class="parameter">directory</replaceable></option></term>
 194       <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term>
 195       <listitem>
 196        <para>
 197         This option specifies the directory where the database cluster
 198         should be stored. This is the only information required by
 199         <command>initdb</command>, but you can avoid writing it by
 200         setting the <envar>PGDATA</envar> environment variable, which
 201         can be convenient since the database server
 202         (<command>postgres</command>) can find the data
 203         directory later by the same variable.
 204        </para>
 205       </listitem>
 206      </varlistentry>
 207
 208      <varlistentry id="app-initdb-option-encoding">
 209       <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term>
 210       <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term>
 211       <listitem>
 212        <para>
 213         Selects the encoding of the template databases. This will also be the
 214         default encoding of any database you create later, unless you override
 215         it then. The character sets supported by the
 216         <productname>PostgreSQL</productname> server are described in <xref
 217         linkend="multibyte-charset-supported"/>.
 218        </para>
 219        <para>
 220         By default, the template database encoding is derived from the
 221         locale. If <xref linkend="app-initdb-option-no-locale"/> is specified
 222         (or equivalently, if the locale is <literal>C</literal> or
 223         <literal>POSIX</literal>), then the default is <literal>UTF8</literal>
 224         for the ICU provider and <literal>SQL_ASCII</literal> for the
 225         <literal>libc</literal> provider.
 226        </para>
 227       </listitem>
 228      </varlistentry>
 229
 230      <varlistentry id="app-initdb-allow-group-access" xreflabel="group access">
 231       <term><option>-g</option></term>
 232       <term><option>--allow-group-access</option></term>
 233       <listitem>
 234        <para>
 235         Allows users in the same group as the cluster owner to read all cluster
 236         files created by <command>initdb</command>.  This option is ignored
 237         on <productname>Windows</productname> as it does not support
 238         <acronym>POSIX</acronym>-style group permissions.
 239        </para>
 240       </listitem>
 241      </varlistentry>
 242
 243      <varlistentry id="app-initdb-icu-locale">
 244       <term><option>--icu-locale=<replaceable>locale</replaceable></option></term>
 245       <listitem>
 246        <para>
 247         Specifies the ICU locale when the ICU provider is used. Locale support
 248         is described in <xref linkend="locale"/>.
 249        </para>
 250       </listitem>
 251      </varlistentry>
 252
 253      <varlistentry id="app-initdb-icu-rules">
 254       <term><option>--icu-rules=<replaceable>rules</replaceable></option></term>
 255       <listitem>
 256        <para>
 257         Specifies additional collation rules to customize the behavior of the
 258         default collation.  This is supported for ICU only.
 259        </para>
 260       </listitem>
 261      </varlistentry>
 262
 263      <varlistentry id="app-initdb-data-checksums" xreflabel="data checksums">
 264       <term><option>-k</option></term>
 265       <term><option>--data-checksums</option></term>
 266       <listitem>
 267        <para>
 268         Use checksums on data pages to help detect corruption by the
 269         I/O system that would otherwise be silent. Enabling checksums
 270         may incur a noticeable performance penalty. If set, checksums
 271         are calculated for all objects, in all databases. All checksum
 272         failures will be reported in the
 273         <link linkend="monitoring-pg-stat-database-view">
 274         <structname>pg_stat_database</structname></link> view.
 275         See <xref linkend="checksums" /> for details.
 276        </para>
 277       </listitem>
 278      </varlistentry>
 279
 280      <varlistentry id="app-initdb-option-locale">
 281       <term><option>--locale=<replaceable>locale</replaceable></option></term>
 282       <listitem>
 283        <para>
 284         Sets the default locale for the database cluster.  If this
 285         option is not specified, the locale is inherited from the
 286         environment that <command>initdb</command> runs in. Locale
 287         support is described in <xref linkend="locale"/>.
 288        </para>
 289       </listitem>
 290      </varlistentry>
 291
 292      <varlistentry id="app-initdb-option-lc-collate">
 293       <term><option>--lc-collate=<replaceable>locale</replaceable></option></term>
 294       <term><option>--lc-ctype=<replaceable>locale</replaceable></option></term>
 295       <term><option>--lc-messages=<replaceable>locale</replaceable></option></term>
 296       <term><option>--lc-monetary=<replaceable>locale</replaceable></option></term>
 297       <term><option>--lc-numeric=<replaceable>locale</replaceable></option></term>
 298       <term><option>--lc-time=<replaceable>locale</replaceable></option></term>
 299
 300       <listitem>
 301        <para>
 302         Like <option>--locale</option>, but only sets the locale in
 303         the specified category.
 304        </para>
 305       </listitem>
 306      </varlistentry>
 307
 308      <varlistentry id="app-initdb-option-no-locale">
 309       <term><option>--no-locale</option></term>
 310       <listitem>
 311        <para>
 312         Equivalent to <option>--locale=C</option>.
 313        </para>
 314       </listitem>
 315      </varlistentry>
 316
 317      <varlistentry id="app-initdb-option-locale-provider">
 318       <term><option>--locale-provider={<literal>libc</literal>|<literal>icu</literal>}</option></term>
 319       <listitem>
 320        <para>
 321         This option sets the locale provider for databases created in the new
 322         cluster.  It can be overridden in the <command>CREATE
 323         DATABASE</command> command when new databases are subsequently
 324         created.  The default is <literal>libc</literal> (see <xref
 325         linkend="locale-providers"/>).
 326        </para>
 327       </listitem>
 328      </varlistentry>
 329
 330      <varlistentry id="app-initdb-option-no-sync">
 331       <term><option>-N</option></term>
 332       <term><option>--no-sync</option></term>
 333       <listitem>
 334        <para>
 335         By default, <command>initdb</command> will wait for all files to be
 336         written safely to disk.  This option causes <command>initdb</command>
 337         to return without waiting, which is faster, but means that a
 338         subsequent operating system crash can leave the data directory
 339         corrupt.  Generally, this option is useful for testing, but should not
 340         be used when creating a production installation.
 341        </para>
 342       </listitem>
 343      </varlistentry>
 344
 345      <varlistentry id="app-initdb-option-no-instructions">
 346       <term><option>--no-instructions</option></term>
 347       <listitem>
 348        <para>
 349         By default, <command>initdb</command> will write instructions for how
 350         to start the cluster at the end of its output. This option causes
 351         those instructions to be left out. This is primarily intended for use
 352         by tools that wrap <command>initdb</command> in platform-specific
 353         behavior, where those instructions are likely to be incorrect.
 354        </para>
 355       </listitem>
 356      </varlistentry>
 357
 358      <varlistentry id="app-initdb-option-pwfile">
 359       <term><option>--pwfile=<replaceable>filename</replaceable></option></term>
 360       <listitem>
 361        <para>
 362         Makes <command>initdb</command> read the bootstrap superuser's password
 363         from a file.  The first line of the file is taken as the password.
 364        </para>
 365       </listitem>
 366      </varlistentry>
 367
 368      <varlistentry id="app-initdb-option-sync-method">
 369       <term><option>--sync-method=<replaceable>method</replaceable></option></term>
 370       <listitem>
 371        <para>
 372         When set to <literal>fsync</literal>, which is the default,
 373         <command>initdb</command> will recursively open and synchronize all
 374         files in the data directory.  The search for files will follow symbolic
 375         links for the WAL directory and each configured tablespace.
 376        </para>
 377        <para>
 378         On Linux, <literal>syncfs</literal> may be used instead to ask the
 379         operating system to synchronize the whole file systems that contain the
 380         data directory, the WAL files, and each tablespace.  See
 381         <xref linkend="syncfs"/> for more information about using
 382         <function>syncfs()</function>.
 383        </para>
 384        <para>
 385         This option has no effect when <option>--no-sync</option> is used.
 386        </para>
 387       </listitem>
 388      </varlistentry>
 389
 390      <varlistentry id="app-initdb-option-sync-only">
 391       <term><option>-S</option></term>
 392       <term><option>--sync-only</option></term>
 393       <listitem>
 394        <para>
 395         Safely write all database files to disk and exit.  This does not
 396         perform any of the normal <application>initdb</application> operations.
 397         Generally, this option is useful for ensuring reliable recovery after
 398         changing <xref linkend="guc-fsync"/> from <literal>off</literal> to
 399         <literal>on</literal>.
 400        </para>
 401       </listitem>
 402      </varlistentry>
 403
 404      <varlistentry id="app-initdb-option-text-search-config">
 405       <term><option>-T <replaceable>config</replaceable></option></term>
 406       <term><option>--text-search-config=<replaceable>config</replaceable></option></term>
 407       <listitem>
 408        <para>
 409         Sets the default text search configuration.
 410         See <xref linkend="guc-default-text-search-config"/> for further information.
 411        </para>
 412       </listitem>
 413      </varlistentry>
 414
 415      <varlistentry id="app-initdb-option-username">
 416       <term><option>-U <replaceable class="parameter">username</replaceable></option></term>
 417       <term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
 418       <listitem>
 419        <para>
 420         Selects the user name of the
 421         <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>.
 422         This defaults to the name of the
 423         <glossterm linkend="glossary-cluster-owner">cluster owner</glossterm>.
 424        </para>
 425       </listitem>
 426      </varlistentry>
 427
 428      <varlistentry id="app-initdb-option-pwprompt">
 429       <term><option>-W</option></term>
 430       <term><option>--pwprompt</option></term>
 431       <listitem>
 432        <para>
 433         Makes <command>initdb</command> prompt for a password
 434         to give the bootstrap superuser. If you don't plan on using password
 435         authentication, this is not important.  Otherwise you won't be
 436         able to use password authentication until you have a password
 437         set up.
 438        </para>
 439       </listitem>
 440      </varlistentry>
 441
 442       <varlistentry id="app-initdb-option-waldir">
 443       <term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
 444       <term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term>
 445       <listitem>
 446        <para>
 447         This option specifies the directory where the write-ahead log
 448         should be stored.
 449        </para>
 450       </listitem>
 451      </varlistentry>
 452
 453      <varlistentry id="app-initdb-option-wal-segsize">
 454       <term><option>--wal-segsize=<replaceable>size</replaceable></option></term>
 455       <listitem>
 456        <para>
 457         Set the <firstterm>WAL segment size</firstterm>, in megabytes.  This
 458         is the size of each individual file in the WAL log.  The default size
 459         is 16 megabytes.  The value must be a power of 2 between 1 and 1024
 460         (megabytes).  This option can only be set during initialization, and
 461         cannot be changed later.
 462        </para>
 463
 464        <para>
 465         It may be useful to adjust this size to control the granularity of
 466         WAL log shipping or archiving.  Also, in databases with a high volume
 467         of WAL, the sheer number of WAL files per directory can become a
 468         performance and management problem.  Increasing the WAL file size
 469         will reduce the number of WAL files.
 470        </para>
 471       </listitem>
 472      </varlistentry>
 473     </variablelist>
 474    </para>
 475
 476    <para>
 477     Other, less commonly used, options are also available:
 478
 479     <variablelist>
 480      <varlistentry id="app-initdb-option-set">
 481       <term><option>-c <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
 482       <term><option>--set <replaceable>name</replaceable>=<replaceable>value</replaceable></option></term>
 483       <listitem>
 484        <para>
 485         Forcibly set the server parameter <replaceable>name</replaceable>
 486         to <replaceable>value</replaceable> during <command>initdb</command>,
 487         and also install that setting in the
 488         generated <filename>postgresql.conf</filename> file,
 489         so that it will apply during future server runs.
 490         This option can be given more than once to set several parameters.
 491         It is primarily useful when the environment is such that the server
 492         will not start at all using the default parameters.
 493        </para>
 494       </listitem>
 495      </varlistentry>
 496
 497      <varlistentry id="app-initdb-option-debug">
 498       <term><option>-d</option></term>
 499       <term><option>--debug</option></term>
 500       <listitem>
 501        <para>
 502         Print debugging output from the bootstrap backend and a few other
 503         messages of lesser interest for the general public.
 504         The bootstrap backend is the program <command>initdb</command>
 505         uses to create the catalog tables.  This option generates a tremendous
 506         amount of extremely boring output.
 507        </para>
 508       </listitem>
 509      </varlistentry>
 510
 511      <varlistentry id="app-initdb-option-discard-caches">
 512       <term><option>--discard-caches</option></term>
 513       <listitem>
 514        <para>
 515         Run the bootstrap backend with the
 516         <literal>debug_discard_caches=1</literal> option.
 517         This takes a very long time and is only of use for deep debugging.
 518        </para>
 519       </listitem>
 520      </varlistentry>
 521
 522      <varlistentry id="app-initdb-option-l">
 523       <term><option>-L <replaceable class="parameter">directory</replaceable></option></term>
 524       <listitem>
 525        <para>
 526         Specifies where <command>initdb</command> should find
 527         its input files to initialize the database cluster.  This is
 528         normally not necessary.  You will be told if you need to
 529         specify their location explicitly.
 530        </para>
 531       </listitem>
 532      </varlistentry>
 533
 534      <varlistentry id="app-initdb-option-no-clean">
 535       <term><option>-n</option></term>
 536       <term><option>--no-clean</option></term>
 537       <listitem>
 538        <para>
 539         By default, when <command>initdb</command>
 540         determines that an error prevented it from completely creating the database
 541         cluster, it removes any files it might have created before discovering
 542         that it cannot finish the job. This option inhibits tidying-up and is
 543         thus useful for debugging.
 544        </para>
 545       </listitem>
 546      </varlistentry>
 547     </variablelist>
 548    </para>
 549
 550    <para>
 551     Other options:
 552
 553     <variablelist>
 554      <varlistentry id="app-initdb-option-version">
 555        <term><option>-V</option></term>
 556        <term><option>--version</option></term>
 557        <listitem>
 558        <para>
 559        Print the <application>initdb</application> version and exit.
 560        </para>
 561        </listitem>
 562      </varlistentry>
 563
 564      <varlistentry id="app-initdb-option-help">
 565        <term><option>-?</option></term>
 566        <term><option>--help</option></term>
 567        <listitem>
 568        <para>
 569        Show help about <application>initdb</application> command line
 570        arguments, and exit.
 571        </para>
 572        </listitem>
 573      </varlistentry>
 574
 575     </variablelist>
 576    </para>
 577
 578  </refsect1>
 579
 580  <refsect1>
 581   <title>Environment</title>
 582
 583   <variablelist>
 584    <varlistentry id="app-initdb-environment-pgdata">
 585     <term><envar>PGDATA</envar></term>
 586
 587     <listitem>
 588      <para>
 589       Specifies the directory where the database cluster is to be
 590       stored; can be overridden using the <option>-D</option> option.
 591      </para>
 592     </listitem>
 593    </varlistentry>
 594
 595    <varlistentry id="app-initdb-environment-pg-color">
 596     <term><envar>PG_COLOR</envar></term>
 597     <listitem>
 598      <para>
 599       Specifies whether to use color in diagnostic messages. Possible values
 600       are <literal>always</literal>, <literal>auto</literal> and
 601       <literal>never</literal>.
 602      </para>
 603     </listitem>
 604    </varlistentry>
 605
 606    <varlistentry id="app-initdb-environment-tz">
 607     <term><envar>TZ</envar></term>
 608
 609     <listitem>
 610      <para>
 611       Specifies the default time zone of the created database cluster.  The
 612       value should be a full time zone name
 613       (see <xref linkend="datatype-timezones"/>).
 614      </para>
 615     </listitem>
 616    </varlistentry>
 617   </variablelist>
 618
 619   <para>
 620    This utility, like most other <productname>PostgreSQL</productname> utilities,
 621    also uses the environment variables supported by <application>libpq</application>
 622    (see <xref linkend="libpq-envars"/>).
 623   </para>
 624
 625  </refsect1>
 626
 627  <refsect1>
 628   <title>Notes</title>
 629
 630   <para>
 631    <command>initdb</command> can also be invoked via
 632    <command>pg_ctl initdb</command>.
 633   </para>
 634  </refsect1>
 635
 636  <refsect1>
 637   <title>See Also</title>
 638
 639   <simplelist type="inline">
 640    <member><xref linkend="app-pg-ctl"/></member>
 641    <member><xref linkend="app-postgres"/></member>
 642    <member><xref linkend="auth-pg-hba-conf"/></member>
 643   </simplelist>
 644  </refsect1>
 645
 646 </refentry>