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.15 2000/10/05 19:48:17 momjian Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="SQL-CREATEDATABASE">
   7  <refmeta>
   8   <refentrytitle id="sql-createdatabase-title">
   9    CREATE DATABASE
  10   </refentrytitle>
  11   <refmiscinfo>SQL - Language Statements</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    CREATE DATABASE
  16   </refname>
  17   <refpurpose>
  18    Creates a new database
  19   </refpurpose>
  20  </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>1999-12-11</date>
  24   </refsynopsisdivinfo>
  25   <synopsis>
  26 CREATE DATABASE <replaceable class="PARAMETER">name</replaceable> [ WITH LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ]
  27   </synopsis>
  28
  29   <refsect2 id="R2-SQL-CREATEDATABASE-1">
  30    <refsect2info>
  31     <date>1999-12-11</date>
  32    </refsect2info>
  33    <title>
  34     Inputs
  35    </title>
  36    <para>
  37
  38     <variablelist>
  39      <varlistentry>
  40       <term><replaceable class="parameter">name</replaceable></term>
  41       <listitem>
  42        <para>
  43         The name of a database to create.
  44        </para>
  45       </listitem>
  46      </varlistentry>
  47      <varlistentry>
  48       <term><replaceable class="parameter">dbpath</replaceable></term>
  49       <listitem>
  50        <para>
  51         An alternate location where to store the new database in the filesystem.
  52         See below for caveats.
  53        </para>
  54       </listitem>
  55      </varlistentry>
  56     </variablelist>
  57    </para>
  58   </refsect2>
  59
  60   <refsect2 id="R2-SQL-CREATEDATABASE-2">
  61    <refsect2info>
  62     <date>1999-12-11</date>
  63    </refsect2info>
  64    <title>
  65     Outputs
  66    </title>
  67    <para>
  68
  69     <variablelist>
  70      <varlistentry>
  71       <term><computeroutput>CREATE DATABASE</computeroutput></term>
  72       <listitem>
  73        <para>
  74         Message returned if the command completes successfully.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term><computeroutput>ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
  81       <listitem>
  82        <para>
  83         You must have the special CREATEDB privilege to create databases.
  84         See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
  85        </para>
  86       </listitem>
  87      </varlistentry>
  88
  89
  90      <varlistentry>
  91       <term><computeroutput>ERROR:  createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
  92       <listitem>
  93        <para>
  94         This occurs if a database with the <replaceable class="parameter">name</replaceable>
  95         specified already exists.
  96        </para>
  97       </listitem>
  98      </varlistentry>
  99
 100      <varlistentry>
 101       <term><computeroutput>ERROR:  Single quotes are not allowed in database names.</computeroutput></term>
 102       <term><computeroutput>ERROR:  Single quotes are not allowed in database paths.</computeroutput></term>
 103       <listitem>
 104        <para>
 105         The database <replaceable class="parameter">name</replaceable> and
 106         <replaceable class="parameter">dbpath</replaceable> cannot contain
 107         single quotes. This is required so that the shell commands that
 108         create the database directory can execute safely.
 109        </para>
 110       </listitem>
 111      </varlistentry>
 112
 113      <varlistentry>
 114       <term><computeroutput>ERROR:  The path 'xxx' is invalid.</computeroutput></term>
 115       <listitem>
 116        <para>
 117         The expansion of the specified <replaceable class="parameter">dbpath</replaceable>
 118         (see below) failed. Check the path you entered or make sure that the
 119         environment variable you are referencing does exist.
 120        </para>
 121       </listitem>
 122      </varlistentry>
 123
 124      <varlistentry>
 125       <term><computeroutput>ERROR:  createdb: May not be called in a transaction block.</computeroutput></term>
 126       <listitem>
 127        <para>
 128         If you have an explicit transaction block in progress you cannot call
 129         <command>CREATE DATABASE</command>. You must finish the transaction first.
 130        </para>
 131       </listitem>
 132      </varlistentry>
 133
 134      <varlistentry>
 135       <term><computeroutput>ERROR:  Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term>
 136       <term><computeroutput>ERROR:  Could not initialize database directory.</computeroutput></term>
 137       <listitem>
 138        <para>
 139         These are most likely related to insufficient permissions on the data
 140         directory, a full disk, or other file system problems. The user under
 141         which the database server is running must have access to the location.
 142        </para>
 143       </listitem>
 144      </varlistentry>
 145
 146     </variablelist>
 147    </para>
 148   </refsect2>
 149  </refsynopsisdiv>
 150
 151  <refsect1 id="R1-SQL-CREATEDATABASE-1">
 152   <refsect1info>
 153    <date>1999-12-11</date>
 154   </refsect1info>
 155   <title>
 156    Description
 157   </title>
 158   <para>
 159    <command>CREATE DATABASE</command> creates a new
 160    <productname>Postgres</productname> database.
 161    The creator becomes the owner of the new database.
 162   </para>
 163
 164   <para>
 165    An alternate location can be specified in order to,
 166    for example, store the database on a different disk.
 167    The path must have been prepared with the
 168    <xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
 169    command.
 170   </para>
 171   <para>
 172    If the path contains a slash, the leading part is interpreted
 173    as an environment variable, which must be known to the
 174    server process. This way the database administrator can
 175    exercise control over at which locations databases can be created.
 176    (A customary choice is, e.g., '<envar>PGDATA2</envar>'.)
 177    If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
 178    (not so by default), absolute path names, as identified by
 179    a leading slash
 180    (e.g., '<filename>/usr/local/pgsql/data</filename>'),
 181    are allowed as well.
 182   </para>
 183
 184   <refsect2 id="R2-SQL-CREATEDATABASE-3">
 185    <refsect2info>
 186     <date>1999-12-11</date>
 187    </refsect2info>
 188    <title>
 189     Notes
 190    </title>
 191    <para>
 192     <command>CREATE DATABASE</command> is a <productname>Postgres</productname>
 193     language extension.
 194    </para>
 195    <para>
 196     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 197    </para>
 198    <para>
 199     The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 200     shell script wrapper around this command, provided for convenience.
 201    </para>
 202
 203    <para>
 204     There are security and data integrity issues
 205     involved with using alternate database locations
 206     specified with absolute path names, and by default
 207     only an environment variable known to the backend may be
 208     specified for an alternate location.
 209     See the Administrator's Guide for more information.
 210    </para>
 211
 212 <!--
 213 comment from Olly; response from Thomas...
 214   <comment>
 215    initlocation does not create a PG_VERSION file in the specified location.
 216    How will Postgres handle the situation if it is upgraded to an
 217    incompatible database version?
 218   </comment>
 219    Hmm. This isn't an issue since the upgrade would do
 220    a dump/reload from the main database area also.
 221    Not sure if the dump/reload would guarantee that
 222    the alternate data area gets refreshed though...
 223 -->
 224   </refsect2>
 225  </refsect1>
 226
 227  <refsect1 id="R1-SQL-CREATEDATABASE-2">
 228   <title>
 229    Usage
 230   </title>
 231   <para>
 232    To create a new database:
 233
 234    <programlisting>
 235 <prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
 236    </programlisting>
 237   </para>
 238
 239   <para>
 240    To create a new database in an alternate area <filename>~/private_db</filename>:
 241
 242    <programlisting>
 243 <prompt>$</prompt> <userinput>mkdir private_db</userinput>
 244 <prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
 245 <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
 246
 247 <prompt>$</prompt> <userinput>psql olly</userinput>
 248 <computeroutput>
 249 Welcome to psql, the PostgreSQL interactive terminal.
 250
 251 Type:  \copyright for distribution terms
 252        \h for help with SQL commands
 253        \? for help on internal slash commands
 254        \g or terminate with semicolon to execute query
 255        \q to quit
 256
 257 <prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
 258 <computeroutput>CREATE DATABASE</computeroutput>
 259    </programlisting>
 260   </para>
 261  </refsect1>
 262
 263  <refsect1 id="R1-SQL-CREATEDATABASE-4">
 264   <title>
 265    Compatibility
 266   </title>
 267
 268   <refsect2 id="R2-SQL-CREATEDATABASE-4">
 269    <refsect2info>
 270     <date>1998-04-15</date>
 271    </refsect2info>
 272    <title>
 273     SQL92
 274    </title>
 275    <para>
 276     There is no <command>CREATE DATABASE</command> statement in SQL92.
 277     Databases are equivalent to catalogs whose creation is implementation-defined.
 278    </para>
 279   </refsect2>
 280  </refsect1>
 281 </refentry>
 282
 283 <!-- Keep this comment at the end of the file
 284 Local variables:
 285 mode: sgml
 286 sgml-omittag:nil
 287 sgml-shorttag:t
 288 sgml-minimize-attributes:nil
 289 sgml-always-quote-attributes:t
 290 sgml-indent-step:1
 291 sgml-indent-data:t
 292 sgml-parent-document:nil
 293 sgml-default-dtd-file:"../reference.ced"
 294 sgml-exposed-tags:nil
 295 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 296 sgml-local-ecat-files:nil
 297 End:
 298 -->