1999-07-22 17:09:15 +02:00
|
|
|
<!--
|
2008-09-23 11:20:39 +02:00
|
|
|
$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.44 2008/09/23 09:20:34 heikki Exp $
|
2001-12-08 04:24:40 +01:00
|
|
|
PostgreSQL documentation
|
1999-07-22 17:09:15 +02:00
|
|
|
-->
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refentry id="APP-INITDB">
|
|
|
|
<refmeta>
|
2001-09-08 17:24:00 +02:00
|
|
|
<refentrytitle id="APP-INITDB-TITLE">initdb</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
|
|
|
|
2003-08-31 19:32:24 +02:00
|
|
|
<indexterm zone="app-initdb">
|
|
|
|
<primary>initdb</primary>
|
|
|
|
</indexterm>
|
|
|
|
|
1999-07-06 19:16:42 +02:00
|
|
|
<refsynopsisdiv>
|
2000-11-12 00:01:45 +01:00
|
|
|
<cmdsynopsis>
|
|
|
|
<command>initdb</command>
|
2003-03-24 15:32:51 +01:00
|
|
|
<arg rep="repeat"><replaceable>option</></arg>
|
2002-10-12 01:03:48 +02:00
|
|
|
<group choice="plain">
|
|
|
|
<arg>--pgdata </arg>
|
|
|
|
<arg>-D </arg>
|
|
|
|
<replaceable>directory</replaceable>
|
|
|
|
</group>
|
2000-11-12 00:01:45 +01:00
|
|
|
</cmdsynopsis>
|
|
|
|
</refsynopsisdiv>
|
|
|
|
|
|
|
|
<refsect1 id="R1-APP-INITDB-1">
|
|
|
|
<title>
|
|
|
|
Description
|
|
|
|
</title>
|
|
|
|
<para>
|
2001-09-08 17:24:00 +02:00
|
|
|
<command>initdb</command> creates a new
|
2003-03-24 15:32:51 +01:00
|
|
|
<productname>PostgreSQL</productname> database cluster. A database
|
|
|
|
cluster is a collection of databases that are managed by a single
|
|
|
|
server instance.
|
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>
|
2005-02-22 03:54:19 +01:00
|
|
|
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>
|
2005-06-21 06:02:34 +02:00
|
|
|
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.
|
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>
|
|
|
|
|
|
|
|
<para>
|
2005-02-22 03:54:19 +01:00
|
|
|
<command>initdb</command> initializes the database cluster's default
|
2008-09-23 11:20:39 +02:00
|
|
|
locale and character set encoding. The character set encoding,
|
|
|
|
collation order (<literal>LC_COLLATE</>) and character set classes
|
|
|
|
(<literal>LC_CTYPE</>, e.g. upper, lower, digit) can be set separately
|
|
|
|
for a database when it is created. <command>initdb</command> determines
|
|
|
|
those settings for the <literal>template1</literal> database, which will
|
|
|
|
serve as the default for all other databases.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
To alter the default collation order or character set classes, use the
|
|
|
|
<option>--lc-collate</option> and <option>--lc-ctype</option> options.
|
|
|
|
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>.
|
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
The remaining locale categories can be changed later when the server
|
|
|
|
is started. You can also use <option>--locale</option> to set the
|
|
|
|
default for all locale categories, including collation order and
|
|
|
|
character set classes. All server locale values (<literal>lc_*</>) can
|
|
|
|
be displayed via <command>SHOW ALL</>.
|
2005-02-22 03:54:19 +01:00
|
|
|
More details 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>.
|
|
|
|
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>
|
|
|
|
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>
|
|
|
|
|
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
|
2006-06-18 17:38:37 +02:00
|
|
|
(<command>postgres</command>) can find the database
|
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>
|
2001-11-28 21:49:10 +01:00
|
|
|
Selects the encoding of the template database. This will also
|
2004-03-23 03:47:35 +01:00
|
|
|
be the default encoding of any database you create later,
|
2004-07-14 19:55:10 +02:00
|
|
|
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
|
2004-03-23 03:47:35 +01:00
|
|
|
the <productname>PostgreSQL</productname> server are described
|
|
|
|
in <xref linkend="multibyte-charset-supported">.
|
1999-12-17 02:05:31 +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
|
|
|
|
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
|
|
|
|
2007-01-06 20:40:00 +01:00
|
|
|
<varlistentry>
|
|
|
|
<term><option>-X <replaceable class="parameter">directory</replaceable></option></term>
|
|
|
|
<term><option>--xlogdir=<replaceable class="parameter">directory</replaceable></option></term>
|
|
|
|
<listitem>
|
|
|
|
<para>
|
|
|
|
This option specifies the directory where the transaction log
|
|
|
|
should be stored.
|
|
|
|
</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>
|
|
|
|
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>
|
2004-06-24 21:26:59 +02:00
|
|
|
|
|
|
|
<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>
|
2002-10-12 01:03:48 +02:00
|
|
|
</variablelist>
|
1999-07-06 19:16:42 +02:00
|
|
|
</para>
|
|
|
|
|
|
|
|
<para>
|
|
|
|
Other, less commonly used, parameters are also available:
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
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>
|
|
|
|
<term><option>--noclean</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>
|
|
|
|
</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>
|
|
|
|
</variablelist>
|
2007-02-20 19:10:59 +01:00
|
|
|
|
|
|
|
<para>
|
|
|
|
This utility, like most other <productname>PostgreSQL</> utilities,
|
2007-03-26 19:23:37 +02:00
|
|
|
also uses the environment variables supported by <application>libpq</>
|
|
|
|
(see <xref linkend="libpq-envars">).
|
2007-02-20 19:10:59 +01:00
|
|
|
</para>
|
|
|
|
|
2001-09-08 17:24:00 +02:00
|
|
|
</refsect1>
|
|
|
|
|
|
|
|
<refsect1>
|
|
|
|
<title>See Also</title>
|
1999-07-06 19:16:42 +02:00
|
|
|
|
2001-09-08 17:24:00 +02:00
|
|
|
<simplelist type="inline">
|
|
|
|
<member><xref linkend="app-postgres"></member>
|
|
|
|
</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>
|