| <!-- |
| $PostgreSQL: pgsql/doc/src/sgml/ref/createdb.sgml,v 1.42.2.2 2007/03/26 17:23:44 tgl 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> |
| |
| <indexterm zone="app-createdb"> |
| <primary>createdb</primary> |
| </indexterm> |
| |
| <refsynopsisdiv> |
| <cmdsynopsis> |
| <command>createdb</command> |
| <arg rep="repeat"><replaceable>option</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 wrapper around the |
| <acronym>SQL</acronym> command <xref linkend="SQL-CREATEDATABASE" |
| endterm="SQL-CREATEDATABASE-title">. |
| There is no effective difference between creating databases via |
| this utility and via other methods for accessing the server. |
| </para> |
| |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>Options</title> |
| |
| <para> |
| <application>createdb</application> accepts the following command-line arguments: |
| |
| <variablelist> |
| <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 cluster. |
| 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> |
| Specifies a comment to be associated with the newly created |
| database. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-D <replaceable class="parameter">tablespace</replaceable></></term> |
| <term><option>--tablespace <replaceable class="parameter">tablespace</replaceable></></term> |
| <listitem> |
| <para> |
| Specifies the default tablespace for the database. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>-e</></term> |
| <term><option>--echo</></term> |
| <listitem> |
| <para> |
| Echo the commands that <application>createdb</application> generates |
| and sends to the server. |
| </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. The character sets supported by the |
| <productname>PostgreSQL</productname> server are described in |
| <xref linkend="multibyte-charset-supported">. |
| </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>-q</></term> |
| <term><option>--quiet</></term> |
| <listitem> |
| <para> |
| Do not display a response. |
| </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> |
| </variablelist> |
| </para> |
| |
| <para> |
| The options <option>-D</option>, <option>-E</option>, |
| <option>-O</option>, and |
| <option>-T</option> correspond to options of the underlying |
| SQL command <xref linkend="SQL-CREATEDATABASE" |
| endterm="SQL-CREATEDATABASE-title">; see there for more information |
| about them. |
| </para> |
| |
| <para> |
| <application>createdb</application> also accepts the following |
| command-line arguments for connection parameters: |
| |
| <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 the value 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 TCP 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> |
| </variablelist> |
| </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> |
| |
| <para> |
| This utility, like most other <productname>PostgreSQL</> utilities, |
| also uses the environment variables supported by <application>libpq</> |
| (see <xref linkend="libpq-envars">). |
| </para> |
| |
| </refsect1> |
| |
| |
| <refsect1> |
| <title>Diagnostics</title> |
| |
| <para> |
| In case of difficulty, see <xref linkend="SQL-CREATEDATABASE" |
| endterm="sql-createdatabase-title"> and <xref linkend="APP-PSQL"> for |
| discussions of potential problems and error messages. |
| The database server must be running at the |
| targeted host. Also, any default connection settings and environment |
| variables used by the <application>libpq</application> front-end |
| library will apply. |
| </para> |
| |
| </refsect1> |
| |
| |
| <refsect1> |
| <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 command: |
| <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> |