Cause initdb to create a third standard database "postgres", which

unlike template0 and template1 does not have any special status in
terms of backend functionality.  However, all external utilities such
as createuser and createdb now connect to "postgres" instead of
template1, and the documentation is changed to encourage people to use
"postgres" instead of template1 as a play area.  This should fix some
longstanding gotchas involving unexpected propagation of database
objects by createdb (when you used template1 without understanding
the implications), as well as ameliorating the problem that CREATE
DATABASE is unhappy if anyone else is connected to template1.
Patch by Dave Page, minor editing by Tom Lane.  All per recent
pghackers discussions.

Author: tglsfdc

contrib/dblink/doc/connection

@@ -28,13 +28,13 @@ Outputs
 
 Example usage
 
-select dblink_connect('dbname=template1');
+select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
 (1 row)
 
-select dblink_connect('myconn','dbname=template1');
+select dblink_connect('myconn','dbname=postgres');
  dblink_connect
 ----------------
  OK

contrib/dblink/doc/cursor

@@ -44,7 +44,7 @@ Note
 
 Example usage
 
-test=# select dblink_connect('dbname=template1');
+test=# select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
@@ -94,7 +94,7 @@ Outputs
 
 Example usage
 
-test=# select dblink_connect('dbname=template1');
+test=# select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
@@ -175,7 +175,7 @@ Note
 
 Example usage
 
-test=# select dblink_connect('dbname=template1');
+test=# select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK

contrib/dblink/doc/misc

@@ -17,10 +17,10 @@ Outputs
 
 Example usage
 
-test=# select dblink_current_query() from (select dblink('dbname=template1','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
+test=# select dblink_current_query() from (select dblink('dbname=postgres','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
                                                                 dblink_current_query
 -----------------------------------------------------------------------------------------------------------------------------------------------------
- select dblink_current_query() from (select dblink('dbname=template1','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
+ select dblink_current_query() from (select dblink('dbname=postgres','select oid, proname from pg_proc where proname = ''byteacat''') as f1) as t1;
 (1 row)
 
 ==================================================================

contrib/dblink/doc/query

@@ -37,7 +37,7 @@ Outputs
 
 Example usage
 
-select * from dblink('dbname=template1','select proname, prosrc from pg_proc')
+select * from dblink('dbname=postgres','select proname, prosrc from pg_proc')
  as t1(proname name, prosrc text) where proname like 'bytea%';
   proname   |   prosrc
 ------------+------------
@@ -55,7 +55,7 @@ select * from dblink('dbname=template1','select proname, prosrc from pg_proc')
  byteaout   | byteaout
 (12 rows)
 
-select dblink_connect('dbname=template1');
+select dblink_connect('dbname=postgres');
  dblink_connect
 ----------------
  OK
@@ -111,7 +111,7 @@ A more convenient way to use dblink may be to create a view:
 
  create view myremote_pg_proc as
  select *
- from dblink('dbname=template1','select proname, prosrc from pg_proc')
+ from dblink('dbname=postgres','select proname, prosrc from pg_proc')
  as t1(proname name, prosrc text);
 
 Then you can simply write:

contrib/oid2name/oid2name.c

@@ -518,7 +518,7 @@ main(int argc, char **argv)
 
 	if (my_opts->dbname == NULL)
 	{
-		my_opts->dbname = "template1";
+		my_opts->dbname = "postgres";
 		my_opts->nodb = true;
 	}
 	pgconn = sql_conn(my_opts);

contrib/reindexdb/reindexdb

@@ -1,6 +1,6 @@
 #!/bin/sh
 # -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- #
-# Package : reindexdb                 Version : $Revision: 1.5 $
+# Package : reindexdb                 Version : $Revision: 1.6 $
 # Date    : 05/08/2002                Author  : Shaun Thomas
 # Req     : psql, sh, perl, sed         Type  : Utility
 #
@@ -174,7 +174,7 @@ if [ "$alldb" ]; then
   # connect to.  That's the list we'll be using.  It's also why it's
   # a good idea for this to be run as a super-user.
   sql='SELECT datname FROM pg_database WHERE datallowconn'
-  dbname=`$PSQL $PSQLOPT -q -t -A -d template1 -c "$sql"`
+  dbname=`$PSQL $PSQLOPT -q -t -A -d postgres -c "$sql"`
 
 # Ok, if it's not all databases, make sure at least one database is
 # specified before continuing.

contrib/seg/README.seg

@@ -159,7 +159,7 @@ Any number	(rules 5,6) -- creates a zero-length segment (a point,
 		boundaries. For example, it adds an extra digit to the lower
 		boundary if the resulting interval includes a power of ten:
 
-		template1=> select '10(+-)1'::seg as seg;
+		postgres=> select '10(+-)1'::seg as seg;
 		      seg
 		---------
 		9.0 .. 11 -- should be: 9 .. 11

doc/src/sgml/backup.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.66 2005/06/20 13:52:17 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/backup.sgml,v 2.67 2005/06/21 04:02:29 tgl Exp $
 -->
 <chapter id="backup">
  <title>Backup and Restore</title>
@@ -177,11 +177,11 @@ pg_dumpall &gt; <replaceable>outfile</>
 </synopsis>
     The resulting dump can be restored with <application>psql</>:
 <synopsis>
-psql -f <replaceable class="parameter">infile</replaceable> template1
+psql -f <replaceable class="parameter">infile</replaceable> postgres
 </synopsis>
     (Actually, you can specify any existing database name to start from,
-    but if you are reloading in an empty cluster then <literal>template1</>
-    is the only available choice.)  It is always necessary to have
+    but if you are reloading in an empty cluster then <literal>postgres</>
+    should generally be used.)  It is always necessary to have
     database superuser access when restoring a <application>pg_dumpall</>
     dump, as that is required to restore the user and group information.
    </para>
@@ -1223,7 +1223,7 @@ restore_command = 'copy /mnt/server/archivedir/%f "%p"'  # Windows
    in parallel, on different ports. Then you can use something like
 
 <programlisting>
-pg_dumpall -p 5432 | psql -d template1 -p 6543
+pg_dumpall -p 5432 | psql -d postgres -p 6543
 </programlisting>
 
    to transfer your data.  Or use an intermediate file if you want.
@@ -1256,7 +1256,7 @@ cd ~/postgresql-&version;
 gmake install
 initdb -D /usr/local/pgsql/data
 postmaster -D /usr/local/pgsql/data
-psql -f backup template1
+psql -f backup postgres
 </programlisting>
 
    See <xref linkend="runtime"> about ways to start and stop the

doc/src/sgml/charset.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/charset.sgml,v 2.72 2005/04/16 16:50:01 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/charset.sgml,v 2.73 2005/06/21 04:02:29 tgl Exp $ -->
 
 <chapter id="charset">
  <title>Localization</>
@@ -647,6 +647,7 @@ $ <userinput>psql -l</userinput>
  euc_kr        | t-ishii | EUC_KR
  euc_tw        | t-ishii | EUC_TW
  mule_internal | t-ishii | MULE_INTERNAL
+ postgres      | t-ishii | EUC_JP
  regression    | t-ishii | SQL_ASCII
  template1     | t-ishii | EUC_JP
  test          | t-ishii | EUC_JP

doc/src/sgml/client-auth.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.80 2005/06/04 20:42:41 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/client-auth.sgml,v 1.81 2005/06/21 04:02:29 tgl Exp $
 -->
 
 <chapter id="client-authentication">
@@ -452,17 +452,17 @@ host    all         all         127.0.0.1/32          trust
 host    all         all         127.0.0.1     255.255.255.255     trust     
 
 # Allow any user from any host with IP address 192.168.93.x to connect
-# to database "template1" as the same user name that ident reports for
+# to database "postgres" as the same user name that ident reports for
 # the connection (typically the Unix user name).
 # 
 # TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
-host    template1   all         192.168.93.0/24       ident sameuser
+host    postgres   all         192.168.93.0/24       ident sameuser
 
 # Allow a user from host 192.168.12.10 to connect to database
-# "template1" if the user's password is correctly supplied.
+# "postgres" if the user's password is correctly supplied.
 # 
 # TYPE  DATABASE    USER        CIDR-ADDRESS          METHOD
-host    template1   all         192.168.12.10/32      md5
+host    postgres    all         192.168.12.10/32      md5
 
 # In the absence of preceding "host" lines, these two lines will
 # reject all connection from 192.168.54.1 (since that entry will be

doc/src/sgml/installation.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.235 2005/06/12 15:51:50 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/installation.sgml,v 1.236 2005/06/21 04:02:29 tgl Exp $ -->
 
 <chapter id="installation">
  <title><![%standalone-include[<productname>PostgreSQL</>]]>
@@ -468,7 +468,7 @@ su - postgres
 </programlisting>
    Finally, restore your data with
 <screen>
-<userinput>/usr/local/pgsql/bin/psql -d template1 -f <replaceable>outputfile</></userinput>
+<userinput>/usr/local/pgsql/bin/psql -d postgres -f <replaceable>outputfile</></userinput>
 </screen>
    using the <emphasis>new</> <application>psql</>.
   </para>

doc/src/sgml/libpq.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.185 2005/06/12 00:00:20 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/libpq.sgml,v 1.186 2005/06/21 04:02:29 tgl Exp $
 -->
 
  <chapter id="libpq">
@@ -4230,14 +4230,14 @@ main(int argc, char **argv)
 
         /*
          * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=template1
+         * the conninfo string; otherwise default to setting dbname=postgres
          * and using environment variables or defaults for all other connection
          * parameters.
          */
         if (argc &gt; 1)
                 conninfo = argv[1];
         else
-                conninfo = "dbname = template1";
+                conninfo = "dbname = postgres";
 
         /* Make a connection to the database */
         conn = PQconnectdb(conninfo);
@@ -4376,14 +4376,14 @@ main(int argc, char **argv)
 
         /*
          * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=template1
+         * the conninfo string; otherwise default to setting dbname=postgres
          * and using environment variables or defaults for all other connection
          * parameters.
          */
         if (argc &gt; 1)
                 conninfo = argv[1];
         else
-                conninfo = "dbname = template1";
+                conninfo = "dbname = postgres";
 
         /* Make a connection to the database */
         conn = PQconnectdb(conninfo);
@@ -4518,14 +4518,14 @@ main(int argc, char **argv)
 
         /*
          * If the user supplies a parameter on the command line, use it as
-         * the conninfo string; otherwise default to setting dbname=template1
+         * the conninfo string; otherwise default to setting dbname=postgres
          * and using environment variables or defaults for all other connection
          * parameters.
          */
         if (argc &gt; 1)
                 conninfo = argv[1];
         else
-                conninfo = "dbname = template1";
+                conninfo = "dbname = postgres";
 
         /* Make a connection to the database */
         conn = PQconnectdb(conninfo);

doc/src/sgml/manage-ag.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.41 2005/06/13 02:40:04 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.42 2005/06/21 04:02:30 tgl Exp $
 -->
 
 <chapter id="managing-databases">
@@ -113,17 +113,20 @@ CREATE DATABASE <replaceable>name</>;
    <command>initdb</> command when the data storage area is
    initialized. (See <xref linkend="creating-cluster">.)  This
    database is called
-   <literal>template1</>.<indexterm><primary>template1</></> So to
-   create the first <quote>real</> database you can connect to
-   <literal>template1</>.
+   <literal>postgres</>.<indexterm><primary>postgres</></> So to
+   create the first <quote>ordinary</> database you can connect to
+   <literal>postgres</>.
   </para>
 
   <para>
-   The name <literal>template1</literal> is no accident: when a new
-   database is created, the template database is essentially cloned.
+   A second database,
+   <literal>template1</literal>,<indexterm><primary>template1</></>
+   is also created by
+   <command>initdb</>.  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. This implies that
-   you should not use the template database for real work, but when
+   propagated to all subsequently created databases. Therefore it is
+   unwise to use <literal>template1</> for real work, but when
    used judiciously this feature can be convenient.  More details
    appear in <xref linkend="manage-ag-templatedbs">.
   </para>
@@ -137,7 +140,7 @@ CREATE DATABASE <replaceable>name</>;
 createdb <replaceable class="parameter">dbname</replaceable>
 </synopsis>
 
-   <command>createdb</> does no magic. It connects to the <literal>template1</>
+   <command>createdb</> does no magic. It connects to the <literal>postgres</>
    database and issues the <command>CREATE DATABASE</> command,
    exactly as described above.
    The <xref linkend="app-createdb"> reference page contains the invocation
@@ -268,13 +271,19 @@ createdb -T template0 <replaceable>dbname</>
    <para>
     <literal>template1</> and <literal>template0</> do not have any special
     status beyond the fact that the name <literal>template1</> is the default
-    source database name for <command>CREATE DATABASE</> and the default
-    database-to-connect-to for various programs such as <command>createdb</>.
+    source database name for <command>CREATE DATABASE</>.
     For example, one could drop <literal>template1</> and recreate it from
     <literal>template0</> without any ill effects.  This course of action
     might be advisable if one has carelessly added a bunch of junk in
     <literal>template1</>.
    </para>
+
+   <para>
+    The <literal>postgres</> database is also created when a database
+    cluster is initialized.  This database is meant as a default database for
+    users and applications to connect to. It is simply a copy of
+    <literal>template1</> and may be dropped and recreated if required.
+   </para>
   </note>
  </sect1>
 

doc/src/sgml/ref/createlang.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.34 2005/05/29 03:32:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createlang.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -223,6 +223,9 @@ PostgreSQL documentation
 <screen>
 <prompt>$ </prompt><userinput>createlang pltcl template1</userinput>
 </screen>
+    Note that installing the language into <literal>template1</literal>
+    will cause it to be automatically installed into subsequently-created
+    databases as well.
    </para>
  </refsect1>
 

doc/src/sgml/ref/drop_database.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.19 2003/11/29 19:51:38 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.20 2005/06/21 04:02:31 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -32,7 +32,7 @@ DROP DATABASE <replaceable class="PARAMETER">name</replaceable>
    catalog entries for the database and deletes the directory
    containing the data.  It can only be executed by the database owner.
    Also, it cannot be executed while you or anyone else are connected
-   to the target database.  (Connect to <literal>template1</literal> or any
+   to the target database.  (Connect to <literal>postgres</literal> or any
    other database to issue this command.) 
   </para>
 

doc/src/sgml/ref/initdb.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.34 2005/02/22 02:54:19 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/initdb.sgml,v 1.35 2005/06/21 04:02:31 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -47,9 +47,12 @@ PostgreSQL documentation
    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>
-   database. When you later create a new database, everything in the
-   <literal>template1</literal> database is copied. It contains catalog
-   tables containing things like built-in data types.
+   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.
   </para>
 
   <para>