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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.36 2003/09/12 00:12:47 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            [ LOCATION [=] '<replaceable class="parameter">dbpath</replaceable>' ]
  26            [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
  27            [ ENCODING [=] <replaceable class="parameter">encoding</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    An alternative location can be specified in order to,
  55    for example, store the database on a different disk.
  56    The path must have been prepared with the
  57    <xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
  58    command.
  59   </para>
  60
  61   <para>
  62    If the path name does not contain a slash, it is interpreted
  63    as an environment variable name, which must be known to the
  64    server process. This way the database administrator can
  65    exercise control over locations in which databases can be created.
  66    (A customary choice is, e.g., <envar>PGDATA2</envar>.)
  67    If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
  68    (not so by default), absolute path names, as identified by
  69    a leading slash
  70    (e.g., <filename>/usr/local/pgsql/data</filename>),
  71    are allowed as well.
  72    In either case, the final path name must be absolute and must not
  73    contain any single quotes.
  74   </para>
  75
  76   <para>
  77    By default, the new database will be created by cloning the standard
  78    system database <literal>template1</>.  A different template can be
  79    specified by writing <literal>TEMPLATE
  80    <replaceable class="parameter">name</replaceable></literal>.  In particular,
  81    by writing <literal>TEMPLATE template0</>, you can create a virgin
  82    database containing only the standard objects predefined by your
  83    version of <productname>PostgreSQL</productname>.  This is useful
  84    if you wish to avoid copying
  85    any installation-local objects that may have been added to
  86    <literal>template1</>.
  87   </para>
  88
  89   <para>
  90    The optional encoding parameter allows selection of the database
  91    encoding.  When not specified, it defaults to the encoding used by
  92    the selected template database.
  93   </para>
  94  </refsect1>
  95
  96  <refsect1>
  97   <title>Parameters</title>
  98
  99     <variablelist>
 100      <varlistentry>
 101       <term><replaceable class="parameter">name</replaceable></term>
 102       <listitem>
 103        <para>
 104         The name of a database to create.
 105        </para>
 106       </listitem>
 107      </varlistentry>
 108      <varlistentry>
 109       <term><replaceable class="parameter">dbowner</replaceable></term>
 110       <listitem>
 111        <para>
 112         The name of the database user who will own the new database,
 113         or <literal>DEFAULT</literal> to use the default (namely, the
 114         user executing the command).
 115        </para>
 116       </listitem>
 117      </varlistentry>
 118      <varlistentry>
 119       <term><replaceable class="parameter">dbpath</replaceable></term>
 120       <listitem>
 121        <para>
 122         An alternate file-system location in which to store the new database,
 123         specified as a string literal;
 124         or <literal>DEFAULT</literal> to use the default location.
 125        </para>
 126       </listitem>
 127      </varlistentry>
 128      <varlistentry>
 129       <term><replaceable class="parameter">template</replaceable></term>
 130       <listitem>
 131        <para>
 132         The name of the template from which to create the new database,
 133         or <literal>DEFAULT</literal> to use the default template
 134         (<literal>template1</literal>).
 135        </para>
 136       </listitem>
 137      </varlistentry>
 138      <varlistentry>
 139       <term><replaceable class="parameter">encoding</replaceable></term>
 140       <listitem>
 141        <para>
 142         Character set encoding to use in the new database.  Specify
 143         a string constant (e.g., <literal>'SQL_ASCII'</literal>),
 144         or an integer encoding number, or <literal>DEFAULT</literal>
 145         to use the default encoding.
 146        </para>
 147       </listitem>
 148      </varlistentry>
 149     </variablelist>
 150
 151   <para>
 152    Optional parameters can be written in any order, not only the order
 153    illustrated above.
 154   </para>
 155  </refsect1>
 156
 157  <refsect1>
 158   <title>Notes</title>
 159
 160    <para>
 161     <command>CREATE DATABASE</> cannot be executed inside a transaction
 162     block.
 163    </para>
 164
 165    <para>
 166     Errors along the line of <quote>could not initialize database directory</>
 167     are most likely related to insufficient permissions on the data
 168     directory, a full disk, or other file system problems.  When using an
 169     alternate location, the user under
 170     which the database server is running must have access to the location.
 171    </para>
 172
 173    <para>
 174     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 175    </para>
 176
 177    <para>
 178     The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 179     wrapper program around this command, provided for convenience.
 180    </para>
 181
 182   <para>
 183    There are security issues involved with using alternate database
 184    locations specified with absolute path names; this is why the feature
 185    is not enabled by default.  See <xref
 186    linkend="manage-ag-alternate-locs"> for more information.
 187   </para>
 188
 189   <para>
 190    Although it is possible to copy a database other than <literal>template1</>
 191    by specifying its name as the template, this is not (yet) intended as
 192    a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
 193    We recommend that databases used as templates be treated as read-only.
 194    See <xref linkend="manage-ag-templatedbs"> for more information.
 195   </para>
 196  </refsect1>
 197
 198  <refsect1>
 199   <title>Examples</title>
 200
 201   <para>
 202    To create a new database:
 203
 204 <programlisting>
 205 CREATE DATABASE lusiadas;
 206 </programlisting>
 207   </para>
 208
 209   <para>
 210    To create a new database in an alternate area
 211    <filename>~/private_db</filename>, execute the following from the
 212    shell:
 213
 214 <programlisting>
 215 mkdir private_db
 216 initlocation ~/private_db
 217 </programlisting>
 218
 219    Then execute the following from within a
 220    <application>psql</application> session:
 221
 222 <programlisting>
 223 CREATE DATABASE elsewhere WITH LOCATION '/home/olly/private_db';
 224 </programlisting>
 225   </para>
 226  </refsect1>
 227
 228  <refsect1>
 229   <title>Compatibility</title>
 230
 231   <para>
 232    There is no <command>CREATE DATABASE</command> statement in the SQL
 233    standard.  Databases are equivalent to catalogs, whose creation is
 234    implementation-defined.
 235   </para>
 236  </refsect1>
 237 </refentry>
 238
 239 <!-- Keep this comment at the end of the file
 240 Local variables:
 241 mode: sgml
 242 sgml-omittag:nil
 243 sgml-shorttag:t
 244 sgml-minimize-attributes:nil
 245 sgml-always-quote-attributes:t
 246 sgml-indent-step:1
 247 sgml-indent-data:t
 248 sgml-parent-document:nil
 249 sgml-default-dtd-file:"../reference.ced"
 250 sgml-exposed-tags:nil
 251 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 252 sgml-local-ecat-files:nil
 253 End:
 254 -->