Get rid of initdb -t bugs by the simple expedient of getting rid of

initdb -t.  This option is obsoleted by 7.1's ability to drop and
recreate template1 during normal operation.

doc/src/sgml/ref/initdb.sgml

 <!--
-$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.14 2000/12/25 23:15:26 petere Exp $
+$Header: /cvsroot/pgsql/doc/src/sgml/ref/initdb.sgml,v 1.15 2001/01/20 22:09:24 tgl Exp $
 Postgres documentation
 -->
 
@@ -41,7 +41,6 @@ Postgres documentation
     <arg>-L <replaceable>directory</replaceable></arg>
     <group><arg>--noclean</arg><arg>-n</arg></group>
     <group><arg>--debug</arg><arg>-d</arg></group>
-    <group><arg>--template</arg><arg>-t</arg></group>
   </cmdsynopsis>
  </refsynopsisdiv>
 
@@ -58,8 +57,8 @@ Postgres documentation
   <para>
    Creating a database system consists of creating the directories in which
    the database data will live, generating the shared catalog tables 
-   (tables that do not belong to any particular database), and
-   creating the <literal>template1</literal>
+   (tables that belong to the whole cluster rather than to any particular
+   database), and creating the <literal>template1</literal>
    database.  When you create a new database, everything in the
    <literal>template1</literal> database is copied.
    It contains catalog tables filled in for things like the
@@ -67,8 +66,9 @@ Postgres documentation
   </para>
 
   <para>
-   You must not execute <application>initdb</application> as root. This is
-   because you cannot run the database server as root either, but the
+   You must not execute <application>initdb</application> as root; it must
+   be run by the Unix user account that will run the database server.
+   This is because you cannot run the database server as root either, but the
    server needs to have access to the files <application>initdb</application>
    creates. Furthermore, during the initialization phase, when there are no
    users and no access controls installed, <productname>Postgres</productname>
@@ -78,10 +78,14 @@ Postgres documentation
   </para>
 
   <para>
-   Although <application>initdb</application> will attempt to create the respective
-   data directory, chances are that it won't have the permission to do so. Thus
-   it is a good idea to create the data directory before running <application>initdb</application>
-   <emphasis>and</emphasis> to hand over the ownership of it to the database superuser.
+   Although <application>initdb</application> will attempt to create the
+   specified data directory, often it won't have permission to do so,
+   since the parent of the desired data directory is often a root-owned
+   directory.  To set up an arrangement like this, create an empty data
+   directory as root, then use <application>chown</application> to hand over
+   ownership of that directory to the database user account, then
+   <application>su</application> to become the database user, and
+   finally run <application>initdb</application> as the database user.
   </para>
 
   <refsect2>
@@ -96,7 +100,7 @@ Postgres documentation
        <para>
         This option specifies where in the file system the database
         should be stored. This is the only information required by
-        <application>initdb</application>, but you can avoid it by
+        <application>initdb</application>, but you can avoid writing it by
         setting the <envar>PGDATA</envar> environment variable, which
         can be convenient since the database server
         (<filename>postmaster</filename>) can find the database
@@ -125,7 +129,7 @@ Postgres documentation
       <listitem>
        <para>
         Makes <application>initdb</application> prompt for a password
-        of the database superuser. If you don't plan on using 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.
@@ -166,28 +170,6 @@ Postgres documentation
       </listitem>
      </varlistentry>
 
-     <varlistentry>
-      <term>--template</term>
-      <term>-t</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>
@@ -195,8 +177,8 @@ Postgres documentation
        <para>
 	By default, when <application>initdb</application>
 	determines that an error prevented it from completely creating the database
-	system, it removes any files it may have created before determining
-	that it can't finish the job. This option inhibits any tidying-up and is
+	system, 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>
@@ -211,7 +193,7 @@ Postgres documentation
         messages of lesser interest for the general public.
 	The bootstrap backend is the program <application>initdb</application>
 	uses to create the catalog tables.  This option generates a tremendous
-	amount of output.
+	amount of extremely boring output.
        </para>
       </listitem>
      </varlistentry>

src/bin/initdb/initdb.sh

@@ -15,16 +15,14 @@
 # changed to add site-local standard data.  Either one can be copied
 # to produce a new database.
 #
-# Optionally, we can skip creating the complete database cluster and
-# just create (or replace) the template databases.
-#
-# To create all those things, we run the postgres (backend) program and
-# feed it data from the bki files that were installed.
+# To create template1, we run the postgres (backend) program and
+# feed it data from the bki files that were installed.  template0 is
+# made just by copying the completed template1.
 #
 #
 # Copyright (c) 1994, Regents of the University of California
 #
-# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.119 2001/01/04 17:25:09 petere Exp $
+# $Header: /cvsroot/pgsql/src/bin/initdb/Attic/initdb.sh,v 1.120 2001/01/20 22:09:24 tgl Exp $
 #
 #-------------------------------------------------------------------------
 
@@ -38,7 +36,7 @@ exit_nicely(){
     echo 1>&2
     echo "$CMDNAME failed." 1>&2
     if [ "$noclean" != yes ]; then
-        if [ "$template_only" != yes ] && [ "$made_new_pgdata" = yes ]; then
+        if [ "$made_new_pgdata" = yes ]; then
             echo "Removing $PGDATA." 1>&2
             rm -rf "$PGDATA" || echo "Failed." 1>&2
         fi
@@ -169,7 +167,6 @@ MULTIBYTEID=0
 # Set defaults:
 debug=
 noclean=
-template_only=
 show_setting=
 
 # Note: There is a single compelling reason that the name of the database
@@ -202,10 +199,6 @@ do
                 noclean=yes
                 echo "Running with noclean mode on. Mistakes will not be cleaned up."
                 ;;
-        --template|-t)
-                template_only=yes
-                echo "Updating template0 and template1 databases only."
-                ;;
 # The sysid of the database superuser. Can be freely changed.
         --sysid|-i)
                 POSTGRES_SUPERUSERID="$2"
@@ -232,7 +225,7 @@ do
         -D*)
                 PGDATA=`echo $1 | sed 's/^-D//'`
                 ;;
-# The directory where the database templates are stored. Normally
+# The directory where the .bki input files are stored. Normally
 # they are in PREFIX/share and this option should be unnecessary.
         -L)
                 datadir="$2"
@@ -278,7 +271,6 @@ if [ "$usage" ]; then
     echo "  -i, --sysid SYSID           Database sysid for the superuser"
     echo "Less commonly used options: "
     echo "  -L DIRECTORY                Where to find the input files"
-    echo "  -t, --template              Re-initialize template databases only"
     echo "  -d, --debug                 Generate lots of debugging output"
     echo "  -n, --noclean               Do not clean up after errors"
     echo
@@ -400,16 +392,13 @@ umask 077
 pgdata_contents=`ls -A "$PGDATA" 2>/dev/null`
 if [ x"$pgdata_contents" != x ]
 then
-    if [ "$template_only" != yes ]
-    then
-      (
-        echo "$CMDNAME: The directory $PGDATA exists but is not empty."
-        echo "If you want to create a new database system, either remove or empty"
-        echo "the directory $PGDATA or run initdb with an argument"
-        echo "other than $PGDATA."
-      ) 1>&2
-        exit 1
-    fi
+    (
+      echo "$CMDNAME: The directory $PGDATA exists but is not empty."
+      echo "If you want to create a new database system, either remove or empty"
+      echo "the directory $PGDATA or run initdb with"
+      echo "an argument other than $PGDATA."
+    ) 1>&2
+    exit 1
 else
     if [ ! -d "$PGDATA" ]; then
         echo "Creating directory $PGDATA"
@@ -470,31 +459,25 @@ echo $short_version > "$PGDATA"/base/1/PG_VERSION || exit_nicely
 #
 # CREATE GLOBAL TABLES
 #
-# XXX --- I do not believe the "template_only" option can actually work.
-# With this coding, it'll fail to make entries for pg_shadow etc. in
-# template1 ... tgl 11/2000
 
-if [ "$template_only" != yes ]
-then
-    echo "Creating global relations in $PGDATA/global"
-    [ "$debug" = yes ] && echo "Running: $PGPATH/postgres $BACKENDARGS template1"
-
-    cat "$GLOBAL_BKI" \
-    | sed -e "s/POSTGRES/$POSTGRES_SUPERUSERNAME/g" \
-          -e "s/PGUID/$POSTGRES_SUPERUSERID/g" \
-          -e "s/ENCODING/$MULTIBYTEID/g" \
-    | "$PGPATH"/postgres $BACKENDARGS template1 \
-    || exit_nicely
-
-    echo $short_version > "$PGDATA/PG_VERSION" || exit_nicely
-
-    cp "$PG_HBA_SAMPLE" "$PGDATA"/pg_hba.conf              || exit_nicely
-    cp "$PG_IDENT_SAMPLE" "$PGDATA"/pg_ident.conf          || exit_nicely
-    cp "$POSTGRESQL_CONF_SAMPLE" "$PGDATA"/postgresql.conf || exit_nicely
-    chmod 0600 "$PGDATA"/pg_hba.conf "$PGDATA"/pg_ident.conf \
-	"$PGDATA"/postgresql.conf
+echo "Creating global relations in $PGDATA/global"
 
-fi
+[ "$debug" = yes ] && echo "Running: $PGPATH/postgres $BACKENDARGS template1"
+
+cat "$GLOBAL_BKI" \
+| sed -e "s/POSTGRES/$POSTGRES_SUPERUSERNAME/g" \
+      -e "s/PGUID/$POSTGRES_SUPERUSERID/g" \
+      -e "s/ENCODING/$MULTIBYTEID/g" \
+| "$PGPATH"/postgres $BACKENDARGS template1 \
+|| exit_nicely
+
+echo $short_version > "$PGDATA/PG_VERSION" || exit_nicely
+
+cp "$PG_HBA_SAMPLE" "$PGDATA"/pg_hba.conf              || exit_nicely
+cp "$PG_IDENT_SAMPLE" "$PGDATA"/pg_ident.conf          || exit_nicely
+cp "$POSTGRESQL_CONF_SAMPLE" "$PGDATA"/postgresql.conf || exit_nicely
+chmod 0600 "$PGDATA"/pg_hba.conf "$PGDATA"/pg_ident.conf \
+	"$PGDATA"/postgresql.conf
 
 
 ##########################################################################