docs: tablespaces cannot be accessed independently

Mention impossibility of moving tablespaces, backing them up
independently, or the inadvisability of placing them on temporary
file systems.

Patch by Craig Ringer, adjustments by Ian Lawrence Warwick and me

diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index b44d521ba69bc75170ae5599603719386ed3b4c8..78ec509a8b5875343a5596cf084c02130838f369 100644 (file)
--- a/doc/src/sgml/manage-ag.sgml
+++ b/doc/src/sgml/manage-ag.sgml
@@ -379,17 +379,34 @@ dropdb <replaceable class="parameter">dbname</replaceable>
    expensive, slower disk system.
   </para>
 
+  <warning>
+   <para>
+     Even though located outside the main PostgreSQL data directory,
+     tablespaces are an integral part of the database cluster and
+     <emphasis>cannot</emphasis> be treated as an autonomous collection
+     of data files. They are dependent on metadata contained in the main
+     data directory, and therefore cannot be attached to a different
+     database cluster or backed up individually.  Similarly, if you lose
+     a tablespace (file deletion, disk failure, etc), the database cluster
+     might become unreadable or unable to start.  Placing a tablespace
+     on a temporary file system like a ramdisk risks the reliability of
+     the entire cluster.
+   </para>
+  </warning>
+
   <para>
    To define a tablespace, use the <xref
    linkend="sql-createtablespace">
    command, for example:<indexterm><primary>CREATE TABLESPACE</></>:
 <programlisting>
-CREATE TABLESPACE fastspace LOCATION '/mnt/sda1/postgresql/data';
+CREATE TABLESPACE fastspace LOCATION '/ssd1/postgresql/data';
 </programlisting>
    The location must be an existing, empty directory that is owned by
    the <productname>PostgreSQL</> operating system user.  All objects subsequently
    created within the tablespace will be stored in files underneath this
-   directory.
+   directory.  The location must not be on removable or transient storage,
+   as the cluster might fail to function if the tablespace is missing
+   or lost.
   </para>
 
   <note>

diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml
index b6435650578be2c50b1543cc6572bc61b9164db7..cf6215ee6084cd69734bcca6a4fca52646073772 100644 (file)
--- a/doc/src/sgml/ref/create_tablespace.sgml
+++ b/doc/src/sgml/ref/create_tablespace.sgml
@@ -50,6 +50,14 @@ CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable>
    <command>CREATE INDEX</> or <command>ADD CONSTRAINT</> to have the data
    files for these objects stored within the specified tablespace.
   </para>
+
+  <warning>
+   <para>
+    A tablespace cannot be used independently of the cluster in which it
+    is defined;  see <xref linkend="manage-ag-tablespaces"/>.
+   </para>
+  </warning>
+
  </refsect1>
 
  <refsect1>