postgres/doc/src/sgml/ref/create_database.sgml

<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_database.sgml,v 1.41 2004/07/17 16:33:31 tgl Exp $
PostgreSQL documentation
-->

<refentry id="SQL-CREATEDATABASE">
 <refmeta>
  <refentrytitle id="sql-createdatabase-title">CREATE DATABASE</refentrytitle>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE DATABASE</refname>
  <refpurpose>create a new database</refpurpose>
 </refnamediv>

 <indexterm zone="sql-createdatabase">
  <primary>CREATE DATABASE</primary>
 </indexterm>

 <refsynopsisdiv>
<synopsis>
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable>
    [ [ WITH ] [ OWNER [=] <replaceable class="parameter">dbowner</replaceable> ]
           [ TEMPLATE [=] <replaceable class="parameter">template</replaceable> ]
           [ ENCODING [=] <replaceable class="parameter">encoding</replaceable> ]
           [ TABLESPACE [=] <replaceable class="parameter">tablespace</replaceable> ] ]
</synopsis>
 </refsynopsisdiv>

 <refsect1>
  <title>Description</title>

  <para>
   <command>CREATE DATABASE</command> creates a new
   <productname>PostgreSQL</productname> database.
  </para>

  <para>
   To create a database, you must be a superuser or have the special
   <literal>CREATEDB</> privilege.
   See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
  </para>

  <para>
   Normally, the creator becomes the owner of the new database.
   Superusers can create databases owned by other users using the
   <literal>OWNER</> clause. They can even create databases owned by
   users with no special privileges. Non-superusers with <literal>CREATEDB</>
   privilege can only create databases owned by themselves.
  </para>

  <para>
   By default, the new database will be created by cloning the standard
   system database <literal>template1</>.  A different template can be
   specified by writing <literal>TEMPLATE
   <replaceable class="parameter">name</replaceable></literal>.  In particular,
   by writing <literal>TEMPLATE template0</>, you can create a virgin
   database containing only the standard objects predefined by your
   version of <productname>PostgreSQL</productname>.  This is useful
   if you wish to avoid copying
   any installation-local objects that may have been added to
   <literal>template1</>.
  </para>
 </refsect1>

 <refsect1>
  <title>Parameters</title>

    <variablelist>
     <varlistentry>
      <term><replaceable class="parameter">name</replaceable></term>
      <listitem>
       <para>
        The name of a database to create.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">dbowner</replaceable></term>
      <listitem>
       <para>
        The name of the database user who will own the new database,
        or <literal>DEFAULT</literal> to use the default (namely, the
        user executing the command).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">template</replaceable></term>
      <listitem>
       <para>
        The name of the template from which to create the new database,
        or <literal>DEFAULT</literal> to use the default template
        (<literal>template1</literal>).
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">encoding</replaceable></term>
      <listitem>
       <para>
        Character set encoding to use in the new database.  Specify
        a string constant (e.g., <literal>'SQL_ASCII'</literal>),
        or an integer encoding number, or <literal>DEFAULT</literal>
        to use the default encoding. The character sets supported by the
        <productname>PostgreSQL</productname> server are described in
        <xref linkend="multibyte-charset-supported">.
       </para>
      </listitem>
     </varlistentry>
     <varlistentry>
      <term><replaceable class="parameter">tablespace</replaceable></term>
      <listitem>
       <para>
        Specifies the default tablespace for the new database.
        If not specified, the same tablespace that is default for
        the template database is used.  See
        <xref linkend="sql-createtablespace" endterm="sql-createtablespace-title">
        for more information.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>

  <para>
   Optional parameters can be written in any order, not only the order
   illustrated above.
  </para>
 </refsect1>

 <refsect1>
  <title>Notes</title>

   <para>
    <command>CREATE DATABASE</> cannot be executed inside a transaction
    block.
   </para>

   <para>
    Errors along the line of <quote>could not initialize database directory</>
    are most likely related to insufficient permissions on the data
    directory, a full disk, or other file system problems.
   </para>

   <para>
    Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
   </para>

   <para>
    The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
    wrapper program around this command, provided for convenience.
   </para>

  <para>
   Although it is possible to copy a database other than <literal>template1</>
   by specifying its name as the template, this is not (yet) intended as
   a general-purpose <quote><command>COPY DATABASE</command></quote> facility.
   We recommend that databases used as templates be treated as read-only.
   See <xref linkend="manage-ag-templatedbs"> for more information.
  </para>
 </refsect1>

 <refsect1>
  <title>Examples</title>

  <para>
   To create a new database:

<programlisting>
CREATE DATABASE lusiadas;
</programlisting>
  </para>

  <para>
   To create a database <literal>sales</> owned by user <literal>salesapp</>>
   with a default tablespace of <literal>salesspace</>:

<programlisting>
CREATE DATABASE sales OWNER salesapp TABLESPACE salesspace;
</programlisting>
  </para>

  <para>
   To create a database <literal>music</> which supports the ISO-8859-1 
   character set:

<programlisting>
CREATE DATABASE music ENCODING 'LATIN1';
</programlisting>
  </para>
 </refsect1>

 <refsect1>
  <title>Compatibility</title>

  <para>
   There is no <command>CREATE DATABASE</command> statement in the SQL
   standard.  Databases are equivalent to catalogs, whose creation is
   implementation-defined.
  </para>
 </refsect1>
</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->