begriffs open source - ai-pg/blob - full-docs/man7/CREATE_TABLESPACE.7

   1 '\" t
   2 .\"     Title: CREATE TABLESPACE
   3 .\"    Author: The PostgreSQL Global Development Group
   4 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   5 .\"      Date: 2025
   6 .\"    Manual: PostgreSQL 18.0 Documentation
   7 .\"    Source: PostgreSQL 18.0
   8 .\"  Language: English
   9 .\"
  10 .TH "CREATE TABLESPACE" "7" "2025" "PostgreSQL 18.0" "PostgreSQL 18.0 Documentation"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 CREATE_TABLESPACE \- define a new tablespace
  32 .SH "SYNOPSIS"
  33 .sp
  34 .nf
  35 CREATE TABLESPACE \fItablespace_name\fR
  36     [ OWNER { \fInew_owner\fR | CURRENT_ROLE | CURRENT_USER | SESSION_USER } ]
  37     LOCATION \*(Aq\fIdirectory\fR\*(Aq
  38     [ WITH ( \fItablespace_option\fR = \fIvalue\fR [, \&.\&.\&. ] ) ]
  39 .fi
  40 .SH "DESCRIPTION"
  41 .PP
  42 \fBCREATE TABLESPACE\fR
  43 registers a new cluster\-wide tablespace\&. The tablespace name must be distinct from the name of any existing tablespace in the database cluster\&.
  44 .PP
  45 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\&.
  46 .PP
  47 A user with appropriate privileges can pass
  48 \fItablespace_name\fR
  49 to
  50 \fBCREATE DATABASE\fR,
  51 \fBCREATE TABLE\fR,
  52 \fBCREATE INDEX\fR
  53 or
  54 \fBADD CONSTRAINT\fR
  55 to have the data files for these objects stored within the specified tablespace\&.
  56 .if n \{\
  57 .sp
  58 .\}
  59 .RS 4
  60 .it 1 an-trap
  61 .nr an-no-space-flag 1
  62 .nr an-break-flag 1
  63 .br
  64 .ps +1
  65 \fBWarning\fR
  66 .ps -1
  67 .br
  68 .PP
  69 A tablespace cannot be used independently of the cluster in which it is defined; see
  70 Section\ \&22.6\&.
  71 .sp .5v
  72 .RE
  73 .SH "PARAMETERS"
  74 .PP
  75 \fItablespace_name\fR
  76 .RS 4
  77 The name of a tablespace to be created\&. The name cannot begin with
  78 pg_, as such names are reserved for system tablespaces\&.
  79 .RE
  80 .PP
  81 \fIuser_name\fR
  82 .RS 4
  83 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\&.
  84 .RE
  85 .PP
  86 \fIdirectory\fR
  87 .RS 4
  88 The directory that will be used for the tablespace\&. The directory must exist (\fBCREATE TABLESPACE\fR
  89 will not create it), should be empty, and must be owned by the
  90 PostgreSQL
  91 system user\&. The directory must be specified by an absolute path name\&.
  92 .RE
  93 .PP
  94 \fItablespace_option\fR
  95 .RS 4
  96 A tablespace parameter to be set or reset\&. Currently, the only available parameters are
  97 \fIseq_page_cost\fR,
  98 \fIrandom_page_cost\fR,
  99 \fIeffective_io_concurrency\fR
 100 and
 101 \fImaintenance_io_concurrency\fR\&. Setting these values for a particular tablespace will override the planner\*(Aqs usual estimate of the cost of reading pages from tables in that tablespace, and how many concurrent I/Os are issued, as established by the configuration parameters of the same name (see
 102 seq_page_cost,
 103 random_page_cost,
 104 effective_io_concurrency,
 105 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\&.
 106 .RE
 107 .SH "NOTES"
 108 .PP
 109 \fBCREATE TABLESPACE\fR
 110 cannot be executed inside a transaction block\&.
 111 .SH "EXAMPLES"
 112 .PP
 113 To create a tablespace
 114 dbspace
 115 at file system location
 116 /data/dbs, first create the directory using operating system facilities and set the correct ownership:
 117 .sp
 118 .if n \{\
 119 .RS 4
 120 .\}
 121 .nf
 122 mkdir /data/dbs
 123 chown postgres:postgres /data/dbs
 124 .fi
 125 .if n \{\
 126 .RE
 127 .\}
 128 .sp
 129 Then issue the tablespace creation command inside
 130 PostgreSQL:
 131 .sp
 132 .if n \{\
 133 .RS 4
 134 .\}
 135 .nf
 136 CREATE TABLESPACE dbspace LOCATION \*(Aq/data/dbs\*(Aq;
 137 .fi
 138 .if n \{\
 139 .RE
 140 .\}
 141 .PP
 142 To create a tablespace owned by a different database user, use a command like this:
 143 .sp
 144 .if n \{\
 145 .RS 4
 146 .\}
 147 .nf
 148 CREATE TABLESPACE indexspace OWNER genevieve LOCATION \*(Aq/data/indexes\*(Aq;
 149 .fi
 150 .if n \{\
 151 .RE
 152 .\}
 153 .SH "COMPATIBILITY"
 154 .PP
 155 \fBCREATE TABLESPACE\fR
 156 is a
 157 PostgreSQL
 158 extension\&.
 159 .SH "SEE ALSO"
 160 CREATE DATABASE (\fBCREATE_DATABASE\fR(7)), CREATE TABLE (\fBCREATE_TABLE\fR(7)), CREATE INDEX (\fBCREATE_INDEX\fR(7)), DROP TABLESPACE (\fBDROP_TABLESPACE\fR(7)), ALTER TABLESPACE (\fBALTER_TABLESPACE\fR(7))