Add init[db] option to pg_ctl

pg_ctl gets a new mode that runs initdb.  Adjust the documentation a bit to
not assume that initdb is the only way to run database cluster initialization.
But don't replace initdb as the canonical way.

Author: Zdenek Kotala <Zdenek.Kotala@Sun.COM>

doc/src/sgml/config.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.235 2009/11/28 23:38:06 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/config.sgml,v 1.236 2009/12/10 06:32:27 petere Exp $ -->
 
 <chapter Id="runtime-config">
   <title>Server Configuration</title>
@@ -54,9 +54,9 @@
    <para>
     One way to set these parameters is to edit the file
     <filename>postgresql.conf</><indexterm><primary>postgresql.conf</></>,
-    which is normally kept in the data directory. (<application>initdb</>
-    installs a default copy there.) An example of what this file might look
-    like is:
+    which is normally kept in the data directory.  (A default copy is
+    installed there when the database cluster directory is
+    initialized.)  An example of what this file might look like is:
 <programlisting>
 # This is a comment
 log_connections = yes

doc/src/sgml/manage-ag.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.58 2009/05/06 16:15:20 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.59 2009/12/10 06:32:27 petere Exp $ -->
 
 <chapter id="managing-databases">
  <title>Managing Databases</title>
@@ -119,8 +119,8 @@ CREATE DATABASE <replaceable>name</>;
   <para>
    A second database,
    <literal>template1</literal>,<indexterm><primary>template1</></>
-   is also created by
-   <command>initdb</>.  Whenever a new database is created within the
+   is also created during database cluster initialization.  Whenever a
+   new database is created within the
    cluster, <literal>template1</literal> is essentially cloned.
    This means that any changes you make in <literal>template1</> are
    propagated to all subsequently created databases. Therefore it is
@@ -196,7 +196,8 @@ createdb -O <replaceable>rolename</> <replaceable>dbname</>
    <literal>template1</>, that is, only the standard objects
    predefined by your version of
    <productname>PostgreSQL</productname>.  <literal>template0</>
-   should never be changed after <command>initdb</>.  By instructing
+   should never be changed after the database cluster has been
+   initialized.  By instructing
    <command>CREATE DATABASE</> to copy <literal>template0</> instead
    of <literal>template1</>, you can create a <quote>virgin</> user
    database that contains none of the site-local additions in
@@ -453,7 +454,8 @@ CREATE TABLE foo(i int);
   </para>
 
   <para>
-   Two tablespaces are automatically created by <literal>initdb</>. The
+   Two tablespaces are automatically created when the database cluster
+   is initialized.  The
    <literal>pg_global</> tablespace is used for shared system catalogs. The
    <literal>pg_default</> tablespace is the default tablespace of the
    <literal>template1</> and <literal>template0</> databases (and, therefore,

doc/src/sgml/ref/initdb.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.44 2008/09/23 09:20:34 heikki Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.45 2009/12/10 06:32:28 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -309,10 +309,20 @@ PostgreSQL documentation
 
  </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>
   </simplelist>
  </refsect1>

doc/src/sgml/ref/pg_ctl-ref.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.46 2008/06/26 01:12:19 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/pg_ctl-ref.sgml,v 1.47 2009/12/10 06:32:28 petere Exp $
 PostgreSQL documentation
 -->
 
@@ -12,7 +12,7 @@ PostgreSQL documentation
 
  <refnamediv>
   <refname>pg_ctl</refname>
-  <refpurpose>start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
+  <refpurpose>initialize, start, stop, or restart a <productname>PostgreSQL</productname> server</refpurpose>
  </refnamediv>
 
  <indexterm zone="app-pg-ctl">
@@ -22,6 +22,13 @@ PostgreSQL documentation
  <refsynopsisdiv>
   <cmdsynopsis>
 
+   <command>pg_ctl</command>
+   <arg choice="plain">init[db]</arg>
+   <arg>-s</arg>
+   <arg>-D <replaceable>datadir</replaceable></arg>
+   <arg>-o <replaceable>options</replaceable></arg>
+   <sbr>
+
    <command>pg_ctl</command>
    <arg choice="plain">start</arg>
    <arg>-w</arg>
@@ -105,7 +112,8 @@ PostgreSQL documentation
  <refsect1 id="app-pg-ctl-description">
   <title>Description</title>
   <para>
-   <application>pg_ctl</application> is a utility for starting,
+   <application>pg_ctl</application> is a utility for initializing a
+   <productname>PostgreSQL</productname> database cluster, starting,
    stopping, or restarting the <productname>PostgreSQL</productname>
    backend server (<xref linkend="app-postgres">), or displaying the
    status of a running server.  Although the server can be started
@@ -115,6 +123,15 @@ PostgreSQL documentation
    controlled shutdown.
   </para>
 
+  <para>
+   The <option>init</option> or <option>initdb</option> mode creates a
+   new
+   <productname>PostgreSQL</productname> database cluster.  A database
+   cluster is a collection of databases that are managed by a single
+   server instance.  This mode invokes the <command>initdb</command>
+   command.  See <xref linkend="app-initdb"> for details.
+  </para>
+
   <para>
    In <option>start</option> mode, a new server is launched.  The
    server is started in the background, and standard input is attached to
@@ -263,6 +280,12 @@ PostgreSQL documentation
         option unless you are doing something unusual and get errors
         that the <filename>postgres</filename> executable was not found.
        </para>
+
+       <para>
+        In <literal>init</literal> mode, this option analogously
+        specifies the location of the <filename>initdb</filename>
+        executable.
+       </para>
       </listitem>
      </varlistentry>
 
@@ -542,9 +565,10 @@ Command line was:
  <refsect1>
   <title>See Also</title>
 
-  <para>
-   <xref linkend="app-postgres">
-  </para>
+  <simplelist type="inline">
+   <member><xref linkend="app-initdb"></member>
+   <member><xref linkend="app-postgres"></member>
+  </simplelist>
  </refsect1>
 
 </refentry>

doc/src/sgml/runtime.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.428 2009/04/27 16:27:36 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/runtime.sgml,v 1.429 2009/12/10 06:32:28 petere Exp $ -->
 
 <chapter Id="runtime">
  <title>Server Setup and Operation</title>
@@ -93,6 +93,20 @@
    </para>
   </tip>
 
+  <para>
+   Alternatively, you can run <command>initdb</command> via
+   the <xref linkend="app-pg-ctl">
+   program<indexterm><primary>pg_ctl</></> like so:
+<screen>
+<prompt>$</> <userinput>pg_ctl -D /usr/local/pgsql/data initdb</userinput>
+</screen>
+   This may be more intuitive if you are
+   using <command>pg_ctl</command> for starting and stopping the
+   server (see <xref linkend="server-start">), so
+   that <command>pg_ctl</command> would be the sole command you use
+   for managing the database server instance.
+  </para>
+
   <para>
    <command>initdb</command> will attempt to create the directory you
    specify if it does not already exist. It is likely that it will not

doc/src/sgml/xfunc.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.142 2009/11/30 15:49:35 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/xfunc.sgml,v 1.143 2009/12/10 06:32:28 petere Exp $ -->
 
  <sect1 id="xfunc">
   <title>User-Defined Functions</title>
@@ -1353,7 +1353,8 @@ CREATE FUNCTION test(int, int) RETURNS int
 
    <para>
     Normally, all internal functions present in the
-    server are declared during the initialization of the database cluster (<command>initdb</command>),
+    server are declared during the initialization of the database cluster
+    (see <xref linkend="creating-cluster">),
     but a user could use <command>CREATE FUNCTION</command>
     to create additional alias names for an internal function.
     Internal functions are declared in <command>CREATE FUNCTION</command>