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.41 2004/07/17 16:33:31 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 </synopsis>
  29  </refsynopsisdiv>
  30
  31  <refsect1>
  32   <title>Description</title>
  33
  34   <para>
  35    <command>CREATE DATABASE</command> creates a new
  36    <productname>PostgreSQL</productname> database.
  37   </para>
  38
  39   <para>
  40    To create a database, you must be a superuser or have the special
  41    <literal>CREATEDB</> privilege.
  42    See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
  43   </para>
  44
  45   <para>
  46    Normally, the creator becomes the owner of the new database.
  47    Superusers can create databases owned by other users using the
  48    <literal>OWNER</> clause. They can even create databases owned by
  49    users with no special privileges. Non-superusers with <literal>CREATEDB</>
  50    privilege can only create databases owned by themselves.
  51   </para>
  52
  53   <para>
  54    By default, the new database will be created by cloning the standard
  55    system database <literal>template1</>.  A different template can be
  56    specified by writing <literal>TEMPLATE
  57    <replaceable class="parameter">name</replaceable></literal>.  In particular,
  58    by writing <literal>TEMPLATE template0</>, you can create a virgin
  59    database containing only the standard objects predefined by your
  60    version of <productname>PostgreSQL</productname>.  This is useful
  61    if you wish to avoid copying
  62    any installation-local objects that may have been added to
  63    <literal>template1</>.
  64   </para>
  65  </refsect1>
  66
  67  <refsect1>
  68   <title>Parameters</title>
  69
  70     <variablelist>
  71      <varlistentry>
  72       <term><replaceable class="parameter">name</replaceable></term>
  73       <listitem>
  74        <para>
  75         The name of a database to create.
  76        </para>
  77       </listitem>
  78      </varlistentry>
  79      <varlistentry>
  80       <term><replaceable class="parameter">dbowner</replaceable></term>
  81       <listitem>
  82        <para>
  83         The name of the database user who will own the new database,
  84         or <literal>DEFAULT</literal> to use the default (namely, the
  85         user executing the command).
  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. The character sets supported by the
 107         <productname>PostgreSQL</productname> server are described in
 108         <xref linkend="multibyte-charset-supported">.
 109        </para>
 110       </listitem>
 111      </varlistentry>
 112      <varlistentry>
 113       <term><replaceable class="parameter">tablespace</replaceable></term>
 114       <listitem>
 115        <para>
 116         Specifies the default tablespace for the new database.
 117         If not specified, the same tablespace that is default for
 118         the template database is used.  See
 119         <xref linkend="sql-createtablespace" endterm="sql-createtablespace-title">
 120         for more information.
 121        </para>
 122       </listitem>
 123      </varlistentry>
 124     </variablelist>
 125
 126   <para>
 127    Optional parameters can be written in any order, not only the order
 128    illustrated above.
 129   </para>
 130  </refsect1>
 131
 132  <refsect1>
 133   <title>Notes</title>
 134
 135    <para>
 136     <command>CREATE DATABASE</> cannot be executed inside a transaction
 137     block.
 138    </para>
 139
 140    <para>
 141     Errors along the line of <quote>could not initialize database directory</>
 142     are most likely related to insufficient permissions on the data
 143     directory, a full disk, or other file system problems.
 144    </para>
 145
 146    <para>
 147     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 148    </para>
 149
 150    <para>
 151     The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 152     wrapper program around this command, provided for convenience.
 153    </para>
 154
 155   <para>
 156    Although it is possible to copy a database other than <literal>template1</>
 157    by specifying its name as the template, this is not (yet) intended as
 158    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
 159    We recommend that databases used as templates be treated as read-only.
 160    See <xref linkend="manage-ag-templatedbs"> for more information.
 161   </para>
 162  </refsect1>
 163
 164  <refsect1>
 165   <title>Examples</title>
 166
 167   <para>
 168    To create a new database:
 169
 170 <programlisting>
 171 CREATE DATABASE lusiadas;
 172 </programlisting>
 173   </para>
 174
 175   <para>
 176    To create a database <literal>sales</> owned by user <literal>salesapp</>>
 177    with a default tablespace of <literal>salesspace</>:
 178
 179 <programlisting>
 180 CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
 181 </programlisting>
 182   </para>
 183
 184   <para>
 185    To create a database <literal>music</> which supports the ISO-8859-1
 186    character set:
 187
 188 <programlisting>
 189 CREATE DATABASE music ENCODING 'LATIN1';
 190 </programlisting>
 191   </para>
 192  </refsect1>
 193
 194  <refsect1>
 195   <title>Compatibility</title>
 196
 197   <para>
 198    There is no <command>CREATE DATABASE</command> statement in the SQL
 199    standard.  Databases are equivalent to catalogs, whose creation is
 200    implementation-defined.
 201   </para>
 202  </refsect1>
 203 </refentry>
 204
 205 <!-- Keep this comment at the end of the file
 206 Local variables:
 207 mode: sgml
 208 sgml-omittag:nil
 209 sgml-shorttag:t
 210 sgml-minimize-attributes:nil
 211 sgml-always-quote-attributes:t
 212 sgml-indent-step:1
 213 sgml-indent-data:t
 214 sgml-parent-document:nil
 215 sgml-default-dtd-file:"../reference.ced"
 216 sgml-exposed-tags:nil
 217 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 218 sgml-local-ecat-files:nil
 219 End:
 220 -->