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