Debian Codegraph @

doc/src/sgml/ref/alter_group.sgml

raw
1 <!--
2 doc/src/sgml/ref/alter_group.sgml
3 PostgreSQL documentation
4 -->
5
6 <refentry id="sql-altergroup">
7 <indexterm zone="sql-altergroup">
8 <primary>ALTER GROUP</primary>
9 </indexterm>
10
11 <refmeta>
12 <refentrytitle>ALTER GROUP</refentrytitle>
13 <manvolnum>7</manvolnum>
14 <refmiscinfo>SQL - Language Statements</refmiscinfo>
15 </refmeta>
16
17 <refnamediv>
18 <refname>ALTER GROUP</refname>
19 <refpurpose>change role name or membership</refpurpose>
20 </refnamediv>
21
22 <refsynopsisdiv>
23 <synopsis>
24 ALTER GROUP <replaceable class="parameter">role_specification</replaceable> ADD USER <replaceable class="parameter">user_name</replaceable> [, ... ]
25 ALTER GROUP <replaceable class="parameter">role_specification</replaceable> DROP USER <replaceable class="parameter">user_name</replaceable> [, ... ]
26
27 <phrase>where <replaceable class="parameter">role_specification</replaceable> can be:</phrase>
28
29 <replaceable class="parameter">role_name</replaceable>
30 | CURRENT_ROLE
31 | CURRENT_USER
32 | SESSION_USER
33
34 ALTER GROUP <replaceable class="parameter">group_name</replaceable> RENAME TO <replaceable>new_name</replaceable>
35 </synopsis>
36 </refsynopsisdiv>
37
38 <refsect1>
39 <title>Description</title>
40
41 <para>
42 <command>ALTER GROUP</command> changes the attributes of a user group.
43 This is an obsolete command, though still accepted for backwards
44 compatibility, because groups (and users too) have been superseded by the
45 more general concept of roles.
46 </para>
47
48 <para>
49 The first two variants add users to a group or remove them from a group.
50 (Any role can play the part of either a <quote>user</quote> or a
51 <quote>group</quote> for this purpose.) These variants are effectively
52 equivalent to granting or revoking membership in the role named as the
53 <quote>group</quote>; so the preferred way to do this is to use
54 <link linkend="sql-grant"><command>GRANT</command></link> or
55 <link linkend="sql-revoke"><command>REVOKE</command></link>. Note that
56 <command>GRANT</command> and <command>REVOKE</command> have additional
57 options which are not available with this command, such as the ability
58 to grant and revoke <literal>ADMIN OPTION</literal>, and the ability to
59 specify the grantor.
60 </para>
61
62 <para>
63 The third variant changes the name of the group. This is exactly
64 equivalent to renaming the role with
65 <link linkend="sql-alterrole"><command>ALTER ROLE</command></link>.
66 </para>
67 </refsect1>
68
69 <refsect1>
70 <title>Parameters</title>
71
72 <variablelist>
73 <varlistentry>
74 <term><replaceable class="parameter">group_name</replaceable></term>
75 <listitem>
76 <para>
77 The name of the group (role) to modify.
78 </para>
79 </listitem>
80 </varlistentry>
81
82 <varlistentry>
83 <term><replaceable class="parameter">user_name</replaceable></term>
84 <listitem>
85 <para>
86 Users (roles) that are to be added to or removed from the group.
87 The users must already exist; <command>ALTER GROUP</command> does not
88 create or drop users.
89 </para>
90 </listitem>
91 </varlistentry>
92
93 <varlistentry>
94 <term><replaceable>new_name</replaceable></term>
95 <listitem>
96 <para>
97 The new name of the group.
98 </para>
99 </listitem>
100 </varlistentry>
101 </variablelist>
102 </refsect1>
103
104 <refsect1>
105 <title>Examples</title>
106 <para>
107 Add users to a group:
108
109 <programlisting>
110 ALTER GROUP staff ADD USER karl, john;
111 </programlisting>
112
113 Remove a user from a group:
114
115 <programlisting>
116 ALTER GROUP workers DROP USER beth;
117 </programlisting></para>
118 </refsect1>
119
120 <refsect1>
121 <title>Compatibility</title>
122
123 <para>
124 There is no <command>ALTER GROUP</command> statement in the SQL
125 standard.
126 </para>
127 </refsect1>
128
129 <refsect1>
130 <title>See Also</title>
131
132 <simplelist type="inline">
133 <member><xref linkend="sql-grant"/></member>
134 <member><xref linkend="sql-revoke"/></member>
135 <member><xref linkend="sql-alterrole"/></member>
136 </simplelist>
137 </refsect1>
138
139 </refentry>