postgresql/doc/src/sgml/ref/create_database.sgml

<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_database.sgml,v 1.11 1999/12/12 05:15:09 momjian Exp $
Postgres 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>
   Creates a new database
  </refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <refsynopsisdivinfo>
   <date>1999-12-11</date>
  </refsynopsisdivinfo>
  <synopsis>
CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> [ WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ]
  </synopsis>

  <refsect2 id="R2-SQL-CREATEDATABASE-1">
   <refsect2info>
    <date>1999-12-11</date>
   </refsect2info>
   <title>
    Inputs
   </title>
   <para>

    <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">dbpath</replaceable></term>
      <listitem>
       <para>
	An alternate location where to store the new database in the filesystem.
        See below for caveats.
       </para>
      </listitem>
     </varlistentry>
    </variablelist>
   </para>
  </refsect2>

  <refsect2 id="R2-SQL-CREATEDATABASE-2">
   <refsect2info>
    <date>1999-12-11</date>
   </refsect2info>
   <title>
    Outputs
   </title>
   <para>

    <variablelist>
     <varlistentry>
      <term><computeroutput>CREATE DATABASE</computeroutput></term>
      <listitem>
       <para>
	Message returned if the command completes successfully.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
      <listitem>
       <para>
        You must have the special CREATEDB privilege to create databases.
        See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
       </para>
      </listitem>
     </varlistentry>


     <varlistentry>
      <term><computeroutput>ERROR:  createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
      <listitem>
       <para>
	This occurs if a database with the <replaceable class="parameter">name</replaceable>
        specified already exists.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>ERROR:  Single quotes are not allowed in database names.</computeroutput></term>
      <term><computeroutput>ERROR:  Single quotes are not allowed in database paths.</computeroutput></term>
      <listitem>
       <para>
	The database <replaceable class="parameter">name</replaceable> and
        <replaceable class="parameter">dbpath</replaceable> cannot contain
        single quotes. This is required so that the shell commands that
        create the database directory can execute safely.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>ERROR:  The path 'xxx' is invalid.</computeroutput></term>
      <listitem>
       <para>
        The expansion of the specified <replaceable class="parameter">dbpath</replaceable>
        (see below how) failed. Check the path you entered or make sure that the
        environment variable you are referencing does exist.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>ERROR:  createdb: May not be called in a transaction block.</computeroutput></term>
      <listitem>
       <para>
        If you have an explicit transaction block in progress you cannot call
        <command>CREATE DATABASE</command>. You must finish the transaction first.
       </para>
      </listitem>
     </varlistentry>

     <varlistentry>
      <term><computeroutput>ERROR:  Unable to create database directory 'xxx'.</computeroutput></term>
      <term><computeroutput>ERROR:  Could not initialize database directory.</computeroutput></term>
      <listitem>
       <para>
        These are most likely related to insufficient permissions on the data
        directory, a full disk, or other file system problems. The user under
        which the database server is running, must have access to the location.
       </para>
      </listitem>
     </varlistentry>

    </variablelist>
   </para>
  </refsect2>
 </refsynopsisdiv>

 <refsect1 id="R1-SQL-CREATEDATABASE-1">
  <refsect1info>
   <date>1999-12-11</date>
  </refsect1info>
  <title>
   Description
  </title>
  <para>
   <command>CREATE DATABASE</command> creates a new
   <productname>PostgreSQL</productname> database.
   The creator becomes the owner of the new database.
  </para>

  <para>
   An alternate location can be specified in order to,
   for example, store the database on a different disk.
   The path must have been prepared with the <xref
   linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
   command.
  </para>
  <para>
   If the path contains a slash, the leading part is interpreted
   as an environment variable, which must be known to the
   server process. This way the database administrator can
   exercise control over at which locations databases can be created.
   (A customary choice is, e.g., '<envar>PGDATA2</envar>'.)
   If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
   (not so by default), absolute path names, as identified by
   a leading slash
   (e.g. '<filename>/usr/local/pgsql/data</filename>'),
   are allowed as well.
  </para>

  <refsect2 id="R2-SQL-CREATEDATABASE-3">
   <refsect2info>
    <date>1999-12-11</date>
   </refsect2info>
   <title>
    Notes
   </title>
   <para>
    <command>CREATE DATABASE</command> is a <productname>Postgres</productname>
    language extension.
   </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
    shell script wrapper around this command, provided for convenience.
   </para>

   <para>
    There are security and data integrity issues
    involved with using alternate database locations
    specified with absolute path names, and by default
    only an environment variable known to the backend may be
    specified for an alternate location.
    See the Administrator's Guide for more information.
   </para>

<!--
comment from Olly; response from Thomas...
  <comment>
   initlocation does not create a PG_VERSION file in the specified location.
   How will Postgres handle the situation if it is upgraded to an 
   incompatible database version?
  </comment>
   Hmm. This isn't an issue since the upgrade would do
   a dump/reload from the main database area also.
   Not sure if the dump/reload would guarantee that
   the alternate data area gets refreshed though...
-->
  </refsect2>
 </refsect1>

 <refsect1 id="R1-SQL-CREATEDATABASE-2">
  <title>
   Usage
  </title>
  <para>
   To create a new database:

   <programlisting>
<prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
   </programlisting>
  </para>

  <para>
   To create a new database in an alternate area <filename>~/private_db</filename>:

   <programlisting>
<prompt>$</prompt> <userinput>mkdir private_db</userinput>
<prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
<computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
   
<prompt>$</prompt> <userinput>psql olly</userinput>
<computeroutput>Welcome to psql, the PostgreSQL interactive terminal.
(Please type \copyright to see the distribution terms of PostgreSQL.)
 
Type \h for help with SQL commands,
     \? for help on internal slash commands,
     \q to quit,
     \g or terminate with semicolon to execute query.
<prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
<computeroutput>CREATE DATABASE</computeroutput>
   </programlisting>
  </para>
 </refsect1>

 <refsect1 id="R1-SQL-CREATEDATABASE-4">
  <title>
   Compatibility
  </title>

  <refsect2 id="R2-SQL-CREATEDATABASE-4">
   <refsect2info>
    <date>1998-04-15</date>
   </refsect2info>
   <title>
    SQL92
   </title>
   <para>
    There is no <command>CREATE DATABASE</command> statement in SQL92.
    The equivalent command in standard SQL is <command>CREATE SCHEMA</command>.
   </para>
  </refsect2>
 </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:
-->