begriffs open source - ai-pg/blob - full-docs/src/sgml/html/app-createdb.html

   1 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><title>createdb</title><link rel="stylesheet" type="text/css" href="stylesheet.css" /><link rev="made" href="pgsql-docs@lists.postgresql.org" /><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot" /><link rel="prev" href="app-clusterdb.html" title="clusterdb" /><link rel="next" href="app-createuser.html" title="createuser" /></head><body id="docContent" class="container-fluid col-10"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="5" align="center"><span class="application">createdb</span></th></tr><tr><td width="10%" align="left"><a accesskey="p" href="app-clusterdb.html" title="clusterdb">Prev</a> </td><td width="10%" align="left"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><th width="60%" align="center">PostgreSQL Client Applications</th><td width="10%" align="right"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="10%" align="right"> <a accesskey="n" href="app-createuser.html" title="createuser">Next</a></td></tr></table><hr /></div><div class="refentry" id="APP-CREATEDB"><div class="titlepage"></div><a id="id-1.9.4.4.1" class="indexterm"></a><div class="refnamediv"><h2><span class="refentrytitle"><span class="application">createdb</span></span></h2><p>createdb — create a new <span class="productname">PostgreSQL</span> database</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p id="id-1.9.4.4.4.1"><code class="command">createdb</code> [<em class="replaceable"><code>connection-option</code></em>...] [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>dbname</code></em>
   3     [<em class="replaceable"><code>description</code></em>]]</p></div></div><div class="refsect1" id="R1-APP-CREATEDB-1"><h2>Description</h2><p>
   4    <span class="application">createdb</span> creates a new <span class="productname">PostgreSQL</span>
   5    database.
   6   </p><p>
   7    Normally, the database user who executes this command becomes the owner of
   8    the new database.
   9    However, a different owner can be specified via the <code class="option">-O</code>
  10    option, if the executing user has appropriate privileges.
  11   </p><p>
  12    <span class="application">createdb</span> is a wrapper around the
  13    <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>.
  14    There is no effective difference between creating databases via
  15    this utility and via other methods for accessing the server.
  16   </p></div><div class="refsect1" id="id-1.9.4.4.6"><h2>Options</h2><p>
  17    <span class="application">createdb</span> accepts the following command-line arguments:
  18
  19     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
  20         Specifies the name of the database to be created.  The name must be
  21         unique among all <span class="productname">PostgreSQL</span> databases in this cluster.
  22         The default is to create a database with the same name as the
  23         current system user.
  24        </p></dd><dt><span class="term"><em class="replaceable"><code>description</code></em></span></dt><dd><p>
  25         Specifies a comment to be associated with the newly created
  26         database.
  27        </p></dd><dt><span class="term"><code class="option">-D <em class="replaceable"><code>tablespace</code></em></code><br /></span><span class="term"><code class="option">--tablespace=<em class="replaceable"><code>tablespace</code></em></code></span></dt><dd><p>
  28         Specifies the default tablespace for the database. (This name
  29         is processed as a double-quoted identifier.)
  30        </p></dd><dt><span class="term"><code class="option">-e</code><br /></span><span class="term"><code class="option">--echo</code></span></dt><dd><p>
  31         Echo the commands that <span class="application">createdb</span> generates
  32         and sends to the server.
  33        </p></dd><dt><span class="term"><code class="option">-E <em class="replaceable"><code>encoding</code></em></code><br /></span><span class="term"><code class="option">--encoding=<em class="replaceable"><code>encoding</code></em></code></span></dt><dd><p>
  34         Specifies the character encoding scheme to be used in this
  35         database. The character sets supported by the
  36         <span class="productname">PostgreSQL</span> server are described in
  37         <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="23.3.1. Supported Character Sets">Section 23.3.1</a>.
  38        </p></dd><dt><span class="term"><code class="option">-l <em class="replaceable"><code>locale</code></em></code><br /></span><span class="term"><code class="option">--locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
  39         Specifies the locale to be used in this database.  This is equivalent
  40         to specifying <code class="option">--lc-collate</code>,
  41         <code class="option">--lc-ctype</code>, and <code class="option">--icu-locale</code> to the
  42         same value. Some locales are only valid for ICU and must be set with
  43         <code class="option">--icu-locale</code>.
  44        </p></dd><dt><span class="term"><code class="option">--lc-collate=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
  45         Specifies the LC_COLLATE setting to be used in this database.
  46        </p></dd><dt><span class="term"><code class="option">--lc-ctype=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
  47         Specifies the LC_CTYPE setting to be used in this database.
  48        </p></dd><dt><span class="term"><code class="option">--builtin-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
  49         Specifies the locale name when the builtin provider is used. Locale support
  50         is described in <a class="xref" href="locale.html" title="23.1. Locale Support">Section 23.1</a>.
  51        </p></dd><dt><span class="term"><code class="option">--icu-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
  52         Specifies the ICU locale ID to be used in this database, if the
  53         ICU locale provider is selected.
  54        </p></dd><dt><span class="term"><code class="option">--icu-rules=<em class="replaceable"><code>rules</code></em></code></span></dt><dd><p>
  55         Specifies additional collation rules to customize the behavior of the
  56         default collation of this database.  This is supported for ICU only.
  57        </p></dd><dt><span class="term"><code class="option">--locale-provider={<code class="literal">builtin</code>|<code class="literal">libc</code>|<code class="literal">icu</code>}</code></span></dt><dd><p>
  58         Specifies the locale provider for the database's default collation.
  59        </p></dd><dt><span class="term"><code class="option">-O <em class="replaceable"><code>owner</code></em></code><br /></span><span class="term"><code class="option">--owner=<em class="replaceable"><code>owner</code></em></code></span></dt><dd><p>
  60         Specifies the database user who will own the new database.
  61         (This name is processed as a double-quoted identifier.)
  62        </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>strategy</code></em></code><br /></span><span class="term"><code class="option">--strategy=<em class="replaceable"><code>strategy</code></em></code></span></dt><dd><p>
  63         Specifies the database creation strategy.  See
  64         <a class="xref" href="sql-createdatabase.html#CREATE-DATABASE-STRATEGY">CREATE DATABASE STRATEGY</a> for more details.
  65        </p></dd><dt><span class="term"><code class="option">-T <em class="replaceable"><code>template</code></em></code><br /></span><span class="term"><code class="option">--template=<em class="replaceable"><code>template</code></em></code></span></dt><dd><p>
  66         Specifies the template database from which to build this
  67         database.  (This name is processed as a double-quoted identifier.)
  68        </p></dd><dt><span class="term"><code class="option">-V</code><br /></span><span class="term"><code class="option">--version</code></span></dt><dd><p>
  69        Print the <span class="application">createdb</span> version and exit.
  70        </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
  71       Show help about <span class="application">createdb</span> command line
  72       arguments, and exit.
  73       </p></dd></dl></div><p>
  74    </p><p>
  75     The options <code class="option">-D</code>, <code class="option">-l</code>, <code class="option">-E</code>,
  76     <code class="option">-O</code>, and
  77     <code class="option">-T</code> correspond to options of the underlying
  78     SQL command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>; see there for more information
  79     about them.
  80    </p><p>
  81     <span class="application">createdb</span> also accepts the following
  82     command-line arguments for connection parameters:
  83
  84     </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="option">-h <em class="replaceable"><code>host</code></em></code><br /></span><span class="term"><code class="option">--host=<em class="replaceable"><code>host</code></em></code></span></dt><dd><p>
  85         Specifies the host name of the machine on which the
  86         server is running.  If the value begins with a slash, it is used
  87         as the directory for the Unix domain socket.
  88        </p></dd><dt><span class="term"><code class="option">-p <em class="replaceable"><code>port</code></em></code><br /></span><span class="term"><code class="option">--port=<em class="replaceable"><code>port</code></em></code></span></dt><dd><p>
  89         Specifies the TCP port or the local Unix domain socket file
  90         extension on which the server is listening for connections.
  91        </p></dd><dt><span class="term"><code class="option">-U <em class="replaceable"><code>username</code></em></code><br /></span><span class="term"><code class="option">--username=<em class="replaceable"><code>username</code></em></code></span></dt><dd><p>
  92         User name to connect as.
  93        </p></dd><dt><span class="term"><code class="option">-w</code><br /></span><span class="term"><code class="option">--no-password</code></span></dt><dd><p>
  94         Never issue a password prompt.  If the server requires
  95         password authentication and a password is not available by
  96         other means such as a <code class="filename">.pgpass</code> file, the
  97         connection attempt will fail.  This option can be useful in
  98         batch jobs and scripts where no user is present to enter a
  99         password.
 100        </p></dd><dt><span class="term"><code class="option">-W</code><br /></span><span class="term"><code class="option">--password</code></span></dt><dd><p>
 101         Force <span class="application">createdb</span> to prompt for a
 102         password before connecting to a database.
 103        </p><p>
 104         This option is never essential, since
 105         <span class="application">createdb</span> will automatically prompt
 106         for a password if the server demands password authentication.
 107         However, <span class="application">createdb</span> will waste a
 108         connection attempt finding out that the server wants a password.
 109         In some cases it is worth typing <code class="option">-W</code> to avoid the extra
 110         connection attempt.
 111        </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
 112          Specifies the name of the database to connect to when creating the
 113          new database. If not specified, the <code class="literal">postgres</code>
 114          database will be used; if that does not exist (or if it is the name
 115          of the new database being created), <code class="literal">template1</code> will
 116          be used.
 117          This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="32.1.1. Connection Strings">connection
 118          string</a>.  If so, connection string parameters will override any
 119          conflicting command line options.
 120        </p></dd></dl></div><p>
 121    </p></div><div class="refsect1" id="id-1.9.4.4.7"><h2>Environment</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">PGDATABASE</code></span></dt><dd><p>
 122       If set, the name of the database to create, unless overridden on
 123       the command line.
 124      </p></dd><dt><span class="term"><code class="envar">PGHOST</code><br /></span><span class="term"><code class="envar">PGPORT</code><br /></span><span class="term"><code class="envar">PGUSER</code></span></dt><dd><p>
 125       Default connection parameters.  <code class="envar">PGUSER</code> also
 126       determines the name of the database to create, if it is not
 127       specified on the command line or by <code class="envar">PGDATABASE</code>.
 128      </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
 129       Specifies whether to use color in diagnostic messages. Possible values
 130       are <code class="literal">always</code>, <code class="literal">auto</code> and
 131       <code class="literal">never</code>.
 132      </p></dd></dl></div><p>
 133    This utility, like most other <span class="productname">PostgreSQL</span> utilities,
 134    also uses the environment variables supported by <span class="application">libpq</span>
 135    (see <a class="xref" href="libpq-envars.html" title="32.15. Environment Variables">Section 32.15</a>).
 136   </p></div><div class="refsect1" id="id-1.9.4.4.8"><h2>Diagnostics</h2><p>
 137    In case of difficulty, see <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>
 138    and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> for
 139    discussions of potential problems and error messages.
 140    The database server must be running at the
 141    targeted host.  Also, any default connection settings and environment
 142    variables used by the <span class="application">libpq</span> front-end
 143    library will apply.
 144   </p></div><div class="refsect1" id="id-1.9.4.4.9"><h2>Examples</h2><p>
 145     To create the database <code class="literal">demo</code> using the default
 146     database server:
 147 </p><pre class="screen">
 148 <code class="prompt">$ </code><strong class="userinput"><code>createdb demo</code></strong>
 149 </pre><p>
 150    </p><p>
 151     To create the database <code class="literal">demo</code> using the
 152     server on host <code class="literal">eden</code>, port 5000, using the
 153     <code class="literal">template0</code> template database,  here is the
 154     command-line command and the underlying SQL command:
 155 </p><pre class="screen">
 156 <code class="prompt">$ </code><strong class="userinput"><code>createdb -p 5000 -h eden -T template0 -e demo</code></strong>
 157 <code class="computeroutput">CREATE DATABASE demo TEMPLATE template0;</code>
 158 </pre></div><div class="refsect1" id="id-1.9.4.4.10"><h2>See Also</h2><span class="simplelist"><a class="xref" href="app-dropdb.html" title="dropdb"><span class="refentrytitle"><span class="application">dropdb</span></span></a>, <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a></span></div></div><div class="navfooter"><hr /><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="app-clusterdb.html" title="clusterdb">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="reference-client.html" title="PostgreSQL Client Applications">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="app-createuser.html" title="createuser">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="application">clusterdb</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html" title="PostgreSQL 18.0 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">createuser</span></td></tr></table></div></body></html>