Location via proxy:   [ UP ]  
[Report a bug]   [Manage cookies]                
Skip to content

Commit 58d214e

Browse files
tglsfdctglsfdc
committed
Basic documentation for ROLEs. The user-manag chapter still needs to
be rewritten, but at least the reference pages are reasonably sane.
1 parent 0c2d7e3 commit 58d214e

15 files changed

+1061
-642
lines changed

‎doc/src/sgml/ref/allfiles.sgml

+4-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.64 2005/07/25 22:12:31 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.65 2005/07/26 23:24:02 tgl Exp $
33
PostgreSQL documentation
44
Complete list of usable sgml source files in this directory.
55
-->
@@ -16,6 +16,7 @@ Complete list of usable sgml source files in this directory.
1616
<!entity alterLanguage system "alter_language.sgml">
1717
<!entity alterOperator system "alter_operator.sgml">
1818
<!entity alterOperatorClass system "alter_opclass.sgml">
19+
<!entity alterRole system "alter_role.sgml">
1920
<!entity alterSchema system "alter_schema.sgml">
2021
<!entity alterSequence system "alter_sequence.sgml">
2122
<!entity alterTable system "alter_table.sgml">
@@ -44,6 +45,7 @@ Complete list of usable sgml source files in this directory.
4445
<!entity createLanguage system "create_language.sgml">
4546
<!entity createOperator system "create_operator.sgml">
4647
<!entity createOperatorClass system "create_opclass.sgml">
48+
<!entity createRole system "create_role.sgml">
4749
<!entity createRule system "create_rule.sgml">
4850
<!entity createSchema system "create_schema.sgml">
4951
<!entity createSequence system "create_sequence.sgml">
@@ -68,6 +70,7 @@ Complete list of usable sgml source files in this directory.
6870
<!entity dropLanguage system "drop_language.sgml">
6971
<!entity dropOperator system "drop_operator.sgml">
7072
<!entity dropOperatorClass system "drop_opclass.sgml">
73+
<!entity dropRole system "drop_role.sgml">
7174
<!entity dropRule system "drop_rule.sgml">
7275
<!entity dropSchema system "drop_schema.sgml">
7376
<!entity dropSequence system "drop_sequence.sgml">

‎doc/src/sgml/ref/alter_group.sgml

+22-12
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
<!--
2-
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.15 2005/01/04 00:39:53 tgl Exp $
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.16 2005/07/26 23:24:02 tgl Exp $
33
PostgreSQL documentation
44
-->
55

@@ -11,7 +11,7 @@ PostgreSQL documentation
1111

1212
<refnamediv>
1313
<refname>ALTER GROUP</refname>
14-
<refpurpose>change a user group</refpurpose>
14+
<refpurpose>change role name or membership</refpurpose>
1515
</refnamediv>
1616

1717
<indexterm zone="sql-altergroup">
@@ -32,16 +32,25 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
3232

3333
<para>
3434
<command>ALTER GROUP</command> changes the attributes of a user group.
35+
This is an obsolete command, though still accepted for backwards
36+
compatibility, because groups (and users too) have been superseded by the
37+
more general concept of roles.
3538
</para>
3639

3740
<para>
3841
The first two variants add users to a group or remove them from a group.
39-
Only database superusers can use this command.
42+
(Any role can play the part of either a <quote>user</> or a
43+
<quote>group</> for this purpose.) These variants are effectively
44+
equivalent to granting or revoking membership in the role named as the
45+
<quote>group</>; so the preferred way to do this is to use
46+
<xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> or
47+
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">.
4048
</para>
4149

4250
<para>
43-
The third variant changes the name of the group. Only a database
44-
superuser can rename groups.
51+
The third variant changes the name of the group. This is exactly
52+
equivalent to renaming the role with
53+
<xref linkend="sql-alterrole" endterm="sql-alterrole-title">.
4554
</para>
4655
</refsect1>
4756

@@ -53,7 +62,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
5362
<term><replaceable class="PARAMETER">groupname</replaceable></term>
5463
<listitem>
5564
<para>
56-
The name of the group to modify.
65+
The name of the group (role) to modify.
5766
</para>
5867
</listitem>
5968
</varlistentry>
@@ -62,9 +71,9 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
6271
<term><replaceable class="PARAMETER">username</replaceable></term>
6372
<listitem>
6473
<para>
65-
Users that are to be added to or removed from the group. The users
66-
must already exist; <command>ALTER GROUP</> does not create or
67-
drop users.
74+
Users (roles) that are to be added to or removed from the group.
75+
The users must already exist; <command>ALTER GROUP</> does not
76+
create or drop users.
6877
</para>
6978
</listitem>
7079
</varlistentry>
@@ -103,16 +112,17 @@ ALTER GROUP workers DROP USER beth;
103112

104113
<para>
105114
There is no <command>ALTER GROUP</command> statement in the SQL
106-
standard. The concept of roles is similar.
115+
standard.
107116
</para>
108117
</refsect1>
109118

110119
<refsect1>
111120
<title>See Also</title>
112121

113122
<simplelist type="inline">
114-
<member><xref linkend="sql-creategroup" endterm="sql-creategroup-title"></member>
115-
<member><xref linkend="sql-dropgroup" endterm="sql-dropgroup-title"></member>
123+
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
124+
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
125+
<member><xref linkend="sql-alterrole" endterm="sql-alterrole-title"></member>
116126
</simplelist>
117127
</refsect1>
118128

‎doc/src/sgml/ref/alter_role.sgml

+272
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,272 @@
1+
<!--
2+
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.1 2005/07/26 23:24:02 tgl Exp $
3+
PostgreSQL documentation
4+
-->
5+
6+
<refentry id="SQL-ALTERROLE">
7+
<refmeta>
8+
<refentrytitle id="sql-alterrole-title">ALTER ROLE</refentrytitle>
9+
<refmiscinfo>SQL - Language Statements</refmiscinfo>
10+
</refmeta>
11+
12+
<refnamediv>
13+
<refname>ALTER ROLE</refname>
14+
<refpurpose>change a database role</refpurpose>
15+
</refnamediv>
16+
17+
<indexterm zone="sql-alterrole">
18+
<primary>ALTER ROLE</primary>
19+
</indexterm>
20+
21+
<refsynopsisdiv>
22+
<synopsis>
23+
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
24+
25+
where <replaceable class="PARAMETER">option</replaceable> can be:
26+
27+
SUPERUSER | NOSUPERUSER
28+
| CREATEDB | NOCREATEDB
29+
| CREATEROLE | NOCREATEROLE
30+
| CREATEUSER | NOCREATEUSER
31+
| INHERIT | NOINHERIT
32+
| LOGIN | NOLOGIN
33+
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
34+
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
35+
36+
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
37+
38+
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
39+
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>parameter</replaceable>
40+
</synopsis>
41+
</refsynopsisdiv>
42+
43+
<refsect1>
44+
<title>Description</title>
45+
46+
<para>
47+
<command>ALTER ROLE</command> changes the attributes of a
48+
<productname>PostgreSQL</productname> role.
49+
</para>
50+
51+
<para>
52+
The first variant of this command listed in the synopsis can change
53+
many of the role attributes that can be specified in
54+
<xref linkend="sql-createrole" endterm="sql-createrole-title">,
55+
which see for details. (All the possible attributes are covered,
56+
except that there are no options for adding or removing memberships; use
57+
<xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
58+
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title"> for that.)
59+
Attributes not mentioned in the command retain their previous settings.
60+
Database superusers can change any of these settings for any role.
61+
Roles having <literal>CREATEROLE</> privilege can change any of these
62+
settings, but only for non-superuser roles.
63+
Ordinary roles can only change their own password.
64+
</para>
65+
66+
<para>
67+
The second variant changes the name of the role.
68+
Database superusers can rename any role.
69+
Roles having <literal>CREATEROLE</> privilege can rename non-superuser
70+
roles.
71+
The current session user cannot be renamed.
72+
(Connect as a different user if you need to do that.)
73+
Because <literal>MD5</>-encrypted passwords use the role name as
74+
cryptographic salt, renaming a role clears its password if the
75+
password is <literal>MD5</>-encrypted.
76+
</para>
77+
78+
<para>
79+
The third and the fourth variant change a role's session default for
80+
a specified configuration variable. Whenever the role subsequently
81+
starts a new session, the specified value becomes the session default,
82+
overriding whatever setting is present in <filename>postgresql.conf</>
83+
or has been received from the <command>postmaster</command> command line.
84+
(For a role without <literal>LOGIN</> privilege, session defaults have
85+
no effect.)
86+
Ordinary roles can change their own session defaults.
87+
Superusers can change anyone's session defaults.
88+
Roles having <literal>CREATEROLE</> privilege can change defaults for
89+
non-superuser roles.
90+
Certain variables cannot be set this way, or can only be
91+
set if a superuser issues the command.
92+
</para>
93+
</refsect1>
94+
95+
<refsect1>
96+
<title>Parameters</title>
97+
98+
<variablelist>
99+
<varlistentry>
100+
<term><replaceable class="PARAMETER">name</replaceable></term>
101+
<listitem>
102+
<para>
103+
The name of the role whose attributes are to be altered.
104+
</para>
105+
</listitem>
106+
</varlistentry>
107+
108+
<varlistentry>
109+
<term><literal>SUPERUSER</literal></term>
110+
<term><literal>NOSUPERUSER</literal></term>
111+
<term><literal>CREATEDB</></term>
112+
<term><literal>NOCREATEDB</></term>
113+
<term><literal>CREATEROLE</literal></term>
114+
<term><literal>NOCREATEROLE</literal></term>
115+
<term><literal>CREATEUSER</literal></term>
116+
<term><literal>NOCREATEUSER</literal></term>
117+
<term><literal>INHERIT</literal></term>
118+
<term><literal>NOINHERIT</literal></term>
119+
<term><literal>LOGIN</literal></term>
120+
<term><literal>NOLOGIN</literal></term>
121+
<term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term>
122+
<term><literal>ENCRYPTED</></term>
123+
<term><literal>UNENCRYPTED</></term>
124+
<term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term>
125+
<listitem>
126+
<para>
127+
These clauses alter attributes originally set by
128+
<xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">,
129+
which see for more information.
130+
</para>
131+
</listitem>
132+
</varlistentry>
133+
134+
<varlistentry>
135+
<term><replaceable>newname</replaceable></term>
136+
<listitem>
137+
<para>
138+
The new name of the role.
139+
</para>
140+
</listitem>
141+
</varlistentry>
142+
143+
<varlistentry>
144+
<term><replaceable>parameter</replaceable></term>
145+
<term><replaceable>value</replaceable></term>
146+
<listitem>
147+
<para>
148+
Set this role's session default for the specified configuration
149+
parameter to the given value. If
150+
<replaceable>value</replaceable> is <literal>DEFAULT</literal>
151+
or, equivalently, <literal>RESET</literal> is used, the
152+
role-specific variable setting is removed, so the role will
153+
inherit the system-wide default setting in new sessions. Use
154+
<literal>RESET ALL</literal> to clear all role-specific settings.
155+
</para>
156+
157+
<para>
158+
See <xref linkend="sql-set" endterm="sql-set-title"> and <xref
159+
linkend="runtime-config"> for more information about allowed
160+
parameter names and values.
161+
</para>
162+
</listitem>
163+
</varlistentry>
164+
</variablelist>
165+
</refsect1>
166+
167+
<refsect1>
168+
<title>Notes</title>
169+
170+
<para>
171+
Use <xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">
172+
to add new roles, and <xref linkend="SQL-DROPROLE"
173+
endterm="SQL-DROPROLE-title"> to remove a role.
174+
</para>
175+
176+
<para>
177+
<command>ALTER ROLE</command> cannot change a role's memberships.
178+
Use <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
179+
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">
180+
to do that.
181+
</para>
182+
183+
<para>
184+
It is also possible to tie a
185+
session default to a specific database rather than to a role; see
186+
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
187+
Role-specific settings override database-specific
188+
ones if there is a conflict.
189+
</para>
190+
</refsect1>
191+
192+
<refsect1>
193+
<title>Examples</title>
194+
195+
<para>
196+
Change a role's password:
197+
198+
<programlisting>
199+
ALTER ROLE davide WITH PASSWORD 'hu8jmn3';
200+
</programlisting>
201+
</para>
202+
203+
<para>
204+
Change a password expiration date, specifying that the password
205+
should expire at midday on 4th May 2015 using
206+
the time zone which is one hour ahead of <acronym>UTC</>:
207+
<programlisting>
208+
ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1';
209+
</programlisting>
210+
</para>
211+
212+
<para>
213+
Make a password valid forever:
214+
<programlisting>
215+
ALTER ROLE fred VALID UNTIL 'infinity';
216+
</programlisting>
217+
</para>
218+
219+
<para>
220+
Give a role the ability to create other roles and new databases:
221+
222+
<programlisting>
223+
ALTER ROLE miriam CREATEROLE CREATEDB;
224+
</programlisting>
225+
</para>
226+
227+
<para>
228+
Give a role a non-default setting of the
229+
<xref linkend="guc-maintenance-work-mem"> parameter:
230+
231+
<programlisting>
232+
ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
233+
</programlisting>
234+
</para>
235+
</refsect1>
236+
237+
<refsect1>
238+
<title>Compatibility</title>
239+
240+
<para>
241+
The <command>ALTER ROLE</command> statement is a
242+
<productname>PostgreSQL</productname> extension.
243+
</para>
244+
</refsect1>
245+
246+
<refsect1>
247+
<title>See Also</title>
248+
249+
<simplelist type="inline">
250+
<member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
251+
<member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
252+
<member><xref linkend="sql-set" endterm="sql-set-title"></member>
253+
</simplelist>
254+
</refsect1>
255+
</refentry>
256+
257+
<!-- Keep this comment at the end of the file
258+
Local variables:
259+
mode: sgml
260+
sgml-omittag:nil
261+
sgml-shorttag:t
262+
sgml-minimize-attributes:nil
263+
sgml-always-quote-attributes:t
264+
sgml-indent-step:1
265+
sgml-indent-data:t
266+
sgml-parent-document:nil
267+
sgml-default-dtd-file:"../reference.ced"
268+
sgml-exposed-tags:nil
269+
sgml-local-catalogs:"/usr/lib/sgml/catalog"
270+
sgml-local-ecat-files:nil
271+
End:
272+
-->

0 commit comments

Comments
 (0)