| <!-- |
| 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 for the cluster, use the option |
| <option>--locale</option>. There are also individual options |
| <option>--lc-*</option> and <option>--icu-locale</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. |
| </para> |
| |
| <para> |
| Alternatively, <command>initdb</command> can use the ICU library to provide |
| locale services by specifying <literal>--locale-provider=icu</literal>. The |
| server must be built with ICU support. 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> |
| 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"/>. |
| </para> |
| |
| <para> |
| To alter the default encoding, use the <option>--encoding</option>. |
| More details can be found in <xref linkend="multibyte"/>. |
| </para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para> |
| <variablelist> |
| <varlistentry id="app-initdb-option-auth"> |
| <term><option>-A <replaceable class="parameter">authmethod</replaceable></option></term> |
| <term><option>--auth=<replaceable class="parameter">authmethod</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies the default authentication method for local |
| users used in <filename>pg_hba.conf</filename> (<literal>host</literal> |
| and <literal>local</literal> lines). See <xref linkend="auth-pg-hba-conf"/> |
| for an overview of valid values. |
| </para> |
| |
| <para> |
| <command>initdb</command> will |
| prepopulate <filename>pg_hba.conf</filename> entries using the |
| specified authentication method for non-replication as well as |
| replication connections. |
| </para> |
| |
| <para> |
| Do not use <literal>trust</literal> unless you trust all local users on your |
| system. <literal>trust</literal> is the default for ease of installation. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-auth-host"> |
| <term><option>--auth-host=<replaceable class="parameter">authmethod</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies the authentication method for local users via |
| TCP/IP connections used in <filename>pg_hba.conf</filename> |
| (<literal>host</literal> lines). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-auth-local"> |
| <term><option>--auth-local=<replaceable class="parameter">authmethod</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies the authentication method for local users via |
| Unix-domain socket connections used in <filename>pg_hba.conf</filename> |
| (<literal>local</literal> lines). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-cluster-key-command" xreflabel="cluster key command"> |
| <term><option>-c <replaceable class="parameter">command</replaceable></option></term> |
| <term><option>--cluster-key-command=<replaceable class="parameter">command</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies an external command to obtain the cluster-level |
| key for cluster file encryption during server initialization and |
| server start; see <xref linkend="guc-cluster-key-command"/> for details. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-D <replaceable class="parameter">directory</replaceable></option></term> |
| <term><option>--pgdata=<replaceable class="parameter">directory</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies the directory where the database cluster |
| should be stored. This is the only information required by |
| <command>initdb</command>, but you can avoid writing it by |
| setting the <envar>PGDATA</envar> environment variable, which |
| can be convenient since the database server |
| (<command>postgres</command>) can find the data |
| directory later by the same variable. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-encoding"> |
| <term><option>-E <replaceable class="parameter">encoding</replaceable></option></term> |
| <term><option>--encoding=<replaceable class="parameter">encoding</replaceable></option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <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 |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-icu-locale"> |
| <term><option>--icu-locale=<replaceable>locale</replaceable></option></term> |
| <listitem> |
| <para> |
| Specifies the ICU locale when the ICU provider is used. Locale support |
| is described in <xref linkend="locale"/>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <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> |
| |
| <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 |
| 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 |
| <link linkend="monitoring-pg-stat-database-view"> |
| <structname>pg_stat_database</structname></link> view. |
| See <xref linkend="checksums" /> for details. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-file-encryption-method" |
| xreflabel="file encryption"> |
| <term><option>-K <replaceable class="parameter">encryption_method</replaceable></option></term> |
| <term><option>--file-encryption-method=<replaceable class="parameter">encryption_method</replaceable></option></term> |
| <listitem> |
| <para> |
| Specifies the cluster file encryption method. The |
| value values are <literal>AES128</literal> (the default), <literal>AES192</literal>, and <literal>AES256</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>--locale=<replaceable>locale</replaceable></option></term> |
| <listitem> |
| <para> |
| Sets the default locale for the database cluster. If this |
| option is not specified, the locale is inherited from the |
| environment that <command>initdb</command> runs in. Locale |
| support is described in <xref linkend="locale"/>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-lc-collate"> |
| <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> |
| |
| <listitem> |
| <para> |
| Like <option>--locale</option>, but only sets the locale in |
| the specified category. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-no-locale"> |
| <term><option>--no-locale</option></term> |
| <listitem> |
| <para> |
| Equivalent to <option>--locale=C</option>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-locale-provider"> |
| <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> (see <xref |
| linkend="locale-providers"/>). |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-no-sync"> |
| <term><option>-N</option></term> |
| <term><option>--no-sync</option></term> |
| <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> |
| |
| <varlistentry id="app-initdb-option-no-instructions"> |
| <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 |
| by tools that wrap <command>initdb</command> in platform-specific |
| behavior, where those instructions are likely to be incorrect. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-pwfile"> |
| <term><option>--pwfile=<replaceable>filename</replaceable></option></term> |
| <listitem> |
| <para> |
| Makes <command>initdb</command> read the bootstrap superuser's password |
| from a file. The first line of the file is taken as the password. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-R</option></term> |
| <term><option>--authprompt</option></term> |
| <listitem> |
| <para> |
| Allows the <option>--cluster-key-command</option> command |
| to prompt for a passphrase or PIN. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <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 |
| perform any of the normal <application>initdb</application> operations. |
| Generally, this option is useful for ensuring reliable recovery after |
| changing <xref linkend="guc-fsync"/> from <literal>off</literal> to |
| <literal>on</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-text-search-config"> |
| <term><option>-T <replaceable>config</replaceable></option></term> |
| <term><option>--text-search-config=<replaceable>config</replaceable></option></term> |
| <listitem> |
| <para> |
| Sets the default text search configuration. |
| See <xref linkend="guc-default-text-search-config"/> for further information. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-u <replaceable>datadir</replaceable></option></term> |
| <term><option>--copy-encryption-keys=<replaceable>datadir</replaceable></option></term> |
| <listitem> |
| <para> |
| Copies cluster file encryption keys from another cluster; required |
| when using <application>pg_upgrade</application> on a cluster |
| with cluster file encryption enabled. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-U <replaceable class="parameter">username</replaceable></option></term> |
| <term><option>--username=<replaceable class="parameter">username</replaceable></option></term> |
| <listitem> |
| <para> |
| Sets the user name of the |
| <glossterm linkend="glossary-bootstrap-superuser">bootstrap superuser</glossterm>. |
| This defaults to the name of the operating-system user running |
| <command>initdb</command>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-pwprompt"> |
| <term><option>-W</option></term> |
| <term><option>--pwprompt</option></term> |
| <listitem> |
| <para> |
| Makes <command>initdb</command> prompt for a password |
| to give the bootstrap superuser. If you don't plan on using password |
| 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> |
| |
| <varlistentry id="app-initdb-option-waldir"> |
| <term><option>-X <replaceable class="parameter">directory</replaceable></option></term> |
| <term><option>--waldir=<replaceable class="parameter">directory</replaceable></option></term> |
| <listitem> |
| <para> |
| This option specifies the directory where the write-ahead log |
| should be stored. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-wal-segsize"> |
| <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> |
| </variablelist> |
| </para> |
| |
| <para> |
| Other, less commonly used, options are also available: |
| |
| <variablelist> |
| <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> |
| |
| <varlistentry id="app-initdb-option-debug"> |
| <term><option>-d</option></term> |
| <term><option>--debug</option></term> |
| <listitem> |
| <para> |
| Print debugging output from the bootstrap backend and a few other |
| messages of lesser interest for the general public. |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-discard-caches"> |
| <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> |
| |
| <varlistentry id="app-initdb-option-l"> |
| <term><option>-L <replaceable class="parameter">directory</replaceable></option></term> |
| <listitem> |
| <para> |
| Specifies where <command>initdb</command> should find |
| its input files to initialize the database cluster. This is |
| normally not necessary. You will be told if you need to |
| specify their location explicitly. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-no-clean"> |
| <term><option>-n</option></term> |
| <term><option>--no-clean</option></term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| |
| <para> |
| Other options: |
| |
| <variablelist> |
| <varlistentry id="app-initdb-option-version"> |
| <term><option>-V</option></term> |
| <term><option>--version</option></term> |
| <listitem> |
| <para> |
| Print the <application>initdb</application> version and exit. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-option-help"> |
| <term><option>-?</option></term> |
| <term><option>--help</option></term> |
| <listitem> |
| <para> |
| Show help about <application>initdb</application> command line |
| arguments, and exit. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </para> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Environment</title> |
| |
| <variablelist> |
| <varlistentry id="app-initdb-environment-pgdata"> |
| <term><envar>PGDATA</envar></term> |
| |
| <listitem> |
| <para> |
| Specifies the directory where the database cluster is to be |
| stored; can be overridden using the <option>-D</option> option. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-environment-pg-color"> |
| <term><envar>PG_COLOR</envar></term> |
| <listitem> |
| <para> |
| Specifies whether to use color in diagnostic messages. Possible values |
| are <literal>always</literal>, <literal>auto</literal> and |
| <literal>never</literal>. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry id="app-initdb-environment-tz"> |
| <term><envar>TZ</envar></term> |
| |
| <listitem> |
| <para> |
| Specifies the default time zone of the created database cluster. The |
| value should be a full time zone name |
| (see <xref linkend="datatype-timezones"/>). |
| </para> |
| </listitem> |
| </varlistentry> |
| </variablelist> |
| |
| </refsect1> |
| |
| <refsect1> |
| <title>Notes</title> |
| |
| <para> |
| <command>initdb</command> can also be invoked via |
| <command>pg_ctl initdb</command>. |
| </para> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| |
| <simplelist type="inline"> |
| <member><xref linkend="app-pg-ctl"/></member> |
| <member><xref linkend="app-postgres"/></member> |
| <member><xref linkend="auth-pg-hba-conf"/></member> |
| </simplelist> |
| </refsect1> |
| |
| </refentry> |
