diff options
Diffstat (limited to 'doc/src/sgml/ref/initdb.sgml')
| -rw-r--r-- | doc/src/sgml/ref/initdb.sgml | 606 |
1 files changed, 304 insertions, 302 deletions
diff --git a/doc/src/sgml/ref/initdb.sgml b/doc/src/sgml/ref/initdb.sgml index 19ee8d88dc..f8702f2779 100644 --- a/doc/src/sgml/ref/initdb.sgml +++ b/doc/src/sgml/ref/initdb.sgml @@ -1,313 +1,315 @@ -<REFENTRY ID="APP-INITDB"> -<REFMETA> -<REFENTRYTITLE> -<application>initdb</application> -</REFENTRYTITLE> -<REFMISCINFO>Application</REFMISCINFO> -</REFMETA> -<REFNAMEDIV> -<REFNAME> -<application>initdb</application> -</REFNAME> -<REFPURPOSE> -Create a new <productname>Postgres</productname> database installation -</REFPURPOSE> - </refnamediv> -<REFSYNOPSISDIV> -<REFSYNOPSISDIVINFO> -<DATE>1998-10-02</DATE> -</REFSYNOPSISDIVINFO> -<SYNOPSIS> +<refentry id="APP-INITDB"> + <refmeta> + <refentrytitle> + <application>initdb</application> + </refentrytitle> + <refmiscinfo>Application</refmiscinfo> + </refmeta> + <refnamediv> + <refname> + <application>initdb</application> + </refname> + <refpurpose> + Create a new <productname>Postgres</productname> database installation + </refpurpose> + </refnamediv> + <refsynopsisdiv> + <refsynopsisdivinfo> + <date>1998-10-02</date> + </refsynopsisdivinfo> + <synopsis> initdb [ --pgdata=<replaceable class="parameter">dbdir</replaceable> | -r <replaceable class="parameter">dbdir</replaceable> ] [ --pglib=<replaceable class="parameter">libdir</replaceable> | -l <replaceable class="parameter">libdir</replaceable> ] [ --template=<replaceable class="parameter">template</replaceable> | -t <replaceable class="parameter">template</replaceable> ] [ --username=<replaceable class="parameter">name</replaceable> | -u <replaceable class="parameter">name</replaceable> ] [ --noclean | -n ] [ --debug | -d ] -</SYNOPSIS> + </synopsis> - <REFSECT2 ID="R2-APP-INITDB-1"> - <REFSECT2INFO> - <DATE>1998-10-02</DATE> - </REFSECT2INFO> - <TITLE> - Inputs - </TITLE> - <PARA> - <variablelist> - <varlistentry> - <term> - --pglib=<replaceable class="parameter">libdir</replaceable> - </term> - <term> - -l <replaceable class="parameter">libdir</replaceable> - </term> - <term> - <envar>PGLIB</envar> - </term> - <listitem> - <para> - Where are the files that make up <productname>Postgres</productname>? - Apart from files that - have to go in particular directories because of their function, the - files that make up the <productname>Postgres</productname> software - were installed in a directory - called the <replaceable class="parameter">libdir</replaceable> directory. - An example of a file that will be found - there that <application>initdb</application> - needs is <filename>global1.bki.source</filename>, - which contains all the information that goes - into the shared catalog tables. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - --pgdata=<replaceable class="parameter">dbdir</replaceable> - </term> - <term> - -r <replaceable class="parameter">dbdir</replaceable> - </term> - <term> - <envar>PGDATA</envar> - </term> - <listitem> - <para> - Where in your Unix filesystem do you want the database data to go? - The top level directory is called the <envar>PGDATA</envar> directory. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - --username=<replaceable class="parameter">name</replaceable> - </term> - <term> - -u <replaceable class="parameter">name</replaceable> - </term> - <term> - <envar>PGUSER</envar> - </term> - <listitem> - <para> - Who will be the <productname>Postgres</productname> superuser - for this database system? The - <productname>Postgres</productname> superuser is a Unix user - who owns all files that store the database - system and also owns the postmaster and backend processes that access them. - Or just let it default to you (the Unix user who runs - <application>initdb</application>). - </para> - <note> - <para> - Only the Unix superuser (<literal>root</literal>) - can create a database system with an owner - different from the <productname>Postgres</productname> superuser. - </para> - </note> - </listitem> - </varlistentry> - </variablelist> - </para> - <para> - Other, less commonly used, parameters are also available: - - <variablelist> - <varlistentry> - <term> - --template=<replaceable class="parameter">template</replaceable> - </term> - <term> - -t <replaceable class="parameter">template</replaceable> - </term> - <listitem> - <para> - Replace the <literal>template1</literal> - database in an existing database system, and don't touch anything else. - This is useful when you need to upgrade your <literal>template1</literal> - database using <application>initdb</application> - from a newer release of <productname>Postgres</productname>, - or when your <literal>template1</literal> - database has become corrupted by some system problem. Normally the - contents of <literal>template1</literal> - remain constant throughout the life of the database system. You can't - destroy anything by running <application>initdb</application> - with the - <option>--template</option> - option. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - --noclean - </term> - <term> - -n - </term> - <listitem> - <para> - By default, when <application>initdb</application> - determines that error prevent it from completely creating the database - system, it removes any files it may have created before determining - that it can't finish the job. That includes any core files left by - the programs it invokes. This option inhibits any tidying-up and is - thus useful for debugging. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - --debug - </term> - <term> - -d - </term> - <listitem> - <para> - Print debugging output from the bootstrap backend. - The bootstrap backend is the program <application>initdb</application> - uses to create the catalog tables. This option generates a tremendous - amount of output. It also turns off the final vacuuming step. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - <para> - Files are also input to <application>initdb</application>: - - <variablelist> - <varlistentry> - <term> - <application>postconfig</application> - </term> - <listitem> - <para> - If appearing somewhere in the Unix command search path - (defined by the PATH environment variable). - This is a program that specifies defaults for some of the - command options. See below. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename><envar>PGLIB</envar>/global1.bki.source</filename> - </term> - <listitem> - <para> - Contents for the shared catalog tables in the new database system. This - file is part of the <productname>Postgres</productname> software. - </para> - </listitem> - </varlistentry> - - <varlistentry> - <term> - <filename><envar>PGLIB</envar>/local1_template1.bki.source</filename> - </term> - <listitem> - <para> - Contents for the template1 tables in the new database system. This - file is part of the <productname>Postgres</productname> software. - </para> - </listitem> - </varlistentry> - - </variablelist> - </para> - </refsect2> + <refsect2 id="R2-APP-INITDB-1"> + <refsect2info> + <date>1998-10-02</date> + </refsect2info> + <title> + Inputs + </title> + <para> - <REFSECT2 ID="R2-APP-INITDB-2"> - <REFSECT2INFO> - <DATE>1998-09-26</DATE> - </REFSECT2INFO> - <TITLE> - Outputs - </TITLE> - <PARA> - <application>initdb</application> will create files in the <envar>PGDATA</envar> - data area which are the system tables and framework for a complete - installation. - </para> - </refsect2> - </refsynopsisdiv> + <variablelist> + <varlistentry> + <term>--pglib=<replaceable class="parameter">libdir</replaceable></term> + <term>-l <replaceable class="parameter">libdir</replaceable></term> + <term><envar>PGLIB</envar></term> + <listitem> + <para> + Where are the files that make up <productname>Postgres</productname>? + Apart from files that + have to go in particular directories because of their function, the + files that make up the <productname>Postgres</productname> software + were installed in a directory + called the <replaceable class="parameter">libdir</replaceable> directory. + An example of a file that will be found + there that <application>initdb</application> + needs is <filename>global1.bki.source</filename>, + which contains all the information that goes + into the shared catalog tables. + </para> + </listitem> + </varlistentry> - <REFSECT1 ID="R1-APP-INITDB-1"> - <REFSECT1INFO> - <DATE>1998-09-26</DATE> - </REFSECT1INFO> - <TITLE> - Description - </TITLE> - <PARA> - <application>initdb</application> creates a new - <productname>Postgres</productname> database system. - A database system is a - collection of databases that are all administered by the same Unix user - and managed by a single postmaster. - </para> - <para> - Creating a database system consists of creating the directories in which - the database data will live, generating the shared catalog tables - (tables that don't belong to any particular database), and - creating the <literal>template1</literal> - database. What is the <literal>template1</literal> - database? When you create a database, <productname>Postgres</productname> - does it by copying - everything from the <literal>template1</literal> - database. It contains catalog tables filled in for things like the - builtin types. - </para> - <para> - After <application>initdb</application> - creates the database, it completes the initialization by running - <application>vacuum</application>, which resets some optimization parameters. - </para> - <para> - There are three ways to give parameters to <application>initdb</application>. - - First, you can use <application>initdb</application> command options. - Second, you can set environment - variables before invoking <application>initdb</application>. - Third, you can have a program called <application>postconfig</application> - in your Unix command search path. + <varlistentry> + <term>--pgdata=<replaceable class="parameter">dbdir</replaceable></term> + <term>-r <replaceable class="parameter">dbdir</replaceable></term> + <term><envar>PGDATA</envar></term> + <listitem> + <para> + Where in your Unix filesystem do you want the database data to go? + The top level directory is called the <envar>PGDATA</envar> directory. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--username=<replaceable class="parameter">name</replaceable></term> + <term>-u <replaceable class="parameter">name</replaceable></term> + <term><envar>PGUSER</envar></term> + <listitem> + <para> + Who will be the <productname>Postgres</productname> superuser + for this database system? The + <productname>Postgres</productname> superuser is a Unix user + who owns all files that store the database + system and also owns the postmaster and backend processes that access them. + Or just let it default to you (the Unix user who runs + <application>initdb</application>). + </para> + <note> + <para> + Only the Unix superuser (<literal>root</literal>) + can create a database system with an owner + different from the <productname>Postgres</productname> superuser. + </para> + </note> + </listitem> + </varlistentry> + </variablelist> + </para> + + <para> + Other, less commonly used, parameters are also available: + + <variablelist> + <varlistentry> + <term>--template=<replaceable class="parameter">template</replaceable></term> + <term>-t <replaceable class="parameter">template</replaceable></term> + <listitem> + <para> + Replace the <literal>template1</literal> + database in an existing database system, and don't touch anything else. + This is useful when you need to upgrade your <literal>template1</literal> + database using <application>initdb</application> + from a newer release of <productname>Postgres</productname>, + or when your <literal>template1</literal> + database has become corrupted by some system problem. Normally the + contents of <literal>template1</literal> + remain constant throughout the life of the database system. You can't + destroy anything by running <application>initdb</application> + with the + <option>--template</option> + option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--noclean</term> + <term>-n</term> + <listitem> + <para> + By default, when <application>initdb</application> + determines that error prevent it from completely creating the database + system, it removes any files it may have created before determining + that it can't finish the job. That includes any core files left by + the programs it invokes. This option inhibits any tidying-up and is + thus useful for debugging. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--debug</term> + <term>-d</term> + <listitem> + <para> + Print debugging output from the bootstrap backend. + The bootstrap backend is the program <application>initdb</application> + uses to create the catalog tables. This option generates a tremendous + amount of output. It also turns off the final vacuuming step. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + + <para> + Files are also input to <application>initdb</application>: + + <variablelist> + <varlistentry> + <term><application>postconfig</application></term> + <listitem> + <para> + If appearing somewhere in the Unix command search path + (defined by the PATH environment variable). + This is a program that specifies defaults for some of the + command options. See below. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><envar>PGLIB</envar>/global1.bki.source</filename></term> + <listitem> + <para> + Contents for the shared catalog tables in the new database system. This + file is part of the <productname>Postgres</productname> software. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename><envar>PGLIB</envar>/local1_template1.bki.source</filename></term> + <listitem> + <para> + Contents for the template1 tables in the new database system. This + file is part of the <productname>Postgres</productname> software. + </para> + </listitem> + </varlistentry> + + </variablelist> + </para> + </refsect2> + + <refsect2 id="R2-APP-INITDB-2"> + <refsect2info> + <date>1998-09-26</date> + </refsect2info> + <title> + Outputs + </title> + <para> + <application>initdb</application> will create files in the + <envar>PGDATA</envar> + data area which are the system tables and framework for a complete + installation. + </para> + </refsect2> + </refsynopsisdiv> + + <refsect1 id="R1-APP-INITDB-1"> + <refsect1info> + <date>1998-09-26</date> + </refsect1info> + <title> + Description + </title> + <para> + <application>initdb</application> creates a new + <productname>Postgres</productname> database system. + A database system is a + collection of databases that are all administered by the same Unix user + and managed by a single postmaster. + </para> + <para> + Creating a database system consists of creating the directories in which + the database data will live, generating the shared catalog tables + (tables that don't belong to any particular database), and + creating the <literal>template1</literal> + database. What is the <literal>template1</literal> + database? When you create a database, <productname>Postgres</productname> + does it by copying + everything from the <literal>template1</literal> + database. It contains catalog tables filled in for things like the + builtin types. + </para> + <para> + After <application>initdb</application> + creates the database, it completes the initialization by running + <application>vacuum</application>, which resets some optimization parameters. + </para> + <para> + There are three ways to give parameters to <application>initdb</application>. + + <itemizedlist> + <listitem> + <para> + You can use <application>initdb</application> command options. + </para> + </listitem> + <listitem> + <para> + You can set environment + variables before invoking <application>initdb</application>. + </para> + </listitem> + + <listitem> + <para> + You can have a program called <application>postconfig</application> + in your Unix command search path. <application>initdb</application> invokes that program and that program then writes <application>initdb</application> parameters to its standard output stream. This third option is not a common thing to do, however. - </para> - <para> - Command options always override parameters specified any other way. - The values returned by <application>postconfig</application> - override any environment variables, but your - <application>postconfig</application> - program may base its output on the environment variables if you want - their values to be used. - </para> - <para> - The value that <application>postconfig</application> - outputs must have the format - <programlisting> - <replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable>var2</replaceable>=<replaceable class="parameter">value2</replaceable> ... - </programlisting> - - It can output nothing if it doesn't want to supply any parameters. - The <replaceable>var</replaceable> values are equal to - the corresponding environment variable - names. For example, - <programlisting> - PGDATA=/tmp/postgres_test - </programlisting> - has the - same effect as invoking <application>initdb</application> - with an environment variable called <envar>PGDATA</envar> whose value is - <filename>/tmp/postgres_test</filename>. - </para> - </refsect1> -</REFENTRY> + </para> + </listitem> + </itemizedlist> + </para> + + <para> + Command options always override parameters specified any other way. + The values returned by <application>postconfig</application> + override any environment variables, but your + <application>postconfig</application> + program may base its output on the environment variables if you want + their values to be used. + </para> + + <para> + The value that <application>postconfig</application> + outputs must have the format + <synopsis> +<replaceable>var1</replaceable>=<replaceable class="parameter">value1</replaceable> <replaceable class="parameter">var2</replaceable>=<replaceable class="parameter">value2</replaceable> ... + </synopsis> + + It can output nothing if it doesn't want to supply any parameters. + The <replaceable>var</replaceable> values are equal to + the corresponding environment variable + names. For example, + <programlisting> +PGDATA=/tmp/postgres_test + </programlisting> + has the + same effect as invoking <application>initdb</application> + with an environment variable called <envar>PGDATA</envar> whose value is + <filename>/tmp/postgres_test</filename>. + </para> + </refsect1> +</refentry> + +<!-- Keep this comment at the end of the file +Local variables: +mode: sgml +sgml-omittag:nil +sgml-shorttag:t +sgml-minimize-attributes:nil +sgml-always-quote-attributes:t +sgml-indent-step:1 +sgml-indent-data:t +sgml-parent-document:nil +sgml-default-dtd-file:"../reference.ced" +sgml-exposed-tags:nil +sgml-local-catalogs:"/usr/lib/sgml/catalog" +sgml-local-ecat-files:nil +End: +--> |