mirror of
https://git.postgresql.org/git/postgresql.git
synced 2024-08-31 16:37:25 +02:00
294 lines
10 KiB
Plaintext
294 lines
10 KiB
Plaintext
<!--
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.37 2006/09/16 00:30:18 momjian Exp $
|
|
PostgreSQL documentation
|
|
-->
|
|
|
|
<refentry id="APP-INITDB">
|
|
<refmeta>
|
|
<refentrytitle id="APP-INITDB-TITLE">initdb</refentrytitle>
|
|
<manvolnum>1</manvolnum>
|
|
<refmiscinfo>Application</refmiscinfo>
|
|
</refmeta>
|
|
|
|
<refnamediv>
|
|
<refname>initdb</refname>
|
|
<refpurpose>create a new <productname>PostgreSQL</productname> database cluster</refpurpose>
|
|
</refnamediv>
|
|
|
|
<indexterm zone="app-initdb">
|
|
<primary>initdb</primary>
|
|
</indexterm>
|
|
|
|
<refsynopsisdiv>
|
|
<cmdsynopsis>
|
|
<command>initdb</command>
|
|
<arg rep="repeat"><replaceable>option</></arg>
|
|
<group choice="plain">
|
|
<arg>--pgdata </arg>
|
|
<arg>-D </arg>
|
|
<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> database cluster. A database
|
|
cluster is a collection of databases that are managed by a single
|
|
server instance.
|
|
</para>
|
|
|
|
<para>
|
|
Creating a database cluster consists of creating the directories in
|
|
which the database 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>template1</literal>
|
|
and <literal>postgres</literal> databases. When you later create a
|
|
new database, everything in the <literal>template1</literal> database is
|
|
copied. (Therefore, anything installed in <literal>template1</literal>
|
|
is automatically copied into each database created later.)
|
|
The <literal>postgres</literal> database is a default database meant
|
|
for use by users, utilities and third party applications.
|
|
</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 may not be run as root, you must not run
|
|
<command>initdb</command> as root either. (It will in fact refuse
|
|
to do so.)
|
|
</para>
|
|
|
|
<para>
|
|
<command>initdb</command> initializes the database cluster's default
|
|
locale and character set encoding. The collation order
|
|
(<literal>LC_COLLATE</>) and character set classes
|
|
(<literal>LC_CTYPE</>, e.g. upper, lower, digit) are fixed for all
|
|
databases and can not be changed. Collation orders other than
|
|
<literal>C</> or <literal>POSIX</> also have a performance penalty.
|
|
For these reasons it is important to choose the right locale when
|
|
running <command>initdb</command>. The remaining locale categories
|
|
can be changed later when the server is started. All server locale
|
|
values (<literal>lc_*</>) can be displayed via <command>SHOW ALL</>.
|
|
More details can be found in <xref linkend="locale">.
|
|
</para>
|
|
|
|
<para>
|
|
The character set encoding can be set separately for a database when
|
|
it is created. <command>initdb</command> determines the encoding for
|
|
the <literal>template1</literal> database, which will serve as the
|
|
default for all other databases. To alter the default encoding use
|
|
the <option>--encoding</option> option. More details can be found in
|
|
<xref linkend="multibyte">.
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Options</title>
|
|
|
|
<para>
|
|
<variablelist>
|
|
<varlistentry>
|
|
<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 authentication method for local users
|
|
used in <filename>pg_hba.conf</>. Do not use <literal>trust</>
|
|
unless you trust all local users on your system. <literal>Trust</>
|
|
is the default for ease of installation.
|
|
</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 database
|
|
directory later by the same variable.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<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 database. This will also
|
|
be the default encoding of any database you create later,
|
|
unless you override it there. The default is derived from the locale, or
|
|
<literal>SQL_ASCII</literal> if that does not work. The character sets supported by
|
|
the <productname>PostgreSQL</productname> server are described
|
|
in <xref linkend="multibyte-charset-supported">.
|
|
</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>
|
|
<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>
|
|
<term><option>-U <replaceable class="parameter">username</replaceable></option></term>
|
|
<term><option>--username=<replaceable class="parameter">username</replaceable></option></term>
|
|
<listitem>
|
|
<para>
|
|
Selects the user name of the database superuser. This defaults
|
|
to the name of the effective user running
|
|
<command>initdb</command>. It is really not important what the
|
|
superuser's name is, but one might choose to keep the
|
|
customary name <systemitem>postgres</systemitem>, even if the operating
|
|
system user's name is different.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>-W</option></term>
|
|
<term><option>--pwprompt</option></term>
|
|
<listitem>
|
|
<para>
|
|
Makes <command>initdb</command> prompt for a password
|
|
to give the database 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>
|
|
<term><option>--pwfile=<replaceable>filename</></option></term>
|
|
<listitem>
|
|
<para>
|
|
Makes <command>initdb</command> read the database superuser's password
|
|
from a file. The first line of the file is taken as the password.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
<para>
|
|
Other, less commonly used, parameters are also available:
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<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>
|
|
<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>
|
|
<term><option>-n</option></term>
|
|
<term><option>--noclean</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 may have created before discovering
|
|
that it can't finish the job. This option inhibits tidying-up and is
|
|
thus useful for debugging.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>Environment</title>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><envar>PGDATA</envar></term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Specifies the directory where the database cluster is to be
|
|
stored; may be overridden using the <option>-D</option> option.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1>
|
|
<title>See Also</title>
|
|
|
|
<simplelist type="inline">
|
|
<member><xref linkend="app-postgres"></member>
|
|
</simplelist>
|
|
</refsect1>
|
|
|
|
</refentry>
|