<!-- $Header: /cvsroot/pgsql/doc/src/sgml/ref/createdb.sgml,v 1.29 2002/09/21 18:32:54 petere Exp $ PostgreSQL documentation --> <refentry id="APP-CREATEDB"> <refmeta> <refentrytitle id="APP-CREATEDB-TITLE"><application>createdb</application></refentrytitle> <manvolnum>1</manvolnum> <refmiscinfo>Application</refmiscinfo> </refmeta> <refnamediv> <refname>createdb</refname> <refpurpose>create a new <productname>PostgreSQL</productname> database</refpurpose> </refnamediv> <refsynopsisdiv> <cmdsynopsis> <command>createdb</command> <arg rep="repeat"><replaceable>options</replaceable></arg> <arg><replaceable>dbname</replaceable></arg> <arg><replaceable>description</replaceable></arg> </cmdsynopsis> </refsynopsisdiv> <refsect1 id="R1-APP-CREATEDB-1"> <title> Description </title> <para> <application>createdb</application> creates a new <productname>PostgreSQL</productname> database. </para> <para> Normally, the database user who executes this command becomes the owner of the new database. However a different owner can be specified via the <option>-O</option> option, if the executing user has appropriate privileges. </para> <para> <application>createdb</application> is a shell script wrapper around the <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title"> via the <productname>PostgreSQL</productname> interactive terminal <xref linkend="APP-PSQL">. Thus, there is nothing special about creating databases via this or other methods. This means that the <application>psql</application> program must be found by the script and that a database server must be running at the targeted port. Also, any default settings and environment variables available to <application>psql</application> and the <application>libpq</application> front-end library will apply. </para> </refsect1> <refsect1> <title>Options</title> <variablelist> <varlistentry> <term><option>-h <replaceable class="parameter">host</replaceable></></term> <term><option>--host <replaceable class="parameter">host</replaceable></></term> <listitem> <para> Specifies the host name of the machine on which the server is running. If host begins with a slash, it is used as the directory for the Unix domain socket. </para> </listitem> </varlistentry> <varlistentry> <term><option>-p <replaceable class="parameter">port</replaceable></></term> <term><option>--port <replaceable class="parameter">port</replaceable></></term> <listitem> <para> Specifies the Internet TCP/IP port or the local Unix domain socket file extension on which the server is listening for connections. </para> </listitem> </varlistentry> <varlistentry> <term><option>-U <replaceable class="parameter">username</replaceable></></term> <term><option>--username <replaceable class="parameter">username</replaceable></></term> <listitem> <para> User name to connect as </para> </listitem> </varlistentry> <varlistentry> <term><option>-W</></term> <term><option>--password</></term> <listitem> <para> Force password prompt. </para> </listitem> </varlistentry> <varlistentry> <term><option>-e</></term> <term><option>--echo</></term> <listitem> <para> Echo the queries that <application>createdb</application> generates and sends to the server. </para> </listitem> </varlistentry> <varlistentry> <term><option>-q</></term> <term><option>--quiet</></term> <listitem> <para> Do not display a response. </para> </listitem> </varlistentry> <varlistentry> <term><option>-O <replaceable class="parameter">owner</replaceable></></term> <term><option>--owner <replaceable class="parameter">owner</replaceable></></term> <listitem> <para> Specifies the database user who will own the new database. </para> </listitem> </varlistentry> <varlistentry> <term><option>-D <replaceable class="parameter">datadir</replaceable></></term> <term><option>--location <replaceable class="parameter">datadir</replaceable></></term> <listitem> <para> Specifies the alternative location for the database. See also <xref linkend="app-initlocation">. </para> </listitem> </varlistentry> <varlistentry> <term><option>-T <replaceable class="parameter">template</replaceable></></term> <term><option>--template <replaceable class="parameter">template</replaceable></></term> <listitem> <para> Specifies the template database from which to build this database. </para> </listitem> </varlistentry> <varlistentry> <term><option>-E <replaceable class="parameter">encoding</replaceable></></term> <term><option>--encoding <replaceable class="parameter">encoding</replaceable></></term> <listitem> <para> Specifies the character encoding scheme to be used in this database. </para> </listitem> </varlistentry> <varlistentry> <term><replaceable class="parameter">dbname</replaceable></term> <listitem> <para> Specifies the name of the database to be created. The name must be unique among all <productname>PostgreSQL</productname> databases in this installation. The default is to create a database with the same name as the current system user. </para> </listitem> </varlistentry> <varlistentry> <term><replaceable class="parameter">description</replaceable></term> <listitem> <para> This optionally specifies a comment to be associated with the newly created database. </para> </listitem> </varlistentry> </variablelist> <para> The options <option>-h</option>, <option>-p</option>, <option>-U</option>, <option>-W</option>, and <option>-e</option> are passed on literally to <xref linkend="app-psql">. The options <option>-O</option>, <option>-D</option>, <option>-T</option>, and <option>-E</option> are converted into options for the underlying SQL command <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-title">; see there for more information about them. </para> </refsect1> <refsect1> <title>Diagnostics</title> <variablelist> <varlistentry> <term><computeroutput>CREATE DATABASE</computeroutput></term> <listitem> <para>The database was successfully created.</para> </listitem> </varlistentry> <varlistentry> <term><computeroutput>createdb: Database creation failed.</computeroutput></term> <listitem> <para>(Says it all.)</para> </listitem> </varlistentry> <varlistentry> <term><computeroutput>createdb: Comment creation failed. (Database was created.)</computeroutput></term> <listitem> <para> The comment/description for the database could not be created. The database itself will have been created already. You can use the <acronym>SQL</acronym> command <command>COMMENT ON DATABASE</command> to create the comment later on. </para> </listitem> </varlistentry> </variablelist> <para> If there is an error condition, the backend error message will be displayed. See <xref linkend="SQL-CREATEDATABASE" endterm="SQL-CREATEDATABASE-TITLE"> and <xref linkend="APP-PSQL"> for possibilities. </para> </refsect1> <refsect1> <title>Environment</title> <variablelist> <varlistentry> <term><envar>PGDATABASE</envar></term> <listitem> <para> If set, the name of the database to create, unless overridden on the command line. </para> </listitem> </varlistentry> <varlistentry> <term><envar>PGHOST</envar></term> <term><envar>PGPORT</envar></term> <term><envar>PGUSER</envar></term> <listitem> <para> Default connection parameters. <envar>PGUSER</envar> also determines the name of the database to create, if it is not specified on the command line or by <envar>PGDATABASE</envar>. </para> </listitem> </varlistentry> </variablelist> </refsect1> <refsect1 id="R1-APP-CREATEDB-2"> <title>Examples</title> <para> To create the database <literal>demo</literal> using the default database server: <screen> <prompt>$ </prompt><userinput>createdb demo</userinput> <computeroutput>CREATE DATABASE</computeroutput> </screen> The response is the same as you would have gotten from running the <command>CREATE DATABASE</command> <acronym>SQL</acronym> command. </para> <para> To create the database <literal>demo</literal> using the server on host <literal>eden</>, port 5000, using the <literal>LATIN1</literal> encoding scheme with a look at the underlying query: <screen> <prompt>$ </prompt><userinput>createdb -p 5000 -h eden -E LATIN1 -e demo</userinput> <computeroutput>CREATE DATABASE "demo" WITH ENCODING = 'LATIN1'</computeroutput> <computeroutput>CREATE DATABASE</computeroutput> </screen> </para> </refsect1> <refsect1> <title>See Also</title> <simplelist type="inline"> <member><xref linkend="app-dropdb"></member> <member><xref linkend="sql-createdatabase" endterm="sql-createdatabase-title"></member> </simplelist> </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: -->