summaryrefslogtreecommitdiffstats
path: root/doc/src/sgml/html/app-createdb.html
blob: aad42a602942cb555ee15947ab862eda604c66fb (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!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 15.5 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>
    [<em class="replaceable"><code>description</code></em>]]</p></div></div><div class="refsect1" id="R1-APP-CREATEDB-1"><h2>Description</h2><p>
   <span class="application">createdb</span> creates a new <span class="productname">PostgreSQL</span>
   database.
  </p><p>
   Normally, the database user who executes this command becomes the owner of
   the new database.
   However, a different owner can be specified via the <code class="option">-O</code>
   option, if the executing user has appropriate privileges.
  </p><p>
   <span class="application">createdb</span> is a wrapper around the
   <acronym class="acronym">SQL</acronym> command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>.
   There is no effective difference between creating databases via
   this utility and via other methods for accessing the server.
  </p></div><div class="refsect1" id="id-1.9.4.4.6"><h2>Options</h2><p>
   <span class="application">createdb</span> accepts the following command-line arguments:

    </p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><em class="replaceable"><code>dbname</code></em></span></dt><dd><p>
        Specifies the name of the database to be created.  The name must be
        unique among all <span class="productname">PostgreSQL</span> databases in this cluster.
        The default is to create a database with the same name as the
        current system user.
       </p></dd><dt><span class="term"><em class="replaceable"><code>description</code></em></span></dt><dd><p>
        Specifies a comment to be associated with the newly created
        database.
       </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>
        Specifies the default tablespace for the database. (This name
        is processed as a double-quoted identifier.)
       </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>
        Echo the commands that <span class="application">createdb</span> generates
        and sends to the server.
       </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>
        Specifies the character encoding scheme to be used in this
        database. The character sets supported by the
        <span class="productname">PostgreSQL</span> server are described in
        <a class="xref" href="multibyte.html#MULTIBYTE-CHARSET-SUPPORTED" title="24.3.1. Supported Character Sets">Section 24.3.1</a>.
       </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>
        Specifies the locale to be used in this database.  This is equivalent
        to specifying both <code class="option">--lc-collate</code> and <code class="option">--lc-ctype</code>.
       </p></dd><dt><span class="term"><code class="option">--lc-collate=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
        Specifies the LC_COLLATE setting to be used in this database.
       </p></dd><dt><span class="term"><code class="option">--lc-ctype=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
        Specifies the LC_CTYPE setting to be used in this database.
       </p></dd><dt><span class="term"><code class="option">--icu-locale=<em class="replaceable"><code>locale</code></em></code></span></dt><dd><p>
        Specifies the ICU locale ID to be used in this database, if the
        ICU locale provider is selected.
       </p></dd><dt><span class="term"><code class="option">--locale-provider={<code class="literal">libc</code>|<code class="literal">icu</code>}</code></span></dt><dd><p>
        Specifies the locale provider for the database's default collation.
       </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>
        Specifies the database user who will own the new database.
        (This name is processed as a double-quoted identifier.)
       </p></dd><dt><span class="term"><code class="option">-S <em class="replaceable"><code>template</code></em></code><br /></span><span class="term"><code class="option">--strategy=<em class="replaceable"><code>strategy</code></em></code></span></dt><dd><p>
        Specifies the database creation strategy.  See
        <a class="xref" href="sql-createdatabase.html#CREATE-DATABASE-STRATEGY">CREATE DATABASE STRATEGY</a> for more details.
       </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>
        Specifies the template database from which to build this
        database.  (This name is processed as a double-quoted identifier.)
       </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>
       Print the <span class="application">createdb</span> version and exit.
       </p></dd><dt><span class="term"><code class="option">-?</code><br /></span><span class="term"><code class="option">--help</code></span></dt><dd><p>
      Show help about <span class="application">createdb</span> command line
      arguments, and exit.
      </p></dd></dl></div><p>
   </p><p>
    The options <code class="option">-D</code>, <code class="option">-l</code>, <code class="option">-E</code>,
    <code class="option">-O</code>, and
    <code class="option">-T</code> correspond to options of the underlying
    SQL command <a class="link" href="sql-createdatabase.html" title="CREATE DATABASE"><code class="command">CREATE DATABASE</code></a>; see there for more information
    about them.
   </p><p>
    <span class="application">createdb</span> also accepts the following
    command-line arguments for connection parameters:

    </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>
        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.
       </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>
        Specifies the TCP port or the local Unix domain socket file
        extension on which the server is listening for connections.
       </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>
        User name to connect as.
       </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>
        Never issue a password prompt.  If the server requires
        password authentication and a password is not available by
        other means such as a <code class="filename">.pgpass</code> file, the
        connection attempt will fail.  This option can be useful in
        batch jobs and scripts where no user is present to enter a
        password.
       </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>
        Force <span class="application">createdb</span> to prompt for a
        password before connecting to a database.
       </p><p>
        This option is never essential, since
        <span class="application">createdb</span> will automatically prompt
        for a password if the server demands password authentication.
        However, <span class="application">createdb</span> will waste a
        connection attempt finding out that the server wants a password.
        In some cases it is worth typing <code class="option">-W</code> to avoid the extra
        connection attempt.
       </p></dd><dt><span class="term"><code class="option">--maintenance-db=<em class="replaceable"><code>dbname</code></em></code></span></dt><dd><p>
         Specifies the name of the database to connect to when creating the
         new database. If not specified, the <code class="literal">postgres</code>
         database will be used; if that does not exist (or if it is the name
         of the new database being created), <code class="literal">template1</code> will
         be used.
         This can be a <a class="link" href="libpq-connect.html#LIBPQ-CONNSTRING" title="34.1.1. Connection Strings">connection
         string</a>.  If so, connection string parameters will override any
         conflicting command line options.
       </p></dd></dl></div><p>
   </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>
      If set, the name of the database to create, unless overridden on
      the command line.
     </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>
      Default connection parameters.  <code class="envar">PGUSER</code> also
      determines the name of the database to create, if it is not
      specified on the command line or by <code class="envar">PGDATABASE</code>.
     </p></dd><dt><span class="term"><code class="envar">PG_COLOR</code></span></dt><dd><p>
      Specifies whether to use color in diagnostic messages. Possible values
      are <code class="literal">always</code>, <code class="literal">auto</code> and
      <code class="literal">never</code>.
     </p></dd></dl></div><p>
   This utility, like most other <span class="productname">PostgreSQL</span> utilities,
   also uses the environment variables supported by <span class="application">libpq</span>
   (see <a class="xref" href="libpq-envars.html" title="34.15. Environment Variables">Section 34.15</a>).
  </p></div><div class="refsect1" id="id-1.9.4.4.8"><h2>Diagnostics</h2><p>
   In case of difficulty, see <a class="xref" href="sql-createdatabase.html" title="CREATE DATABASE"><span class="refentrytitle">CREATE DATABASE</span></a>
   and <a class="xref" href="app-psql.html" title="psql"><span class="refentrytitle"><span class="application">psql</span></span></a> 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 <span class="application">libpq</span> front-end
   library will apply.
  </p></div><div class="refsect1" id="id-1.9.4.4.9"><h2>Examples</h2><p>
    To create the database <code class="literal">demo</code> using the default
    database server:
</p><pre class="screen">
<code class="prompt">$ </code><strong class="userinput"><code>createdb demo</code></strong>
</pre><p>
   </p><p>
    To create the database <code class="literal">demo</code> using the
    server on host <code class="literal">eden</code>, port 5000, using the
    <code class="literal">template0</code> template database,  here is the
    command-line command and the underlying SQL command:
</p><pre class="screen">
<code class="prompt">$ </code><strong class="userinput"><code>createdb -p 5000 -h eden -T template0 -e demo</code></strong>
<code class="computeroutput">CREATE DATABASE demo TEMPLATE template0;</code>
</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 15.5 Documentation">Home</a></td><td width="40%" align="right" valign="top"> <span class="application">createuser</span></td></tr></table></div></body></html>