doc: Clarify CREATE TABLESPACE documentation

Be more specific about when and how to create the directory and what
permissions it should have.

Discussion: https://www.postgresql.org/message-id/flat/5ca60e1a-26f9-89fd-e912-021dd2b8afe2%40gmail.com

diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml
index 18fa5f0ebf08af4b12fe7dde31048c196e2fcd13..c621ec2c6bf802e90bf7c6c4df8d8facf10abe5f 100644 (file)
--- a/doc/src/sgml/ref/create_tablespace.sgml
+++ b/doc/src/sgml/ref/create_tablespace.sgml
@@ -92,7 +92,8 @@ CREATE TABLESPACE tablespace_name
       
        
         The directory that will be used for the tablespace. The directory
-        should be empty and must be owned by the
+        must exist (CREATE TABLESPACE will not create it),
+        should be empty, and must be owned by the
         PostgreSQL system user.  The directory must be
         specified by an absolute path name.
        
@@ -137,15 +138,23 @@ CREATE TABLESPACE tablespace_name
   Examples
 
   
-   Create a tablespace dbspace at /data/dbs:
+   To create a tablespace dbspace at file system location
+   /data/dbs, first create the directory using operating
+   system facilities and set the correct ownership:
+
+mkdir /data/dbs
+chown postgres:postgres /data/dbs
+
+   Then issue the tablespace creation command inside
+   PostgreSQL:
 
 CREATE TABLESPACE dbspace LOCATION '/data/dbs';
 
   
 
   
-   Create a tablespace indexspace at /data/indexes
-   owned by user genevieve:
+   To create a tablespace owned by a different database user, use a command
+   like this:
 
 CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes';