diff options
Diffstat (limited to 'doc/src/sgml/ref/create_tablespace.sgml')
| -rw-r--r-- | doc/src/sgml/ref/create_tablespace.sgml | 187 |
1 files changed, 187 insertions, 0 deletions
diff --git a/doc/src/sgml/ref/create_tablespace.sgml b/doc/src/sgml/ref/create_tablespace.sgml new file mode 100644 index 0000000..84fa7ee --- /dev/null +++ b/doc/src/sgml/ref/create_tablespace.sgml @@ -0,0 +1,187 @@ +<!-- +doc/src/sgml/ref/create_tablespace.sgml +PostgreSQL documentation +--> + +<refentry id="sql-createtablespace"> + <indexterm zone="sql-createtablespace"> + <primary>CREATE TABLESPACE</primary> + </indexterm> + + <refmeta> + <refentrytitle>CREATE TABLESPACE</refentrytitle> + <manvolnum>7</manvolnum> + <refmiscinfo>SQL - Language Statements</refmiscinfo> + </refmeta> + + <refnamediv> + <refname>CREATE TABLESPACE</refname> + <refpurpose>define a new tablespace</refpurpose> + </refnamediv> + + <refsynopsisdiv> +<synopsis> +CREATE TABLESPACE <replaceable class="parameter">tablespace_name</replaceable> + [ OWNER { <replaceable>new_owner</replaceable> | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ] + LOCATION '<replaceable class="parameter">directory</replaceable>' + [ WITH ( <replaceable class="parameter">tablespace_option</replaceable> = <replaceable class="parameter">value</replaceable> [, ... ] ) ] +</synopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>CREATE TABLESPACE</command> registers a new cluster-wide + tablespace. The tablespace name must be distinct from the name of any + existing tablespace in the database cluster. + </para> + + <para> + A tablespace allows superusers to define an alternative location on + the file system where the data files containing database objects + (such as tables and indexes) can reside. + </para> + + <para> + A user with appropriate privileges can pass + <replaceable class="parameter">tablespace_name</replaceable> to + <command>CREATE DATABASE</command>, <command>CREATE TABLE</command>, + <command>CREATE INDEX</command> or <command>ADD CONSTRAINT</command> 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> + <title>Parameters</title> + + <variablelist> + <varlistentry> + <term><replaceable class="parameter">tablespace_name</replaceable></term> + <listitem> + <para> + The name of a tablespace to be created. The name cannot + begin with <literal>pg_</literal>, as such names + are reserved for system tablespaces. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">user_name</replaceable></term> + <listitem> + <para> + The name of the user who will own the tablespace. If omitted, + defaults to the user executing the command. Only superusers + can create tablespaces, but they can assign ownership of tablespaces + to non-superusers. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">directory</replaceable></term> + <listitem> + <para> + The directory that will be used for the tablespace. The directory + must exist (<command>CREATE TABLESPACE</command> will not create it), + should be empty, and must be owned by the + <productname>PostgreSQL</productname> system user. The directory must be + specified by an absolute path name. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable class="parameter">tablespace_option</replaceable></term> + <listitem> + <para> + A tablespace parameter to be set or reset. Currently, the only + available parameters are <varname>seq_page_cost</varname>, + <varname>random_page_cost</varname>, <varname>effective_io_concurrency</varname> + and <varname>maintenance_io_concurrency</varname>. + Setting these values for a particular tablespace will override the + planner's usual estimate of the cost of reading pages from tables in + that tablespace, and the executor's prefetching behavior, as established + by the configuration parameters of the + same name (see <xref linkend="guc-seq-page-cost"/>, + <xref linkend="guc-random-page-cost"/>, + <xref linkend="guc-effective-io-concurrency"/>, + <xref linkend="guc-maintenance-io-concurrency"/>). This may be useful if + one tablespace is located on a disk which is faster or slower than the + remainder of the I/O subsystem. + </para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Notes</title> + + <para> + Tablespaces are only supported on systems that support symbolic links. + </para> + + <para> + <command>CREATE TABLESPACE</command> cannot be executed inside a transaction + block. + </para> + </refsect1> + + <refsect1> + <title>Examples</title> + + <para> + To create a tablespace <literal>dbspace</literal> at file system location + <literal>/data/dbs</literal>, first create the directory using operating + system facilities and set the correct ownership: +<programlisting> +mkdir /data/dbs +chown postgres:postgres /data/dbs +</programlisting> + Then issue the tablespace creation command inside + <productname>PostgreSQL</productname>: +<programlisting> +CREATE TABLESPACE dbspace LOCATION '/data/dbs'; +</programlisting> + </para> + + <para> + To create a tablespace owned by a different database user, use a command + like this: +<programlisting> +CREATE TABLESPACE indexspace OWNER genevieve LOCATION '/data/indexes'; +</programlisting></para> + </refsect1> + + <refsect1> + <title>Compatibility</title> + + <para> + <command>CREATE TABLESPACE</command> is a <productname>PostgreSQL</productname> + extension. + </para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <simplelist type="inline"> + <member><xref linkend="sql-createdatabase"/></member> + <member><xref linkend="sql-createtable"/></member> + <member><xref linkend="sql-createindex"/></member> + <member><xref linkend="sql-droptablespace"/></member> + <member><xref linkend="sql-altertablespace"/></member> + </simplelist> + </refsect1> + +</refentry> |