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.21 2001/11/18 00:38:00 tgl 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    create 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>
  27     [ WITH [ LOCATION = '<replaceable class="parameter">dbpath</replaceable>' ]
  28            [ TEMPLATE = <replaceable class="parameter">template</replaceable> ]
  29            [ ENCODING = <replaceable class="parameter">encoding</replaceable> ] ]
  30   </synopsis>
  31
  32   <refsect2 id="R2-SQL-CREATEDATABASE-1">
  33    <refsect2info>
  34     <date>1999-12-11</date>
  35    </refsect2info>
  36    <title>
  37     Inputs
  38    </title>
  39    <para>
  40
  41     <variablelist>
  42      <varlistentry>
  43       <term><replaceable class="parameter">name</replaceable></term>
  44       <listitem>
  45        <para>
  46         The name of a database to create.
  47        </para>
  48       </listitem>
  49      </varlistentry>
  50      <varlistentry>
  51       <term><replaceable class="parameter">dbpath</replaceable></term>
  52       <listitem>
  53        <para>
  54         An alternate filesystem location in which to store the new database,
  55         specified as a string literal;
  56         or <literal>DEFAULT</literal> to use the default location.
  57        </para>
  58       </listitem>
  59      </varlistentry>
  60      <varlistentry>
  61       <term><replaceable class="parameter">template</replaceable></term>
  62       <listitem>
  63        <para>
  64         Name of template from which to create the new database,
  65         or <literal>DEFAULT</literal> to use the default template
  66         (<literal>template1</literal>).
  67        </para>
  68       </listitem>
  69      </varlistentry>
  70      <varlistentry>
  71       <term><replaceable class="parameter">encoding</replaceable></term>
  72       <listitem>
  73        <para>
  74         Multibyte encoding method to use in the new database.  Specify
  75         a string literal name (e.g., <literal>'SQL_ASCII'</literal>),
  76         or an integer encoding number, or <literal>DEFAULT</literal>
  77         to use the default encoding.
  78        </para>
  79       </listitem>
  80      </varlistentry>
  81     </variablelist>
  82    </para>
  83   </refsect2>
  84
  85   <refsect2 id="R2-SQL-CREATEDATABASE-2">
  86    <refsect2info>
  87     <date>1999-12-11</date>
  88    </refsect2info>
  89    <title>
  90     Outputs
  91    </title>
  92    <para>
  93
  94     <variablelist>
  95      <varlistentry>
  96       <term><computeroutput>CREATE DATABASE</computeroutput></term>
  97       <listitem>
  98        <para>
  99         Message returned if the command completes successfully.
 100        </para>
 101       </listitem>
 102      </varlistentry>
 103
 104      <varlistentry>
 105       <term><computeroutput>ERROR:  user '<replaceable class="parameter">username</replaceable>' is not allowed to create/drop databases</computeroutput></term>
 106       <listitem>
 107        <para>
 108         You must have the special CREATEDB privilege to create databases.
 109         See <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">.
 110        </para>
 111       </listitem>
 112      </varlistentry>
 113
 114
 115      <varlistentry>
 116       <term><computeroutput>ERROR:  createdb: database "<replaceable class="parameter">name</replaceable>" already exists</computeroutput></term>
 117       <listitem>
 118        <para>
 119         This occurs if a database with the <replaceable class="parameter">name</replaceable>
 120         specified already exists.
 121        </para>
 122       </listitem>
 123      </varlistentry>
 124
 125      <varlistentry>
 126       <term><computeroutput>ERROR:  database path may not contain single quotes</computeroutput></term>
 127       <listitem>
 128        <para>
 129         The database location
 130         <replaceable class="parameter">dbpath</replaceable> cannot contain
 131         single quotes. This is required so that the shell commands that
 132         create the database directory can execute safely.
 133        </para>
 134       </listitem>
 135      </varlistentry>
 136
 137      <varlistentry>
 138       <term><computeroutput>ERROR:  CREATE DATABASE: may not be called in a transaction block</computeroutput></term>
 139       <listitem>
 140        <para>
 141         If you have an explicit transaction block in progress you cannot call
 142         <command>CREATE DATABASE</command>. You must finish the transaction first.
 143        </para>
 144       </listitem>
 145      </varlistentry>
 146
 147      <varlistentry>
 148       <term><computeroutput>ERROR:  Unable to create database directory '<replaceable>path</replaceable>'.</computeroutput></term>
 149       <term><computeroutput>ERROR:  Could not initialize database directory.</computeroutput></term>
 150       <listitem>
 151        <para>
 152         These are most likely related to insufficient permissions on the data
 153         directory, a full disk, or other file system problems. The user under
 154         which the database server is running must have access to the location.
 155        </para>
 156       </listitem>
 157      </varlistentry>
 158
 159     </variablelist>
 160    </para>
 161   </refsect2>
 162  </refsynopsisdiv>
 163
 164  <refsect1 id="R1-SQL-CREATEDATABASE-1">
 165   <refsect1info>
 166    <date>1999-12-11</date>
 167   </refsect1info>
 168   <title>
 169    Description
 170   </title>
 171   <para>
 172    <command>CREATE DATABASE</command> creates a new
 173    <productname>Postgres</productname> database.
 174    The creator becomes the owner of the new database.
 175   </para>
 176
 177   <para>
 178    An alternate location can be specified in order to,
 179    for example, store the database on a different disk.
 180    The path must have been prepared with the
 181    <xref linkend="APP-INITLOCATION" endterm="APP-INITLOCATION-title">
 182    command.
 183   </para>
 184   <para>
 185    If the path name does not contain a slash, it is interpreted
 186    as an environment variable name, which must be known to the
 187    server process. This way the database administrator can
 188    exercise control over locations in which databases can be created.
 189    (A customary choice is, e.g., <envar>PGDATA2</envar>.)
 190    If the server is compiled with <literal>ALLOW_ABSOLUTE_DBPATHS</literal>
 191    (not so by default), absolute path names, as identified by
 192    a leading slash
 193    (e.g., <filename>/usr/local/pgsql/data</filename>),
 194    are allowed as well.
 195   </para>
 196
 197   <para>
 198    By default, the new database will be created by cloning the standard
 199    system database <literal>template1</>.  A different template can be
 200    specified by writing <literal>TEMPLATE =</>
 201    <replaceable class="parameter">name</replaceable>.  In particular,
 202    by writing <literal>TEMPLATE = template0</>, you can create a virgin
 203    database containing only the standard objects predefined by your
 204    version of Postgres.  This is useful if you wish to avoid copying
 205    any installation-local objects that may have been added to
 206    <literal>template1</>.
 207   </para>
 208
 209   <para>
 210    The optional encoding parameter allows selection of the database encoding,
 211    if your server was compiled with multibyte encoding support.  When not
 212    specified, it defaults to the encoding used by the selected template
 213    database.
 214   </para>
 215
 216   <para>
 217    Optional parameters can be written in any order, not only the order
 218    illustrated above.
 219   </para>
 220
 221   <refsect2 id="R2-SQL-CREATEDATABASE-3">
 222    <refsect2info>
 223     <date>1999-12-11</date>
 224    </refsect2info>
 225    <title>
 226     Notes
 227    </title>
 228    <para>
 229     <command>CREATE DATABASE</command> is a <productname>Postgres</productname>
 230     language extension.
 231    </para>
 232    <para>
 233     Use <xref linkend="SQL-DROPDATABASE" endterm="SQL-DROPDATABASE-title"> to remove a database.
 234    </para>
 235    <para>
 236     The program <xref linkend="APP-CREATEDB" endterm="APP-CREATEDB-title"> is a
 237     shell script wrapper around this command, provided for convenience.
 238    </para>
 239
 240    <para>
 241     There are security and data integrity issues
 242     involved with using alternate database locations
 243     specified with absolute path names, and by default
 244     only an environment variable known to the backend may be
 245     specified for an alternate location.
 246     See the Administrator's Guide for more information.
 247    </para>
 248
 249 <!--
 250 comment from Olly; response from Thomas...
 251   <comment>
 252    initlocation does not create a PG_VERSION file in the specified location.
 253    How will Postgres handle the situation if it is upgraded to an
 254    incompatible database version?
 255   </comment>
 256    Hmm. This isn't an issue since the upgrade would do
 257    a dump/reload from the main database area also.
 258    Not sure if the dump/reload would guarantee that
 259    the alternate data area gets refreshed though...
 260 -->
 261
 262   <para>
 263    Although it is possible to copy a database other than <literal>template1</>
 264    by specifying its name as the template, this is not (yet) intended as
 265    a general-purpose COPY DATABASE facility.
 266    We recommend that databases used as templates be treated as read-only.
 267    See the <citetitle>Administrator's Guide</> for more information.
 268   </para>
 269   </refsect2>
 270  </refsect1>
 271
 272  <refsect1 id="R1-SQL-CREATEDATABASE-2">
 273   <title>
 274    Usage
 275   </title>
 276   <para>
 277    To create a new database:
 278
 279    <programlisting>
 280 <prompt>olly=></prompt> <userinput>create database lusiadas;</userinput>
 281    </programlisting>
 282   </para>
 283
 284   <para>
 285    To create a new database in an alternate area <filename>~/private_db</filename>:
 286
 287    <programlisting>
 288 <prompt>$</prompt> <userinput>mkdir private_db</userinput>
 289 <prompt>$</prompt> <userinput>initlocation ~/private_db</userinput>
 290 <computeroutput>Creating Postgres database system directory /home/olly/private_db/base</computeroutput>
 291
 292 <prompt>$</prompt> <userinput>psql olly</userinput>
 293 <computeroutput>
 294 Welcome to psql, the PostgreSQL interactive terminal.
 295
 296 Type:  \copyright for distribution terms
 297        \h for help with SQL commands
 298        \? for help on internal slash commands
 299        \g or terminate with semicolon to execute query
 300        \q to quit
 301
 302 <prompt>olly=></prompt></computeroutput> <userinput>CREATE DATABASE elsewhere WITH LOCATION = '/home/olly/private_db';</userinput>
 303 <computeroutput>CREATE DATABASE</computeroutput>
 304    </programlisting>
 305   </para>
 306  </refsect1>
 307
 308  <refsect1 id="R1-SQL-CREATEDATABASE-4">
 309   <title>
 310    Compatibility
 311   </title>
 312
 313   <refsect2 id="R2-SQL-CREATEDATABASE-4">
 314    <refsect2info>
 315     <date>1998-04-15</date>
 316    </refsect2info>
 317    <title>
 318     SQL92
 319    </title>
 320    <para>
 321     There is no <command>CREATE DATABASE</command> statement in SQL92.
 322     Databases are equivalent to catalogs whose creation is implementation-defined.
 323    </para>
 324   </refsect2>
 325  </refsect1>
 326 </refentry>
 327
 328 <!-- Keep this comment at the end of the file
 329 Local variables:
 330 mode: sgml
 331 sgml-omittag:nil
 332 sgml-shorttag:t
 333 sgml-minimize-attributes:nil
 334 sgml-always-quote-attributes:t
 335 sgml-indent-step:1
 336 sgml-indent-data:t
 337 sgml-parent-document:nil
 338 sgml-default-dtd-file:"../reference.ced"
 339 sgml-exposed-tags:nil
 340 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 341 sgml-local-ecat-files:nil
 342 End:
 343 -->