granicus.if.org Git - postgresql/blob - doc/src/sgml/ref/create_database.sgml

   1 <!--
   2 doc/src/sgml/ref/create_database.sgml
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEDATABASE">
   7  <indexterm zone="sql-createdatabase">
   8   <primary>CREATE DATABASE</primary>
   9  </indexterm>
  10
  11  <refmeta>
  12   <refentrytitle>CREATE DATABASE</refentrytitle>
  13   <manvolnum>7</manvolnum>
  14   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  15  </refmeta>
  16
  17  <refnamediv>
  18   <refname>CREATE DATABASE</refname>
  19   <refpurpose>create a new database</refpurpose>
  20  </refnamediv>
  21
  22  <refsynopsisdiv>
  23 <synopsis>
  24 CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
  25     [ [ WITH ] [ OWNER [=] <replaceable class="parameter">user_name</replaceable> ]
  26            [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
  27            [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
  28            [ LC_COLLATE [=] <replaceable class="parameter">lc_collate</replaceable> ]
  29            [ LC_CTYPE [=] <replaceable class="parameter">lc_ctype</replaceable> ]
  30            [ TABLESPACE [=] <replaceable class="parameter">tablespace_name</replaceable> ]
  31            [ IS_TEMPLATE [=] <replaceable class="parameter">istemplate</replaceable> ]
  32            [ ALLOW_CONNECTIONS [=] <replaceable class="parameter">allowconn</replaceable> ]
  33            [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ] ]
  34 </synopsis>
  35  </refsynopsisdiv>
  36
  37  <refsect1>
  38   <title>Description</title>
  39
  40   <para>
  41    <command>CREATE DATABASE</command> creates a new
  42    <productname>PostgreSQL</productname> database.
  43   </para>
  44
  45   <para>
  46    To create a database, you must be a superuser or have the special
  47    <literal>CREATEDB</> privilege.
  48    See <xref linkend="SQL-CREATEUSER">.
  49   </para>
  50
  51   <para>
  52    By default, the new database will be created by cloning the standard
  53    system database <literal>template1</>.  A different template can be
  54    specified by writing <literal>TEMPLATE
  55    <replaceable class="parameter">name</replaceable></literal>.  In particular,
  56    by writing <literal>TEMPLATE template0</>, you can create a virgin
  57    database containing only the standard objects predefined by your
  58    version of <productname>PostgreSQL</productname>.  This is useful
  59    if you wish to avoid copying
  60    any installation-local objects that might have been added to
  61    <literal>template1</>.
  62   </para>
  63  </refsect1>
  64
  65  <refsect1>
  66   <title>Parameters</title>
  67
  68     <variablelist>
  69      <varlistentry>
  70       <term><replaceable class="parameter">name</replaceable></term>
  71       <listitem>
  72        <para>
  73         The name of a database to create.
  74        </para>
  75       </listitem>
  76      </varlistentry>
  77      <varlistentry>
  78       <term><replaceable class="parameter">user_name</replaceable></term>
  79       <listitem>
  80        <para>
  81         The role name of the user who will own the new database,
  82         or <literal>DEFAULT</literal> to use the default (namely, the
  83         user executing the command).  To create a database owned by another
  84         role, you must be a direct or indirect member of that role,
  85         or be a superuser.
  86        </para>
  87       </listitem>
  88      </varlistentry>
  89      <varlistentry>
  90       <term><replaceable class="parameter">template</replaceable></term>
  91       <listitem>
  92        <para>
  93         The name of the template from which to create the new database,
  94         or <literal>DEFAULT</literal> to use the default template
  95         (<literal>template1</literal>).
  96        </para>
  97       </listitem>
  98      </varlistentry>
  99      <varlistentry>
 100       <term><replaceable class="parameter">encoding</replaceable></term>
 101       <listitem>
 102        <para>
 103         Character set encoding to use in the new database.  Specify
 104         a string constant (e.g., <literal>'SQL_ASCII'</literal>),
 105         or an integer encoding number, or <literal>DEFAULT</literal>
 106         to use the default encoding (namely, the encoding of the
 107         template database). The character sets supported by the
 108         <productname>PostgreSQL</productname> server are described in
 109         <xref linkend="multibyte-charset-supported">. See below for
 110         additional restrictions.
 111        </para>
 112       </listitem>
 113      </varlistentry>
 114      <varlistentry>
 115       <term><replaceable class="parameter">lc_collate</replaceable></term>
 116       <listitem>
 117        <para>
 118         Collation order (<literal>LC_COLLATE</>) to use in the new database.
 119         This affects the sort order applied to strings, e.g. in queries with
 120         ORDER BY, as well as the order used in indexes on text columns.
 121         The default is to use the collation order of the template database.
 122         See below for additional restrictions.
 123        </para>
 124       </listitem>
 125      </varlistentry>
 126      <varlistentry>
 127       <term><replaceable class="parameter">lc_ctype</replaceable></term>
 128       <listitem>
 129        <para>
 130         Character classification (<literal>LC_CTYPE</>) to use in the new
 131         database. This affects the categorization of characters, e.g. lower,
 132         upper and digit. The default is to use the character classification of
 133         the template database. See below for additional restrictions.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137      <varlistentry>
 138       <term><replaceable class="parameter">tablespace_name</replaceable></term>
 139       <listitem>
 140        <para>
 141         The name of the tablespace that will be associated with the
 142         new database, or <literal>DEFAULT</literal> to use the
 143         template database's tablespace. This
 144         tablespace will be the default tablespace used for objects
 145         created in this database. See
 146         <xref linkend="sql-createtablespace">
 147         for more information.
 148        </para>
 149       </listitem>
 150      </varlistentry>
 151
 152      <varlistentry>
 153        <term><replaceable class="parameter">istemplate</replaceable></term>
 154        <listitem>
 155         <para>
 156          If true, then this database can be cloned by any user with CREATEDB
 157          privileges; if false (the default), then only superusers or the owner
 158          of the database can clone it.
 159         </para>
 160        </listitem>
 161       </varlistentry>
 162
 163       <varlistentry>
 164        <term><replaceable class="parameter">allowconn</replaceable></term>
 165        <listitem>
 166         <para>
 167          If false then no one can connect to this database.  The default is
 168          true, allowing connections (except as restricted by other mechanisms,
 169          such as <literal>GRANT</>/<literal>REVOKE CONNECT</>).
 170         </para>
 171        </listitem>
 172       </varlistentry>
 173
 174       <varlistentry>
 175       <term><replaceable class="parameter">connlimit</replaceable></term>
 176       <listitem>
 177        <para>
 178         How many concurrent connections can be made
 179         to this database.  -1 (the default) means no limit.
 180        </para>
 181       </listitem>
 182      </varlistentry>
 183     </variablelist>
 184
 185   <para>
 186    Optional parameters can be written in any order, not only the order
 187    illustrated above.
 188   </para>
 189  </refsect1>
 190
 191  <refsect1>
 192   <title>Notes</title>
 193
 194    <para>
 195     <command>CREATE DATABASE</> cannot be executed inside a transaction
 196     block.
 197    </para>
 198
 199    <para>
 200     Errors along the line of <quote>could not initialize database directory</>
 201     are most likely related to insufficient permissions on the data
 202     directory, a full disk, or other file system problems.
 203    </para>
 204
 205    <para>
 206     Use <xref linkend="SQL-DROPDATABASE"> to remove a database.
 207    </para>
 208
 209    <para>
 210     The program <xref linkend="APP-CREATEDB"> is a
 211     wrapper program around this command, provided for convenience.
 212    </para>
 213
 214    <para>
 215     Database-level configuration parameters (set via <xref
 216     linkend="sql-alterdatabase">) are not copied from the template
 217     database.
 218    </para>
 219
 220   <para>
 221    Although it is possible to copy a database other than <literal>template1</>
 222    by specifying its name as the template, this is not (yet) intended as
 223    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
 224    The principal limitation is that no other sessions can be connected to
 225    the template database while it is being copied.  <command>CREATE
 226    DATABASE</> will fail if any other connection exists when it starts;
 227    otherwise, new connections to the template database are locked out
 228    until <command>CREATE DATABASE</> completes.
 229    See <xref linkend="manage-ag-templatedbs"> for more information.
 230   </para>
 231
 232   <para>
 233    The character set encoding specified for the new database must be
 234    compatible with the chosen locale settings (<literal>LC_COLLATE</> and
 235    <literal>LC_CTYPE</>).  If the locale is <literal>C</> (or equivalently
 236    <literal>POSIX</>), then all encodings are allowed, but for other
 237    locale settings there is only one encoding that will work properly.
 238    (On Windows, however, UTF-8 encoding can be used with any locale.)
 239    <command>CREATE DATABASE</> will allow superusers to specify
 240    <literal>SQL_ASCII</> encoding regardless of the locale settings,
 241    but this choice is deprecated and may result in misbehavior of
 242    character-string functions if data that is not encoding-compatible
 243    with the locale is stored in the database.
 244   </para>
 245
 246   <para>
 247    The encoding and locale settings must match those of the template database,
 248    except when <literal>template0</> is used as template.  This is because
 249    other databases might contain data that does not match the specified
 250    encoding, or might contain indexes whose sort ordering is affected by
 251    <literal>LC_COLLATE</> and <literal>LC_CTYPE</>.  Copying such data would
 252    result in a database that is corrupt according to the new settings.
 253    <literal>template0</literal>, however, is known to not contain any data or
 254    indexes that would be affected.
 255   </para>
 256
 257   <para>
 258    The <literal>CONNECTION LIMIT</> option is only enforced approximately;
 259    if two new sessions start at about the same time when just one
 260    connection <quote>slot</> remains for the database, it is possible that
 261    both will fail.  Also, the limit is not enforced against superusers.
 262   </para>
 263  </refsect1>
 264
 265  <refsect1>
 266   <title>Examples</title>
 267
 268   <para>
 269    To create a new database:
 270
 271 <programlisting>
 272 CREATE DATABASE lusiadas;
 273 </programlisting>
 274   </para>
 275
 276   <para>
 277    To create a database <literal>sales</> owned by user <literal>salesapp</>
 278    with a default tablespace of <literal>salesspace</>:
 279
 280 <programlisting>
 281 CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 282 </programlisting>
 283   </para>
 284
 285   <para>
 286    To create a database <literal>music</> which supports the ISO-8859-1
 287    character set:
 288
 289 <programlisting>
 290 CREATE DATABASE music ENCODING 'LATIN1' TEMPLATE template0;
 291 </programlisting>
 292
 293    In this example, the <literal>TEMPLATE template0</> clause would only
 294    be required if <literal>template1</>'s encoding is not ISO-8859-1.
 295    Note that changing encoding might require selecting new
 296    <literal>LC_COLLATE</> and <literal>LC_CTYPE</> settings as well.
 297   </para>
 298  </refsect1>
 299
 300  <refsect1>
 301   <title>Compatibility</title>
 302
 303   <para>
 304    There is no <command>CREATE DATABASE</command> statement in the SQL
 305    standard.  Databases are equivalent to catalogs, whose creation is
 306    implementation-defined.
 307   </para>
 308  </refsect1>
 309
 310  <refsect1>
 311   <title>See Also</title>
 312
 313   <simplelist type="inline">
 314    <member><xref linkend="sql-alterdatabase"></member>
 315    <member><xref linkend="sql-dropdatabase"></member>
 316   </simplelist>
 317  </refsect1>
 318
 319 </refentry>