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

   1 <!--
   2 $PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.44 2005/07/31 17:19:17 tgl Exp $
   3 PostgreSQL documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEDATABASE">
   7  <refmeta>
   8   <refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
   9   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  10  </refmeta>
  11
  12  <refnamediv>
  13   <refname>CREATE DATABASE</refname>
  14   <refpurpose>create a new database</refpurpose>
  15  </refnamediv>
  16
  17  <indexterm zone="sql-createdatabase">
  18   <primary>CREATE DATABASE</primary>
  19  </indexterm>
  20
  21  <refsynopsisdiv>
  22 <synopsis>
  23 CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
  24     [ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
  25            [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
  26            [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
  27            [ TABLESPACE [=] <replaceable class="parameter">tablespace</replaceable> ]
  28            [ CONNECTION LIMIT [=] <replaceable class="parameter">connlimit</replaceable> ] ]
  29 </synopsis>
  30  </refsynopsisdiv>
  31
  32  <refsect1>
  33   <title>Description</title>
  34
  35   <para>
  36    <command>CREATE DATABASE</command> creates a new
  37    <productname>PostgreSQL</productname> database.
  38   </para>
  39
  40   <para>
  41    To create a database, you must be a superuser or have the special
  42    <literal>CREATEDB</> privilege.
  43    See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
  44   </para>
  45
  46   <para>
  47    Normally, the creator becomes the owner of the new database.
  48    Superusers can create databases owned by other users using the
  49    <literal>OWNER</> clause. They can even create databases owned by
  50    users with no special privileges. Non-superusers with <literal>CREATEDB</>
  51    privilege can only create databases owned by themselves.
  52   </para>
  53
  54   <para>
  55    By default, the new database will be created by cloning the standard
  56    system database <literal>template1</>.  A different template can be
  57    specified by writing <literal>TEMPLATE
  58    <replaceable class="parameter">name</replaceable></literal>.  In particular,
  59    by writing <literal>TEMPLATE template0</>, you can create a virgin
  60    database containing only the standard objects predefined by your
  61    version of <productname>PostgreSQL</productname>.  This is useful
  62    if you wish to avoid copying
  63    any installation-local objects that may have been added to
  64    <literal>template1</>.
  65   </para>
  66  </refsect1>
  67
  68  <refsect1>
  69   <title>Parameters</title>
  70
  71     <variablelist>
  72      <varlistentry>
  73       <term><replaceable class="parameter">name</replaceable></term>
  74       <listitem>
  75        <para>
  76         The name of a database to create.
  77        </para>
  78       </listitem>
  79      </varlistentry>
  80      <varlistentry>
  81       <term><replaceable class="parameter">dbowner</replaceable></term>
  82       <listitem>
  83        <para>
  84         The name of the database user who will own the new database,
  85         or <literal>DEFAULT</literal> to use the default (namely, the
  86         user executing the command).
  87        </para>
  88       </listitem>
  89      </varlistentry>
  90      <varlistentry>
  91       <term><replaceable class="parameter">template</replaceable></term>
  92       <listitem>
  93        <para>
  94         The name of the template from which to create the new database,
  95         or <literal>DEFAULT</literal> to use the default template
  96         (<literal>template1</literal>).
  97        </para>
  98       </listitem>
  99      </varlistentry>
 100      <varlistentry>
 101       <term><replaceable class="parameter">encoding</replaceable></term>
 102       <listitem>
 103        <para>
 104         Character set encoding to use in the new database.  Specify
 105         a string constant (e.g., <literal>'SQL_ASCII'</literal>),
 106         or an integer encoding number, or <literal>DEFAULT</literal>
 107         to use the default encoding. The character sets supported by the
 108         <productname>PostgreSQL</productname> server are described in
 109         <xref linkend="multibyte-charset-supported">.
 110        </para>
 111       </listitem>
 112      </varlistentry>
 113      <varlistentry>
 114       <term><replaceable class="parameter">tablespace</replaceable></term>
 115       <listitem>
 116        <para>
 117         The name of the tablespace that will be associated with the
 118         new database, or <literal>DEFAULT</literal> to use the
 119         template database's tablespace. This
 120         tablespace will be the default tablespace used for objects
 121         created in this database. See
 122         <xref linkend="sql-createtablespace" endterm="sql-createtablespace-title">
 123         for more information.
 124        </para>
 125       </listitem>
 126      </varlistentry>
 127
 128      <varlistentry>
 129       <term><replaceable class="parameter">connlimit</replaceable></term>
 130       <listitem>
 131        <para>
 132         How many concurrent connections can be made
 133         to this database.  -1 (the default) means no limit.
 134        </para>
 135       </listitem>
 136      </varlistentry>
 137     </variablelist>
 138
 139   <para>
 140    Optional parameters can be written in any order, not only the order
 141    illustrated above.
 142   </para>
 143  </refsect1>
 144
 145  <refsect1>
 146   <title>Notes</title>
 147
 148    <para>
 149     <command>CREATE DATABASE</> cannot be executed inside a transaction
 150     block.
 151    </para>
 152
 153    <para>
 154     Errors along the line of <quote>could not initialize database directory</>
 155     are most likely related to insufficient permissions on the data
 156     directory, a full disk, or other file system problems.
 157    </para>
 158
 159    <para>
 160     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 161    </para>
 162
 163    <para>
 164     The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 165     wrapper program around this command, provided for convenience.
 166    </para>
 167
 168   <para>
 169    Although it is possible to copy a database other than <literal>template1</>
 170    by specifying its name as the template, this is not (yet) intended as
 171    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
 172    We recommend that databases used as templates be treated as read-only.
 173    See <xref linkend="manage-ag-templatedbs"> for more information.
 174   </para>
 175
 176   <para>
 177    The <literal>CONNECTION LIMIT</> option is only enforced approximately;
 178    if two new sessions start at about the same time when just one
 179    connection <quote>slot</> remains for the database, it is possible that
 180    both will fail.  Also, the limit is not enforced against superusers.
 181   </para>
 182  </refsect1>
 183
 184  <refsect1>
 185   <title>Examples</title>
 186
 187   <para>
 188    To create a new database:
 189
 190 <programlisting>
 191 CREATE DATABASE lusiadas;
 192 </programlisting>
 193   </para>
 194
 195   <para>
 196    To create a database <literal>sales</> owned by user <literal>salesapp</>
 197    with a default tablespace of <literal>salesspace</>:
 198
 199 <programlisting>
 200 CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 201 </programlisting>
 202   </para>
 203
 204   <para>
 205    To create a database <literal>music</> which supports the ISO-8859-1
 206    character set:
 207
 208 <programlisting>
 209 CREATE DATABASE music ENCODING 'LATIN1';
 210 </programlisting>
 211   </para>
 212  </refsect1>
 213
 214  <refsect1>
 215   <title>Compatibility</title>
 216
 217   <para>
 218    There is no <command>CREATE DATABASE</command> statement in the SQL
 219    standard.  Databases are equivalent to catalogs, whose creation is
 220    implementation-defined.
 221   </para>
 222  </refsect1>
 223 </refentry>
 224
 225 <!-- Keep this comment at the end of the file
 226 Local variables:
 227 mode: sgml
 228 sgml-omittag:nil
 229 sgml-shorttag:t
 230 sgml-minimize-attributes:nil
 231 sgml-always-quote-attributes:t
 232 sgml-indent-step:1
 233 sgml-indent-data:t
 234 sgml-parent-document:nil
 235 sgml-default-dtd-file:"../reference.ced"
 236 sgml-exposed-tags:nil
 237 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 238 sgml-local-ecat-files:nil
 239 End:
 240 -->