From 4353d1809f6d10845be76dda1dad45013d0b14b8 Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Sat, 19 Apr 2014 10:52:49 -0400
Subject: [PATCH] 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
---
 doc/src/sgml/manage-ag.sgml             | 21 +++++++++++++++++++--
 doc/src/sgml/ref/create_tablespace.sgml |  8 ++++++++
 2 files changed, 27 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/manage-ag.sgml b/doc/src/sgml/manage-ag.sgml
index b44d521ba6..78ec509a8b 100644
--- 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 b643565057..cf6215ee60 100644
--- 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>