doc/src/sgml/ref/create_tablespace.sgml

   1 <!--
   2 $PostgreSQL$
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATETABLESPACE">
   7  <refmeta>
   8   <refentrytitle id="sql-createtablespace-title">CREATE TABLESPACE</refentrytitle>
   9   <manvolnum>7</manvolnum>
  10   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  11  </refmeta>
  12
  13  <refnamediv>
  14   <refname>CREATE TABLESPACE</refname>
  15   <refpurpose>define a new tablespace</refpurpose>
  16  </refnamediv>
  17
  18  <indexterm zone="sql-createtablespace">
  19   <primary>CREATE TABLESPACE</primary>
  20  </indexterm>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE TABLESPACE <replaceable class="parameter">tablespacename</replaceable> [ OWNER <replaceable class="parameter">username</replaceable> ] LOCATION '<replaceable class="parameter">directory</replaceable>'
  25 </synopsis>
  26  </refsynopsisdiv>
  27
  28  <refsect1>
  29   <title>Description</title>
  30
  31   <para>
  32    <command>CREATE TABLESPACE</command> registers a new cluster-wide
  33    tablespace.  The tablespace name must be distinct from the name of any
  34    existing tablespace in the database cluster.
  35   </para>
  36
  37   <para>
  38    A tablespace allows superusers to define an alternative location on
  39    the file system where the data files containing database objects
  40    (such as tables and indexes) can reside.
  41   </para>
  42
  43   <para>
  44    A user with appropriate privileges can pass
  45    <replaceable class="parameter">tablespacename</> to
  46    <command>CREATE DATABASE</>, <command>CREATE TABLE</>,
  47    <command>CREATE INDEX</> or <command>ADD CONSTRAINT</> to have the data
  48    files for these objects stored within the specified tablespace.
  49   </para>
  50  </refsect1>
  51
  52  <refsect1>
  53   <title>Parameters</title>
  54
  55     <variablelist>
  56      <varlistentry>
  57       <term><replaceable class="parameter">tablespacename</replaceable></term>
  58       <listitem>
  59        <para>
  60         The name of a tablespace to be created.  The name cannot
  61         begin with <literal>pg_</literal>, as such names
  62         are reserved for system tablespaces.
  63        </para>
  64       </listitem>
  65      </varlistentry>
  66
  67      <varlistentry>
  68       <term><replaceable class="parameter">username</replaceable></term>
  69       <listitem>
  70        <para>
  71         The name of the user who will own the tablespace.  If omitted,
  72         defaults to the user executing the command.  Only superusers
  73         can create tablespaces, but they can assign ownership of tablespaces
  74         to non-superusers.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><replaceable class="parameter">directory</replaceable></term>
  81       <listitem>
  82        <para>
  83         The directory that will be used for the tablespace. The directory
  84         must be empty and must be owned by the
  85         <productname>PostgreSQL</> system user.  The directory must be
  86         specified by an absolute path name.
  87        </para>
  88       </listitem>
  89      </varlistentry>
  90   </variablelist>
  91  </refsect1>
  92
  93  <refsect1>
  94   <title>Notes</title>
  95
  96   <para>
  97    Tablespaces are only supported on systems that support symbolic links.
  98   </para>
  99
 100    <para>
 101     <command>CREATE TABLESPACE</> cannot be executed inside a transaction
 102     block.
 103    </para>
 104  </refsect1>
 105
 106  <refsect1>
 107   <title>Examples</title>
 108
 109   <para>
 110    Create a tablespace <literal>dbspace</> at <literal>/data/dbs</>:
 111 <programlisting>
 112 CREATE TABLESPACE dbspace LOCATION '/data/dbs';
 113 </programlisting>
 114   </para>
 115
 116   <para>
 117    Create a tablespace <literal>indexspace</> at <literal>/data/indexes</>
 118    owned by user <literal>genevieve</>:
 119 <programlisting>
 120 CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes';
 121 </programlisting>
 122   </para>
 123  </refsect1>
 124
 125  <refsect1>
 126   <title>Compatibility</title>
 127
 128   <para>
 129    <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</>
 130    extension.
 131   </para>
 132  </refsect1>
 133
 134  <refsect1>
 135   <title>See Also</title>
 136
 137   <simplelist type="inline">
 138    <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member>
 139    <member><xref linkend="sql-createtable" endterm="sql-createtable-title"></member>
 140    <member><xref linkend="sql-createindex" endterm="sql-createindex-title"></member>
 141    <member><xref linkend="sql-droptablespace" endterm="sql-droptablespace-title"></member>
 142    <member><xref linkend="sql-altertablespace" endterm="sql-altertablespace-title"></member>
 143   </simplelist>
 144  </refsect1>
 145
 146 </refentry>