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

   1 <!--
   2 $Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.10 2000/03/27 17:14:42 thomas Exp $
   3 Postgres documentation
   4 -->
   5
   6 <refentry id="APP-CREATEDB" xreflabel="createdb">
   7  <refmeta>
   8   <refentrytitle id="APP-CREATEDB-TITLE">
   9    <application>createdb</application>
  10   </refentrytitle>
  11   <refmiscinfo>Application</refmiscinfo>
  12  </refmeta>
  13  <refnamediv>
  14   <refname>
  15    <application>createdb</application>
  16   </refname>
  17   <refpurpose>
  18    Create a new <productname>Postgres</productname> database
  19   </refpurpose>
  20  </refnamediv>
  21  <refsynopsisdiv>
  22   <refsynopsisdivinfo>
  23    <date>1999-11-07</date>
  24   </refsynopsisdivinfo>
  25   <synopsis>
  26 createdb [ <replaceable class="parameter">options</replaceable> ] <replaceable class="parameter">dbname</replaceable> [ <replaceable class="parameter">description</replaceable> ]
  27   </synopsis>
  28
  29   <refsect2 id="R2-APP-CREATEDB-1">
  30    <refsect2info>
  31     <date>1999-11-07</date>
  32    </refsect2info>
  33    <title>
  34     Inputs
  35    </title>
  36    <para>
  37
  38     <variablelist>
  39      <varlistentry>
  40       <term>-h, --host <replaceable class="parameter">host</replaceable></term>
  41       <listitem>
  42        <para>
  43         Specifies the hostname of the machine on which the
  44         <application>postmaster</application>
  45         is running.
  46        </para>
  47       </listitem>
  48      </varlistentry>
  49
  50      <varlistentry>
  51       <term>-p, --port <replaceable class="parameter">port</replaceable></term>
  52       <listitem>
  53        <para>
  54         Specifies the Internet TCP/IP port or local Unix domain socket file
  55         extension on which the <application>postmaster</application>
  56         is listening for connections.
  57        </para>
  58       </listitem>
  59      </varlistentry>
  60
  61      <varlistentry>
  62       <term>-U, --username <replaceable class="parameter">username</replaceable></term>
  63       <listitem>
  64        <para>
  65         Username to connect as.
  66        </para>
  67       </listitem>
  68      </varlistentry>
  69
  70      <varlistentry>
  71       <term>-W, --password</term>
  72       <listitem>
  73        <para>
  74         Force password prompt.
  75        </para>
  76       </listitem>
  77      </varlistentry>
  78
  79      <varlistentry>
  80       <term>-e, --echo</term>
  81       <listitem>
  82        <para>
  83         Echo the queries that <application>createdb</application> generates
  84         and sends to the backend.
  85        </para>
  86       </listitem>
  87      </varlistentry>
  88
  89      <varlistentry>
  90       <term>-q, --quiet</term>
  91       <listitem>
  92        <para>
  93         Do not display a response.
  94        </para>
  95       </listitem>
  96      </varlistentry>
  97
  98      <varlistentry>
  99       <term>-D, --location <replaceable class="parameter">datadir</replaceable></term>
 100       <listitem>
 101        <para>
 102         Specifies the alternate database location for this database installation.
 103         This is the location of the installation system tables, not the location
 104         of this specific database, which may be different.
 105        </para>
 106       </listitem>
 107      </varlistentry>
 108
 109      <varlistentry>
 110       <term>-E, --encoding <replaceable class="parameter">encoding</replaceable></term>
 111       <listitem>
 112        <para>
 113         Specifies the character encoding scheme to be used with this database.
 114        </para>
 115       </listitem>
 116      </varlistentry>
 117
 118      <varlistentry>
 119       <term><replaceable class="parameter">dbname</replaceable></term>
 120       <listitem>
 121        <para>
 122         Specifies the name of the database to be created.  The name must be
 123         unique among all <productname>Postgres</productname> databases in this installation.
 124         The default is to create a database with the same name as the
 125         current system user.
 126        </para>
 127       </listitem>
 128      </varlistentry>
 129
 130      <varlistentry>
 131       <term><replaceable class="parameter">description</replaceable></term>
 132       <listitem>
 133        <para>
 134         This optionally specifies a comment to be associated with the newly created
 135         database.
 136        </para>
 137       </listitem>
 138      </varlistentry>
 139
 140     </variablelist>
 141
 142     The options <literal>-h</literal>, <literal>-p</literal>, <literal>-U</literal>,
 143     <literal>-W</literal>, and <literal>-e</literal> are passed on literally to
 144     <xref linkend="APP-PSQL" endterm="APP-PSQL-title">.
 145    </para>
 146   </refsect2>
 147
 148   <refsect2 id="R2-APP-CREATEDB-2">
 149    <refsect2info>
 150     <date>1999-11-07</date>
 151    </refsect2info>
 152    <title>
 153     Outputs
 154    </title>
 155    <para>
 156     <variablelist>
 157      <varlistentry>
 158       <term><computeroutput>CREATE DATABASE</computeroutput></term>
 159       <listitem>
 160        <para>The database was successfully created.</para>
 161       </listitem>
 162      </varlistentry>
 163
 164      <varlistentry>
 165       <term><computeroutput>createdb: Database creation failed.</computeroutput></term>
 166       <listitem>
 167        <para>(Says it all.)</para>
 168       </listitem>
 169      </varlistentry>
 170
 171      <varlistentry>
 172       <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term>
 173       <listitem>
 174        <para>
 175        The comment/description for the database could not be created.
 176        the database itself will have been created already. You can use the
 177        <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to
 178        create the comment later on.
 179        </para>
 180       </listitem>
 181      </varlistentry>
 182     </variablelist>
 183
 184     If there is an error condition, the backend error message will be displayed.
 185     See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title">
 186     and <xref linkend="APP-PSQL" endterm="APP-PSQL-title"> for possibilities.
 187    </para>
 188   </refsect2>
 189  </refsynopsisdiv>
 190
 191  <refsect1 id="R1-APP-CREATEDB-1">
 192   <refsect1info>
 193    <date>1999-11-07</date>
 194   </refsect1info>
 195   <title>
 196    Description
 197   </title>
 198   <para>
 199    <application>createdb</application> creates a new <productname>Postgres</productname>
 200    database. The user who executes this command becomes the database owner.
 201   </para>
 202
 203   <para>
 204    <application>createdb</application> is a shell script wrapper around the
 205    <acronym>SQL</acronym> command
 206    <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via
 207    the <productname>Postgres</productname> interactive terminal
 208    <xref linkend="APP-PSQL" endterm="APP-PSQL-title">. Thus, there is nothing
 209    special about creating databases via this or other methods. This means
 210    that the <application>psql</application> must be found by the script and that
 211    a database server is running at the targeted host. Also, any default
 212    settings and environment variables available to <application>psql</application>
 213    and the <application>libpq</application> front-end library do apply.
 214   </para>
 215  </refsect1>
 216
 217  <refsect1 id="R1-APP-CREATEDB-2">
 218   <refsect1info>
 219    <date>1999-11-07</date>
 220   </refsect1info>
 221   <title>
 222    Usage
 223   </title>
 224   <para>
 225    To create the database <literal>demo</literal>
 226    using the default database server:
 227
 228    <programlisting>
 229 $ <userinput>createdb demo</userinput>
 230 CREATE DATABASE
 231    </programlisting>
 232
 233    The response is the same as you would have gotten from running the
 234    <command>CREATE DATABASE</command> <acronym>SQL</acronym> command.
 235   </para>
 236
 237   <para>
 238    To create the database <literal>demo</literal>
 239    using the postmaster on host eden, port 5000, using the <literal>LATIN1</literal>
 240    encoding scheme with a look at the underlying query:
 241
 242    <programlisting>
 243 $ <userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput>
 244 CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'
 245 CREATE DATABASE
 246    </programlisting>
 247   </para>
 248  </refsect1>
 249 </refentry>
 250
 251 <!-- Keep this comment at the end of the file
 252 Local variables:
 253 mode: sgml
 254 sgml-omittag:nil
 255 sgml-shorttag:t
 256 sgml-minimize-attributes:nil
 257 sgml-always-quote-attributes:t
 258 sgml-indent-step:1
 259 sgml-indent-data:t
 260 sgml-parent-document:nil
 261 sgml-default-dtd-file:"../reference.ced"
 262 sgml-exposed-tags:nil
 263 sgml-local-catalogs:"/usr/lib/sgml/catalog"
 264 sgml-local-ecat-files:nil
 265 End:
 266 -->