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</>
+    which is normally kept in the data directory.  (A default copy is
-    installs a default copy there.) An example of what this file might look
+    installed there when the database cluster directory is
-    like 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
+   is also created during database cluster initialization.  Whenever a
-   <command>initdb</>.  Whenever a new database is created within the
+   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>
+  <simplelist type="inline">
-   <xref linkend="app-postgres">
+   <member><xref linkend="app-initdb"></member>
-  </para>
+   <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>

src/bin/pg_ctl/pg_ctl.c

@@ -4,7 +4,7 @@
  *
  * Portions Copyright (c) 1996-2009, PostgreSQL Global Development Group
  *
- * $PostgreSQL: pgsql/src/bin/pg_ctl/pg_ctl.c,v 1.115 2009/11/14 15:39:36 mha Exp $
+ * $PostgreSQL: pgsql/src/bin/pg_ctl/pg_ctl.c,v 1.116 2009/12/10 06:32:28 petere Exp $
  *
  *-------------------------------------------------------------------------
  */
@@ -57,6 +57,7 @@ typedef enum
 typedef enum
 {
 	NO_COMMAND = 0,
+	INIT_COMMAND,
 	START_COMMAND,
 	STOP_COMMAND,
 	RESTART_COMMAND,
@@ -82,7 +83,7 @@ static char *pgdata_opt = NULL;
 static char *post_opts = NULL;
 static const char *progname;
 static char *log_file = NULL;
-static char *postgres_path = NULL;
+static char *exec_path = NULL;
 static char *register_servicename = "PostgreSQL";		/* FIXME: + version ID? */
 static char *register_username = NULL;
 static char *register_password = NULL;
@@ -100,6 +101,7 @@ static void do_advice(void);
 static void do_help(void);
 static void set_mode(char *modeopt);
 static void set_sig(char *signame);
+static void do_init(void);
 static void do_start(void);
 static void do_stop(void);
 static void do_restart(void);
@@ -358,11 +360,11 @@ start_postmaster(void)
 	 */
 	if (log_file != NULL)
 		snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s < \"%s\" >> \"%s\" 2>&1 &" SYSTEMQUOTE,
-				 postgres_path, pgdata_opt, post_opts,
+				 exec_path, pgdata_opt, post_opts,
 				 DEVNULL, log_file);
 	else
 		snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s < \"%s\" 2>&1 &" SYSTEMQUOTE,
-				 postgres_path, pgdata_opt, post_opts, DEVNULL);
+				 exec_path, pgdata_opt, post_opts, DEVNULL);
 
 	return system(cmd);
 #else							/* WIN32 */
@@ -376,10 +378,10 @@ start_postmaster(void)
 
 	if (log_file != NULL)
 		snprintf(cmd, MAXPGPATH, "CMD /C " SYSTEMQUOTE "\"%s\" %s%s < \"%s\" >> \"%s\" 2>&1" SYSTEMQUOTE,
-				 postgres_path, pgdata_opt, post_opts, DEVNULL, log_file);
+				 exec_path, pgdata_opt, post_opts, DEVNULL, log_file);
 	else
 		snprintf(cmd, MAXPGPATH, "CMD /C " SYSTEMQUOTE "\"%s\" %s%s < \"%s\" 2>&1" SYSTEMQUOTE,
-				 postgres_path, pgdata_opt, post_opts, DEVNULL);
+				 exec_path, pgdata_opt, post_opts, DEVNULL);
 
 	if (!CreateRestrictedProcess(cmd, &pi, false))
 		return GetLastError();
@@ -607,13 +609,70 @@ read_post_opts(void)
 										 * name */
 					post_opts = arg1 + 1;		/* point past whitespace */
 				}
-				if (postgres_path == NULL)
+				if (exec_path == NULL)
-					postgres_path = optline;
+					exec_path = optline;
 			}
 		}
 	}
 }
 
+static char *
+find_other_exec_or_die(const char *argv0, const char *target, const char *versionstr)
+{
+	int			ret;
+	char	   *found_path;
+
+	found_path = pg_malloc(MAXPGPATH);
+
+	if ((ret = find_other_exec(argv0, target, versionstr, found_path)) < 0)
+	{
+		char		full_path[MAXPGPATH];
+
+		if (find_my_exec(argv0, full_path) < 0)
+			strlcpy(full_path, progname, sizeof(full_path));
+
+		if (ret == -1)
+			write_stderr(_("The program \"%s\" is needed by %s "
+						   "but was not found in the\n"
+						   "same directory as \"%s\".\n"
+						   "Check your installation.\n"),
+						 target, progname, full_path);
+		else
+			write_stderr(_("The program \"%s\" was found by \"%s\"\n"
+						   "but was not the same version as %s.\n"
+						   "Check your installation.\n"),
+						 target, full_path, progname);
+		exit(1);
+	}
+
+	return found_path;
+}
+
+static void
+do_init(void)
+{
+	char cmd[MAXPGPATH];
+
+	if (exec_path == NULL)
+		exec_path = find_other_exec_or_die(argv0, "initdb", "initdb (PostgreSQL) " PG_VERSION "\n");
+
+	if (post_opts == NULL)
+		post_opts = "";
+
+	if (!silent_mode)
+		snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s" SYSTEMQUOTE,
+				 exec_path, pgdata_opt, post_opts);
+	else
+		snprintf(cmd, MAXPGPATH, SYSTEMQUOTE "\"%s\" %s%s > \"%s\"" SYSTEMQUOTE,
+				 exec_path, pgdata_opt, post_opts, DEVNULL);
+	
+	if (system(cmd) != 0)
+	{
+		write_stderr(_("%s: database system initialization failed\n"), progname);
+		exit(1);
+	}
+}
+
 static void
 do_start(void)
 {
@@ -636,36 +695,8 @@ do_start(void)
 	if (ctl_command == RESTART_COMMAND || pgdata_opt == NULL)
 		pgdata_opt = "";
 
-	if (postgres_path == NULL)
+	if (exec_path == NULL)
-	{
+		exec_path = find_other_exec_or_die(argv0, "postgres", PG_BACKEND_VERSIONSTR);
-		char	   *postmaster_path;
-		int			ret;
-
-		postmaster_path = pg_malloc(MAXPGPATH);
-
-		if ((ret = find_other_exec(argv0, "postgres", PG_BACKEND_VERSIONSTR,
-								   postmaster_path)) < 0)
-		{
-			char		full_path[MAXPGPATH];
-
-			if (find_my_exec(argv0, full_path) < 0)
-				strlcpy(full_path, progname, sizeof(full_path));
-
-			if (ret == -1)
-				write_stderr(_("The program \"postgres\" is needed by %s "
-							   "but was not found in the\n"
-							   "same directory as \"%s\".\n"
-							   "Check your installation.\n"),
-							 progname, full_path);
-			else
-				write_stderr(_("The program \"postgres\" was found by \"%s\"\n"
-							   "but was not the same version as %s.\n"
-							   "Check your installation.\n"),
-							 full_path, progname);
-			exit(1);
-		}
-		postgres_path = postmaster_path;
-	}
 
 #if defined(HAVE_GETRLIMIT) && defined(RLIMIT_CORE)
 	if (allow_core_files)
@@ -1536,6 +1567,7 @@ do_help(void)
 	printf(_("%s is a utility to start, stop, restart, reload configuration files,\n"
 			 "report the status of a PostgreSQL server, or signal a PostgreSQL process.\n\n"), progname);
 	printf(_("Usage:\n"));
+	printf(_("  %s init[db]               [-D DATADIR] [-s] [-o \"OPTIONS\"]\n"), progname);
 	printf(_("  %s start   [-w] [-t SECS] [-D DATADIR] [-s] [-l FILENAME] [-o \"OPTIONS\"]\n"), progname);
 	printf(_("  %s stop    [-W] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"), progname);
 	printf(_("  %s restart [-w] [-t SECS] [-D DATADIR] [-s] [-m SHUTDOWN-MODE]\n"
@@ -1568,7 +1600,7 @@ do_help(void)
 #endif
 	printf(_("  -l, --log FILENAME     write (or append) server log to FILENAME\n"));
 	printf(_("  -o OPTIONS             command line options to pass to postgres\n"
-			 "                         (PostgreSQL server executable)\n"));
+			 "                         (PostgreSQL server executable) or initdb\n"));
 	printf(_("  -p PATH-TO-POSTGRES    normally not necessary\n"));
 	printf(_("\nOptions for stop or restart:\n"));
 	printf(_("  -m SHUTDOWN-MODE   can be \"smart\", \"fast\", or \"immediate\"\n"));
@@ -1770,7 +1802,7 @@ main(int argc, char **argv)
 					post_opts = xstrdup(optarg);
 					break;
 				case 'p':
-					postgres_path = xstrdup(optarg);
+					exec_path = xstrdup(optarg);
 					break;
 				case 'P':
 					register_password = xstrdup(optarg);
@@ -1825,7 +1857,10 @@ main(int argc, char **argv)
 				exit(1);
 			}
 
-			if (strcmp(argv[optind], "start") == 0)
+			if (strcmp(argv[optind], "init") == 0
+				|| strcmp(argv[optind], "initdb") == 0)
+				ctl_command = INIT_COMMAND;
+			else if (strcmp(argv[optind], "start") == 0)
 				ctl_command = START_COMMAND;
 			else if (strcmp(argv[optind], "stop") == 0)
 				ctl_command = STOP_COMMAND;
@@ -1922,6 +1957,9 @@ main(int argc, char **argv)
 
 	switch (ctl_command)
 	{
+		case INIT_COMMAND:
+			do_init();
+			break;
 		case STATUS_COMMAND:
 			do_status();
 			break;