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
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
|
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>createuser</title>
<link rel="stylesheet" href="stylesheet.css" type="text/css">
<link rev="made" href="pgsql-docs@postgresql.org">
<meta name="generator" content="DocBook XSL Stylesheets V1.70.0">
<link rel="start" href="index.html" title="PostgreSQL 8.1.4 Documentation">
<link rel="up" href="reference-client.html" title="PostgreSQL Client Applications">
<link rel="prev" href="app-createlang.html" title="createlang">
<link rel="next" href="app-dropdb.html" title="dropdb">
<link rel="copyright" href="ln-legalnotice.html" title="Legal Notice">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="refentry" lang="en">
<a name="app-createuser"></a><div class="titlepage"></div>
<div class="refnamediv">
<h2>Name</h2>
<p>createuser — define a new <span class="productname">PostgreSQL</span> user account</p>
</div>
<a name="id793000"></a><div class="refsynopsisdiv">
<h2>Synopsis</h2>
<div class="cmdsynopsis"><p><code class="command">createuser</code> [<em class="replaceable"><code>option</code></em>...] [<em class="replaceable"><code>username</code></em>]</p></div>
</div>
<div class="refsect1" lang="en">
<a name="id793036"></a><h2>Description</h2>
<p> <span class="application">createuser</span> creates a
new <span class="productname">PostgreSQL</span> user (or more precisely, a role).
Only superusers and users with <code class="literal">CREATEROLE</code> privilege can create
new users, so <span class="application">createuser</span> must be
invoked by someone who can connect as a superuser or a user with
<code class="literal">CREATEROLE</code> privilege.
</p>
<p> If you wish to create a new superuser, you must connect as a
superuser, not merely with <code class="literal">CREATEROLE</code> privilege.
Being a superuser implies the ability to bypass all access permission
checks within the database, so superuserdom should not be granted lightly.
</p>
<p> <span class="application">createuser</span> is a wrapper around the
<acronym class="acronym">SQL</acronym> command <a href="sql-createrole.html">CREATE ROLE</a>.
There is no effective difference between creating users via
this utility and via other methods for accessing the server.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id793119"></a><h2>Options</h2>
<p> <span class="application">createuser</span> accepts the following command-line arguments:
</p>
<div class="variablelist"><dl>
<dt><span class="term"><em class="replaceable"><code>username</code></em></span></dt>
<dd><p> Specifies the name of the <span class="productname">PostgreSQL</span> user
to be created.
This name must be different from all existing roles in this
<span class="productname">PostgreSQL</span> installation.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-s</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--superuser</code></span>
</dt>
<dd><p> The new user will be a superuser.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-S</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--no-superuser</code></span>
</dt>
<dd><p> The new user will not be a superuser.
This is the default.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-d</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--createdb</code></span>
</dt>
<dd><p> The new user will be allowed to create databases.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-D</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--no-createdb</code></span>
</dt>
<dd><p> The new user will not be allowed to create databases.
This is the default.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-r</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--createrole</code></span>
</dt>
<dd><p> The new user will be allowed to create new roles (that is,
this user will have <code class="literal">CREATEROLE</code> privilege).
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-R</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--no-createrole</code></span>
</dt>
<dd><p> The new user will not be allowed to create new roles.
This is the default.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-l</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--login</code></span>
</dt>
<dd><p> The new user will be allowed to log in (that is, the user name
can be used as the initial session user identifier).
This is the default.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-L</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--no-login</code></span>
</dt>
<dd><p> The new user will not be allowed to log in.
(A role without login privilege is still useful as a means of
managing database permissions.)
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-i</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--inherit</code></span>
</dt>
<dd><p> The new role will automatically inherit privileges of roles
it is a member of.
This is the default.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-I</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--no-inherit</code></span>
</dt>
<dd><p> The new role will not automatically inherit privileges of roles
it is a member of.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-c <em class="replaceable"><code>number</code></em></code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--connection-limit <em class="replaceable"><code>number</code></em></code></span>
</dt>
<dd><p> Set a maximum number of connections for the new user.
The default is to set no limit.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-P</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--pwprompt</code></span>
</dt>
<dd><p> If given, <span class="application">createuser</span> will issue a prompt for
the password of the new user. This is not necessary if you do not plan
on using password authentication.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-E</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--encrypted</code></span>
</dt>
<dd><p> Encrypts the user's password stored in the database. If not
specified, the default password behavior is used.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-N</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--unencrypted</code></span>
</dt>
<dd><p> Does not encrypt the user's password stored in the database. If
not specified, the default password behavior is used.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-e</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--echo</code></span>
</dt>
<dd><p> Echo the commands that <span class="application">createuser</span> generates
and sends to the server.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-q</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--quiet</code></span>
</dt>
<dd><p> Do not display a response.
</p></dd>
</dl></div>
<p>
</p>
<p> You will be prompted for a name and other missing information if it
is not specified on the command line.
</p>
<p> <span class="application">createuser</span> also accepts the following
command-line arguments for connection parameters:
</p>
<div class="variablelist"><dl>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-h <em class="replaceable"><code>host</code></em></code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><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 xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-p <em class="replaceable"><code>port</code></em></code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--port <em class="replaceable"><code>port</code></em></code></span>
</dt>
<dd><p> Specifies the TCP port or local Unix domain socket file
extension on which the server
is listening for connections.
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-U <em class="replaceable"><code>username</code></em></code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--username <em class="replaceable"><code>username</code></em></code></span>
</dt>
<dd><p> User name to connect as (not the user name to create).
</p></dd>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="option">-W</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="option">--password</code></span>
</dt>
<dd><p> Force password prompt (to connect to the server, not for the
password of the new user).
</p></dd>
</dl></div>
<p>
</p>
</div>
<div class="refsect1" lang="en">
<a name="id793532"></a><h2>Environment</h2>
<div class="variablelist"><dl>
<dt>
<span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="envar">PGHOST</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span xmlns="http://www.w3.org/TR/xhtml1/transitional" class="term"><code xmlns="" class="envar">PGPORT</code></span><br xmlns="http://www.w3.org/TR/xhtml1/transitional"></br><span class="term"><code class="envar">PGUSER</code></span>
</dt>
<dd><p> Default connection parameters
</p></dd>
</dl></div>
</div>
<div class="refsect1" lang="en">
<a name="id793554"></a><h2>Diagnostics</h2>
<p> In case of difficulty, see <a href="sql-createrole.html">CREATE ROLE</a> and <a href="app-psql.html" title="psql"><span class="refentrytitle"><a name="app-psql-title"></a><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" lang="en">
<a name="id793589"></a><h2>Examples</h2>
<p> To create a user <code class="literal">joe</code> on the default database
server:
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>createuser joe</code></strong>
<code class="computeroutput">Shall the new role be a superuser? (y/n) </code><strong class="userinput"><code>n</code></strong>
<code class="computeroutput">Shall the new role be allowed to create databases? (y/n) </code><strong class="userinput"><code>n</code></strong>
<code class="computeroutput">Shall the new role be allowed to create more new roles? (y/n) </code><strong class="userinput"><code>n</code></strong>
<code class="computeroutput">CREATE USER</code></pre>
<p>
</p>
<p> To create the same user <code class="literal">joe</code> using the
server on host <code class="literal">eden</code>, port 5000, avoiding the prompts and
taking a look at the underlying command:
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>createuser -h eden -p 5000 -S -D -R -e joe</code></strong>
<code class="computeroutput">CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</code>
<code class="computeroutput">CREATE ROLE</code></pre>
<p>
</p>
<p> To create the user <code class="literal">joe</code> as a superuser,
and assign a password immediately:
</p>
<pre class="screen"><code class="prompt">$ </code><strong class="userinput"><code>createuser -P -s -e joe</code></strong>
<code class="computeroutput">Enter password for new role: </code><strong class="userinput"><code>xyzzy</code></strong>
<code class="computeroutput">Enter it again: </code><strong class="userinput"><code>xyzzy</code></strong>
<code class="computeroutput">CREATE ROLE joe PASSWORD 'xyzzy' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</code>
<code class="computeroutput">CREATE ROLE</code></pre>
<p>
In the above example, the new password isn't actually echoed when typed,
but we show what was typed for clarity. However the password
<span class="emphasis"><em>will</em></span> appear in the echoed command, as illustrated [mdash ]
so you don't want to use <code class="literal">-e</code> when assigning a password, if
anyone else can see your screen.
</p>
</div>
<div class="refsect1" lang="en">
<a name="id793785"></a><h2>See Also</h2>
<span class="simplelist"><a href="app-dropuser.html" title="dropuser"><span class="refentrytitle"><a name="app-dropuser-title"></a><span class="application">dropuser</span></span></a>, <a href="sql-createrole.html">CREATE ROLE</a>, Environment Variables (<a href="libpq-envars.html" title="28.11.Environment Variables">Section28.11, “Environment Variables”</a>)</span>
</div>
</div></body>
</html>
|
