Rename the built-in tablespaces to pg_default and pg_global, and prohibit

creation of user-defined tablespaces with names starting with 'pg_', as
per suggestion of Chris K-L.  Also install admin-guide tablespace
documentation from Gavin.

7 files changed, 133 insertions, 110 deletions

diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
index 484f15c894..c1561d37d5 100644
--- a/doc/src/sgml/diskusage.sgml
+++ b/doc/src/sgml/diskusage.sgml
@@ -124,20 +124,15 @@ SELECT relname, relpages FROM pg_class ORDER BY relpages DESC;
 
   <para>
    If you cannot free up additional space on the disk by deleting
-   other things you can move some of the database files to other file
-   systems and create a symlink from the original location.  But
-   note that <application>pg_dump</> cannot save the location layout
-   information of such a setup; a restore would put everything back in
-   one place.  To avoid running out of disk space, you can place the
-   WAL files or individual databases in other locations while creating
-   them.  See the <command>initdb</> documentation and <xref
-   linkend="manage-ag-alternate-locs"> for more information about that.
+   other things, you can move some of the database files to other file
+   systems by making use of tablespaces. See <xref
+   linkend="manage-ag-tablespaces"> for more information about that.
   </para>
 
   <tip>
    <para>
     Some file systems perform badly when they are almost full, so do
-    not wait until the disk is full to take action.
+    not wait until the disk is completely full to take action.
    </para>
   </tip>
  </sect1>
diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index 34fecb7fb6..23d0f4c1b1 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -295,86 +295,6 @@ ALTER DATABASE mydb SET geqo TO off;
   </para>
  </sect1>
 
- <sect1 id="manage-ag-alternate-locs">
-  <title>Alternative Locations</title>
-
-   <para>
-    XXX this is entirely dead now, and needs to be replaced by a DBA-level
-    description of tablespaces.
-   </para>
-
-   <para>
-    It is possible to create a database in a location other than the
-    default location for the installation. But remember that all database access
-    occurs through the 
-    database server, so any location specified must be
-    accessible by the server.
-   </para>
-
-   <para>
-    Alternative database locations are referenced by an environment
-    variable which gives the absolute path to the intended storage
-    location. This environment variable must be present in the server's
-    environment, so it must have been defined before the server
-    was started.  (Thus, the set of available alternative locations is
-    under the site administrator's control; ordinary users can't
-    change it.)  Any valid environment variable name may
-    be used to reference an alternative location, although using
-    variable names with a prefix of <literal>PGDATA</> is recommended
-    to avoid confusion and conflict with other variables.
-   </para>
-
-   <para>
-    To create the variable in the environment of the server process
-    you must first shut down the server, define the variable,
-    initialize the data area, and finally restart the server. (See also
-    <xref linkend="postmaster-shutdown"> and <xref
-    linkend="postmaster-start">.) To set an environment variable, type
-<programlisting>
-PGDATA2=/home/postgres/data
-export PGDATA2
-</programlisting>
-    in Bourne shells, or
-<programlisting>
-setenv PGDATA2 /home/postgres/data
-</programlisting>
-    in <command>csh</> or <command>tcsh</>. You have to make sure that this environment
-    variable is always defined in the server environment, otherwise
-    you won't be able to access that database. Therefore you probably
-    want to set it in some sort of shell start-up file or server
-    start-up script.
-   </para>
-
-   <para>
-    <indexterm><primary>initlocation</></>
-    To create a data storage area in <envar>PGDATA2</>, ensure that
-    the containing directory (here, <filename>/home/postgres</filename>)
-    already exists and is writable
-    by the user account that runs the server (see <xref
-    linkend="postgres-user">). Then from the command line, type
-<programlisting>
-initlocation PGDATA2
-</programlisting>
-    (<emphasis>not</emphasis> <literal>initlocation
-    $PGDATA2</literal>).  Then you can restart the server.
-   </para>
-
-   <para>
-    To create a database within the new location, use the command
-<synopsis>
-CREATE DATABASE <replaceable>name</> WITH LOCATION '<replaceable>location</>';
-</synopsis>
-    where <replaceable>location</> is the environment variable you
-    used, <envar>PGDATA2</> in this example. The <command>createdb</>
-    command has the option <option>-D</> for this purpose.
-   </para>
-
-   <para>
-    Databases created in alternative locations can be
-    accessed and dropped like any other database.
-   </para>
- </sect1>
-
  <sect1 id="manage-ag-dropdb">
   <title>Destroying a Database</title>
 
@@ -410,6 +330,116 @@ dropdb <replaceable class="parameter">dbname</replaceable>
    the database with the current user name.)
   </para>
  </sect1>
+
+ <sect1 id="manage-ag-tablespaces">
+  <title>Tablespaces</title>
+
+   <para>
+    Tablespaces in <productname>PostgreSQL</> allow database superusers to
+    define locations in the file system where the files representing
+    database objects can be stored. Once created, a tablespace can be referred
+    to by name when creating database objects.
+   </para>
+
+   <para>
+    By using tablespaces, a database administrator can control the disk
+    layout of a <productname>PostgreSQL</> installation. This is useful in
+    at least two ways. Firstly, if the partition or volume on which the cluster
+    was initialized runs out of space and cannot be extended logically
+    or otherwise, a tablespace can be created on a different partition
+    and used until the system can be reconfigured.
+   </para>
+
+   <para>
+    Secondly, tablespaces allow a database administrator to arrange data
+    locations based on the usage patterns of database objects. For
+    example, an index which is very heavily used can be placed on very fast,
+    highly available disk, such as an expensive solid state device. At the same
+    time a table storing archived data which is rarely used or not performance
+    critical could be stored on a less expensive, slower disk system.
+   </para>
+
+   <para>
+    Databases, schemas, tables, indexes and sequences can all be placed in
+    particular tablespaces. To do so, a user with the <literal>CREATE</>
+    privilege on a given tablespace must pass the tablespace name as a 
+    parameter to the relevant command. For example, the following creates 
+    a table in the tablespace <literal>space1</>:
+<programlisting>
+CREATE TABLE foo(i int) TABLESPACE space1;
+</programlisting>
+   </para>
+
+   <para>
+    The tablespace associated with a database is used to store the system
+    catalogs of that database, as well as any temporary files created by
+    server processes using that database.  Furthermore, it is the default
+    tablespace selected for any objects created within the database, if
+    no specific <literal>TABLESPACE</> clause is given when those objects
+    are created.  If a database is created without specifying a tablespace
+    for it, it uses the same tablespace as the template database it is copied
+    from.
+   </para>
+
+   <para>
+    A schema does not in itself occupy any storage (other than a system
+    catalog entry), so assigning a tablespace to a schema does not in itself
+    do anything.  What this actually does is to set a default tablespace
+    for tables, indexes, and sequences later created within the schema.  If
+    no tablespace is mentioned when creating a schema, it inherits its
+    default tablespace from the current database.
+   </para>
+
+   <para>
+    The default choice of tablespace for an index is the same tablespace
+    already assigned to the table the index is for.
+   </para>
+
+   <para>
+    Another way to state the above rules is that when a schema, table, index
+    or sequence is created without specifying a tablespace, the object
+    inherits its logical parent's tablespace. A schema will be created in the
+    current database's tablespace; a table or sequence will be created in the
+    tablespace of the schema it is being created in; an index will be created
+    in the tablespace of the table underlying the index.
+   </para>
+
+   <para>
+    Two tablespaces are automatically created by <literal>initdb</>. 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,
+    will be the default tablespace for everything else as well, unless
+    explicit <literal>TABLESPACE</> clauses are used somewhere along the
+    line).
+   </para>
+
+   <para>
+    Once created, a tablespace can be used from any database, provided
+    the requesting user has sufficient privilege. This means that a tablespace
+    cannot be dropped until all objects in all databases using the tablespace
+    have been removed.
+   </para>
+
+   <para>
+    To simplify the implementation of tablespaces, 
+    <productname>PostgreSQL</> makes extensive use of symbolic links. This
+    means that tablespaces can be used <emphasis>only</> on systems
+    that support symbolic links.
+   </para>
+
+   <para>
+    The directory <filename>$PGDATA/pg_tblspc</> contains symbolic links that
+    point to each of the non-built-in tablespaces defined in the cluster.
+    Although not recommended, it is possible to adjust the tablespace
+    layout by hand by redefining these links.  Two warnings: do not do so
+    while the postmaster is running; and after you restart the postmaster,
+    update the <structname>pg_tablespace</> catalog to show the new
+    locations.  (If you do not, <literal>pg_dump</> will continue to show
+    the old tablespace locations.)
+   </para> 
+
+ </sect1>
 </chapter>
 
 <!-- Keep this comment at the end of the file
diff --git a/doc/src/sgml/ref/postmaster.sgml b/doc/src/sgml/ref/postmaster.sgml
index f30a6a41f9..7de1c54b2d 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -417,18 +417,6 @@ PostgreSQL documentation
     </listitem>
    </varlistentry>
 
-   <varlistentry>
-    <term>others</term>
-
-    <listitem>
-     <para>
-      Other environment variables may be used to designate alternative
-      data storage locations.  See <xref linkend="manage-ag-alternate-locs"> for more
-      information.
-     </para>
-    </listitem>
-   </varlistentry>
-
   </variablelist>
  </refsect1>
 
diff --git a/src/backend/catalog/catalog.c b/src/backend/catalog/catalog.c
index 506e88ec85..326d99abc3 100644
--- a/src/backend/catalog/catalog.c
+++ b/src/backend/catalog/catalog.c
@@ -119,8 +119,7 @@ GetDatabasePath(Oid dbNode, Oid spcNode)
  *
  *		We now just test if the relation is in the system catalog namespace;
  *		so it's no longer necessary to forbid user relations from having
- *		names starting with pg_.  Now only schema names have the pg_
- *		distinction/requirement.
+ *		names starting with pg_.
  */
 bool
 IsSystemRelation(Relation relation)
@@ -200,8 +199,8 @@ IsToastNamespace(Oid namespaceId)
  *		True iff name starts with the pg_ prefix.
  *
  *		For some classes of objects, the prefix pg_ is reserved for
- *		system objects only. As of 7.3, this is now only true for
- *		schema names.
+ *		system objects only.  As of 7.5, this is only true for
+ *		schema and tablespace names.
  */
 bool
 IsReservedName(const char *name)
diff --git a/src/backend/commands/tablespace.c b/src/backend/commands/tablespace.c
index 383f368ca5..68cc129b39 100644
--- a/src/backend/commands/tablespace.c
+++ b/src/backend/commands/tablespace.c
@@ -19,8 +19,8 @@
  * Thus the full path to an arbitrary file is
  *			$PGDATA/pg_tblspc/spcoid/dboid/relfilenode
  *
- * There are two tablespaces created at initdb time: global (for shared
- * tables) and default (for everything else).  For backwards compatibility
+ * There are two tablespaces created at initdb time: pg_global (for shared
+ * tables) and pg_default (for everything else).  For backwards compatibility
  * and to remain functional on platforms without symlinks, these tablespaces
  * are accessed specially: they are respectively
  *			$PGDATA/global/relfilenode
@@ -234,6 +234,17 @@ CreateTableSpace(CreateTableSpaceStmt *stmt)
 						location)));
 
 	/*
+	 * Disallow creation of tablespaces named "pg_xxx"; we reserve this
+	 * namespace for system purposes.
+	 */
+	if (!allowSystemTableMods && IsReservedName(stmt->tablespacename))
+		ereport(ERROR,
+				(errcode(ERRCODE_RESERVED_NAME),
+				 errmsg("unacceptable tablespace name \"%s\"",
+						stmt->tablespacename),
+		errdetail("The prefix \"pg_\" is reserved for system tablespaces.")));
+
+	/*
 	 * Check that there is no other tablespace by this name.  (The
 	 * unique index would catch this anyway, but might as well give 
 	 * a friendlier message.)
diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index 7c248a5a4f..0abd0882b7 100644
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -53,6 +53,6 @@
  */
 
 /*							yyyymmddN */
-#define CATALOG_VERSION_NO	200406201
+#define CATALOG_VERSION_NO	200406202
 
 #endif
diff --git a/src/include/catalog/pg_tablespace.h b/src/include/catalog/pg_tablespace.h
index 6a3f128777..677aaf9fe2 100644
--- a/src/include/catalog/pg_tablespace.h
+++ b/src/include/catalog/pg_tablespace.h
@@ -57,8 +57,8 @@ typedef FormData_pg_tablespace *Form_pg_tablespace;
 #define Anum_pg_tablespace_spclocation	3
 #define Anum_pg_tablespace_spcacl		4
 
-DATA(insert OID = 1663 ( default	PGUID "" _null_ ));
-DATA(insert OID = 1664 ( global		PGUID "" _null_ ));
+DATA(insert OID = 1663 ( pg_default	PGUID "" _null_ ));
+DATA(insert OID = 1664 ( pg_global	PGUID "" _null_ ));
 
 #define DEFAULTTABLESPACE_OID 1663
 #define GLOBALTABLESPACE_OID 1664