Rethink the locking mechanisms used for CREATE/DROP/RENAME DATABASE.

The former approach used ExclusiveLock on pg_database, which being a
cluster-wide lock meant only one of these operations could proceed at
a time; worse, it also blocked all incoming connections in ReverifyMyDatabase.
Now that we have LockSharedObject(), we can use locks of different types
applied to databases considered as objects.  This allows much more
flexible management of the interlocking: two CREATE DATABASEs need not
block each other, and need not block connections except to the template
database being used.  Similarly DROP DATABASE doesn't block unrelated
operations.  The locking used in flatfiles.c is also much narrower in
scope than before.  Per recent proposal.

doc/src/sgml/manage-ag.sgml

@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.45 2006/03/10 19:10:48 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.46 2006/05/04 16:07:28 tgl Exp $ -->
 
 <chapter id="managing-databases">
  <title>Managing Databases</title>
@@ -166,6 +166,7 @@ CREATE DATABASE <replaceable>dbname</> OWNER <replaceable>rolename</>;
 <programlisting>
 createdb -O <replaceable>rolename</> <replaceable>dbname</>
 </programlisting>
+   from the shell.
    You must be a superuser to be allowed to create a database for
    someone else (that is, for a role you are not a member of).
   </para>
@@ -220,19 +221,15 @@ createdb -T template0 <replaceable>dbname</>
 
   <para>
    It is possible to create additional template databases, and indeed
-   one might copy any database in a cluster by specifying its name
+   one may copy any database in a cluster by specifying its name
    as the template for <command>CREATE DATABASE</>.  It is important to
    understand, however, that this is not (yet) intended as
-   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.  In particular, it is
-   essential that the source database be idle (no data-altering transactions
-   in progress)
-   for the duration of the copying operation.  <command>CREATE DATABASE</>
-   will check
-   that no session (other than itself) is connected to
-   the source database at the start of the operation, but this does not
-   guarantee that changes cannot be made while the copy proceeds, which
-   would result in an inconsistent copied database.  Therefore,
-   we recommend that databases used as templates be treated as read-only.
+   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
+   The principal limitation is that no other sessions can be connected to
+   the source database while it is being copied.  <command>CREATE
+   DATABASE</> will fail if any other connection exists when it starts;
+   otherwise, new connections to the source database are locked out
+   until <command>CREATE DATABASE</> completes.
   </para>
 
   <para>

doc/src/sgml/ref/create_database.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.44 2005/07/31 17:19:17 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.45 2006/05/04 16:07:29 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -45,7 +45,7 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
 
   <para>
    Normally, the creator becomes the owner of the new database.
-   Superusers can create databases owned by other users using the
+   Superusers can create databases owned by other users, by using the
    <literal>OWNER</> clause. They can even create databases owned by
    users with no special privileges. Non-superusers with <literal>CREATEDB</>
    privilege can only create databases owned by themselves.
@@ -104,7 +104,8 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
         Character set encoding to use in the new database.  Specify
         a string constant (e.g., <literal>'SQL_ASCII'</literal>),
         or an integer encoding number, or <literal>DEFAULT</literal>
-        to use the default encoding. The character sets supported by the
+        to use the default encoding (namely, the encoding of the
+        template database). The character sets supported by the
         <productname>PostgreSQL</productname> server are described in
         <xref linkend="multibyte-charset-supported">.
        </para>
@@ -169,7 +170,11 @@ CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
    Although it is possible to copy a database other than <literal>template1</>
    by specifying its name as the template, this is not (yet) intended as
    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
-   We recommend that databases used as templates be treated as read-only.
+   The principal limitation is that no other sessions can be connected to
+   the template database while it is being copied.  <command>CREATE
+   DATABASE</> will fail if any other connection exists when it starts;
+   otherwise, new connections to the template database are locked out
+   until <command>CREATE DATABASE</> completes.
    See <xref linkend="manage-ag-templatedbs"> for more information.
   </para>
 
@@ -220,6 +225,16 @@ CREATE DATABASE music ENCODING 'LATIN1';
    implementation-defined.
   </para>
  </refsect1>
+
+ <refsect1>
+  <title>See Also</title>
+
+  <simplelist type="inline">
+   <member><xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title"></member>
+   <member><xref linkend="sql-dropdatabase" endterm="sql-dropdatabase-title"></member>
+  </simplelist>
+ </refsect1>
+
 </refentry>
 
 <!-- Keep this comment at the end of the file

doc/src/sgml/ref/drop_database.sgml

@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.21 2005/11/22 15:24:17 adunstan Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/drop_database.sgml,v 1.22 2006/05/04 16:07:29 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -86,7 +86,7 @@ DROP DATABASE [ IF EXISTS ] <replaceable class="PARAMETER">name</replaceable>
   <title>Compatibility</title>
 
   <para>
-   The is no <command>DROP DATABASE</command> statement in the SQL standard.
+   There is no <command>DROP DATABASE</command> statement in the SQL standard.
   </para>
  </refsect1>