diff --git a/doc/src/sgml/diskusage.sgml b/doc/src/sgml/diskusage.sgml
index 344141210fc38393d01c372cbaf375f8bbc71158..ce09f7bc9788b19563633f534c7f15ffe80d1ad6 100644
--- a/doc/src/sgml/diskusage.sgml
+++ b/doc/src/sgml/diskusage.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.10 2003/11/29 19:51:36 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/diskusage.sgml,v 1.11 2004/06/21 04:06:03 tgl Exp $
-->
<chapter id="diskusage">
@@ -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 34737ffd4fe9cdf9f8a61b4572665d6da0a77235..030620d91ec370c3073de5dbe4d85ea804b9642f 100644
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.30 2004/06/18 06:13:02 tgl Exp $
+$PostgreSQL: pgsql/doc/src/sgml/manage-ag.sgml,v 2.31 2004/06/21 04:06:03 tgl Exp $
-->
<chapter id="managing-databases">
@@ -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 4d6145488cefb670c806855a4e521b673af81280..96bacf054af0f252632d97ac1805af3ae9d64d63 100644
--- a/doc/src/sgml/ref/postmaster.sgml
+++ b/doc/src/sgml/ref/postmaster.sgml
@@ -1,5 +1,5 @@
<!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.49 2004/03/23 06:09:00 neilc Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/postmaster.sgml,v 1.50 2004/06/21 04:06:04 tgl Exp $
PostgreSQL documentation
-->
@@ -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 9ca8b135b4ccc33e0b9e9e0da5f4b43efb8362c4..2305d10db32673fb052773785d3c5322da1cbfb0 100644
--- a/src/backend/catalog/catalog.c
+++ b/src/backend/catalog/catalog.c
@@ -9,7 +9,7 @@
*
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/backend/catalog/catalog.c,v 1.53 2004/06/21 01:04:41 momjian Exp $
+ * $PostgreSQL: pgsql/src/backend/catalog/catalog.c,v 1.54 2004/06/21 04:06:05 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@@ -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 d00c01ce17a54c56e117a32b53c94865456d4504..61e36d5b5c2deaf3483022fc4d0e817c69da4abf 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
@@ -45,7 +45,7 @@
*
*
* IDENTIFICATION
- * $PostgreSQL: pgsql/src/backend/commands/tablespace.c,v 1.2 2004/06/21 01:04:42 momjian Exp $
+ * $PostgreSQL: pgsql/src/backend/commands/tablespace.c,v 1.3 2004/06/21 04:06:06 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@@ -233,6 +233,17 @@ CreateTableSpace(CreateTableSpaceStmt *stmt)
errmsg("tablespace location \"%s\" is too long",
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
diff --git a/src/include/catalog/catversion.h b/src/include/catalog/catversion.h
index fc4ed22ba4a3068598e0c4a66dfbb1518c40900d..8bb47ad78c733e9076d20acf112f725739ba0dc9 100644
--- a/src/include/catalog/catversion.h
+++ b/src/include/catalog/catversion.h
@@ -37,7 +37,7 @@
* Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.238 2004/06/21 01:04:45 momjian Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/catversion.h,v 1.239 2004/06/21 04:06:07 tgl Exp $
*
*-------------------------------------------------------------------------
*/
@@ -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 f05d3657704dcf0ef50516b383fc1e39306dceed..1378d9987b7e478a3cac48c842072d7acd057501 100644
--- a/src/include/catalog/pg_tablespace.h
+++ b/src/include/catalog/pg_tablespace.h
@@ -8,7 +8,7 @@
* Portions Copyright (c) 1996-2003, PostgreSQL Global Development Group
* Portions Copyright (c) 1994, Regents of the University of California
*
- * $PostgreSQL: pgsql/src/include/catalog/pg_tablespace.h,v 1.1 2004/06/18 06:14:06 tgl Exp $
+ * $PostgreSQL: pgsql/src/include/catalog/pg_tablespace.h,v 1.2 2004/06/21 04:06:07 tgl Exp $
*
* NOTES
* the genbki.sh script reads this file and generates .bki
@@ -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