mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Basic documentation for ROLEs. The user-manag chapter still needs to

Browse Source 
be rewritten, but at least the reference pages are reasonably sane.
This commit is contained in:
Tom Lane 2005-07-26 23:24:02 +00:00
parent 0c2d7e39f9
commit 58d214e51f
15 changed files with 1061 additions and 642 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
doc/src/sgml/ref/allfiles.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.64 2005/07/25 22:12:31 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/allfiles.sgml,v 1.65 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
Complete list of usable sgml source files in this directory.
-->
@ -16,6 +16,7 @@ Complete list of usable sgml source files in this directory.
<!entity alterLanguage system "alter_language.sgml">
<!entity alterOperator system "alter_operator.sgml">
<!entity alterOperatorClass system "alter_opclass.sgml">
<!entity alterRole system "alter_role.sgml">
<!entity alterSchema system "alter_schema.sgml">
<!entity alterSequence system "alter_sequence.sgml">
<!entity alterTable system "alter_table.sgml">
@ -44,6 +45,7 @@ Complete list of usable sgml source files in this directory.
<!entity createLanguage system "create_language.sgml">
<!entity createOperator system "create_operator.sgml">
<!entity createOperatorClass system "create_opclass.sgml">
<!entity createRole system "create_role.sgml">
<!entity createRule system "create_rule.sgml">
<!entity createSchema system "create_schema.sgml">
<!entity createSequence system "create_sequence.sgml">
@ -68,6 +70,7 @@ Complete list of usable sgml source files in this directory.
<!entity dropLanguage system "drop_language.sgml">
<!entity dropOperator system "drop_operator.sgml">
<!entity dropOperatorClass system "drop_opclass.sgml">
<!entity dropRole system "drop_role.sgml">
<!entity dropRule system "drop_rule.sgml">
<!entity dropSchema system "drop_schema.sgml">
<!entity dropSequence system "drop_sequence.sgml">

34
doc/src/sgml/ref/alter_group.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.15 2005/01/04 00:39:53 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_group.sgml,v 1.16 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>ALTER GROUP</refname>
<refpurpose>change a user group</refpurpose>
<refpurpose>change role name or membership</refpurpose>
</refnamediv>
<indexterm zone="sql-altergroup">
@ -32,16 +32,25 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
<para>
<command>ALTER GROUP</command> changes the attributes of a user group.
This is an obsolete command, though still accepted for backwards
compatibility, because groups (and users too) have been superseded by the
more general concept of roles.
</para>
<para>
The first two variants add users to a group or remove them from a group.
Only database superusers can use this command.
(Any role can play the part of either a <quote>user</> or a
<quote>group</> for this purpose.) These variants are effectively
equivalent to granting or revoking membership in the role named as the
<quote>group</>; so the preferred way to do this is to use
<xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> or
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">.
</para>
<para>
The third variant changes the name of the group. Only a database
superuser can rename groups.
The third variant changes the name of the group. This is exactly
equivalent to renaming the role with
<xref linkend="sql-alterrole" endterm="sql-alterrole-title">.
</para>
</refsect1>
@ -53,7 +62,7 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
<term><replaceable class="PARAMETER">groupname</replaceable></term>
<listitem>
<para>
The name of the group to modify.
The name of the group (role) to modify.
</para>
</listitem>
</varlistentry>
@ -62,9 +71,9 @@ ALTER GROUP <replaceable class="PARAMETER">groupname</replaceable> RENAME TO <re
<term><replaceable class="PARAMETER">username</replaceable></term>
<listitem>
<para>
Users that are to be added to or removed from the group. The users
must already exist; <command>ALTER GROUP</> does not create or
drop users.
Users (roles) that are to be added to or removed from the group.
The users must already exist; <command>ALTER GROUP</> does not
create or drop users.
</para>
</listitem>
</varlistentry>
@ -103,7 +112,7 @@ ALTER GROUP workers DROP USER beth;
<para>
There is no <command>ALTER GROUP</command> statement in the SQL
standard. The concept of roles is similar.
standard.
</para>
</refsect1>
@ -111,8 +120,9 @@ ALTER GROUP workers DROP USER beth;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-creategroup" endterm="sql-creategroup-title"></member>
<member><xref linkend="sql-dropgroup" endterm="sql-dropgroup-title"></member>
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
<member><xref linkend="sql-alterrole" endterm="sql-alterrole-title"></member>
</simplelist>
</refsect1>

272
doc/src/sgml/ref/alter_role.sgml Normal file
View File

@ -0,0 +1,272 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_role.sgml,v 1.1 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-ALTERROLE">
<refmeta>
<refentrytitle id="sql-alterrole-title">ALTER ROLE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>ALTER ROLE</refname>
<refpurpose>change a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-alterrole">
<primary>ALTER ROLE</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
SUPERUSER | NOSUPERUSER
| CREATEDB | NOCREATEDB
| CREATEROLE | NOCREATEROLE
| CREATEUSER | NOCREATEUSER
| INHERIT | NOINHERIT
| LOGIN | NOLOGIN
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> SET <replaceable>parameter</replaceable> { TO | = } { <replaceable>value</replaceable> | DEFAULT }
ALTER ROLE <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>parameter</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>ALTER ROLE</command> changes the attributes of a
<productname>PostgreSQL</productname> role.
</para>
<para>
The first variant of this command listed in the synopsis can change
many of the role attributes that can be specified in
<xref linkend="sql-createrole" endterm="sql-createrole-title">,
which see for details. (All the possible attributes are covered,
except that there are no options for adding or removing memberships; use
<xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title"> for that.)
Attributes not mentioned in the command retain their previous settings.
Database superusers can change any of these settings for any role.
Roles having <literal>CREATEROLE</> privilege can change any of these
settings, but only for non-superuser roles.
Ordinary roles can only change their own password.
</para>
<para>
The second variant changes the name of the role.
Database superusers can rename any role.
Roles having <literal>CREATEROLE</> privilege can rename non-superuser
roles.
The current session user cannot be renamed.
(Connect as a different user if you need to do that.)
Because <literal>MD5</>-encrypted passwords use the role name as
cryptographic salt, renaming a role clears its password if the
password is <literal>MD5</>-encrypted.
</para>
<para>
The third and the fourth variant change a role's session default for
a specified configuration variable. Whenever the role subsequently
starts a new session, the specified value becomes the session default,
overriding whatever setting is present in <filename>postgresql.conf</>
or has been received from the <command>postmaster</command> command line.
(For a role without <literal>LOGIN</> privilege, session defaults have
no effect.)
Ordinary roles can change their own session defaults.
Superusers can change anyone's session defaults.
Roles having <literal>CREATEROLE</> privilege can change defaults for
non-superuser roles.
Certain variables cannot be set this way, or can only be
set if a superuser issues the command.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the role whose attributes are to be altered.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SUPERUSER</literal></term>
<term><literal>NOSUPERUSER</literal></term>
<term><literal>CREATEDB</></term>
<term><literal>NOCREATEDB</></term>
<term><literal>CREATEROLE</literal></term>
<term><literal>NOCREATEROLE</literal></term>
<term><literal>CREATEUSER</literal></term>
<term><literal>NOCREATEUSER</literal></term>
<term><literal>INHERIT</literal></term>
<term><literal>NOINHERIT</literal></term>
<term><literal>LOGIN</literal></term>
<term><literal>NOLOGIN</literal></term>
<term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term>
<term><literal>ENCRYPTED</></term>
<term><literal>UNENCRYPTED</></term>
<term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term>
<listitem>
<para>
These clauses alter attributes originally set by
<xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">,
which see for more information.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>newname</replaceable></term>
<listitem>
<para>
The new name of the role.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>parameter</replaceable></term>
<term><replaceable>value</replaceable></term>
<listitem>
<para>
Set this role's session default for the specified configuration
parameter to the given value. If
<replaceable>value</replaceable> is <literal>DEFAULT</literal>
or, equivalently, <literal>RESET</literal> is used, the
role-specific variable setting is removed, so the role will
inherit the system-wide default setting in new sessions. Use
<literal>RESET ALL</literal> to clear all role-specific settings.
</para>
<para>
See <xref linkend="sql-set" endterm="sql-set-title"> and <xref
linkend="runtime-config"> for more information about allowed
parameter names and values.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <xref linkend="SQL-CREATEROLE" endterm="SQL-CREATEROLE-title">
to add new roles, and <xref linkend="SQL-DROPROLE"
endterm="SQL-DROPROLE-title"> to remove a role.
</para>
<para>
<command>ALTER ROLE</command> cannot change a role's memberships.
Use <xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">
to do that.
</para>
<para>
It is also possible to tie a
session default to a specific database rather than to a role; see
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
Role-specific settings override database-specific
ones if there is a conflict.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Change a role's password:
<programlisting>
ALTER ROLE davide WITH PASSWORD 'hu8jmn3';
</programlisting>
</para>
<para>
Change a password expiration date, specifying that the password
should expire at midday on 4th May 2015 using
the time zone which is one hour ahead of <acronym>UTC</>:
<programlisting>
ALTER ROLE chris VALID UNTIL 'May 4 12:00:00 2015 +1';
</programlisting>
</para>
<para>
Make a password valid forever:
<programlisting>
ALTER ROLE fred VALID UNTIL 'infinity';
</programlisting>
</para>
<para>
Give a role the ability to create other roles and new databases:
<programlisting>
ALTER ROLE miriam CREATEROLE CREATEDB;
</programlisting>
</para>
<para>
Give a role a non-default setting of the
<xref linkend="guc-maintenance-work-mem"> parameter:
<programlisting>
ALTER ROLE worker_bee SET maintenance_work_mem = 100000;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The <command>ALTER ROLE</command> statement is a
<productname>PostgreSQL</productname> extension.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
<member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
<member><xref linkend="sql-set" endterm="sql-set-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

237
doc/src/sgml/ref/alter_user.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.37 2005/01/06 00:11:14 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.38 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>ALTER USER</refname>
<refpurpose>change a database user account</refpurpose>
<refpurpose>change a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-alteruser">
@ -23,11 +23,15 @@ PostgreSQL documentation
ALTER USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
SUPERUSER | NOSUPERUSER
| CREATEDB | NOCREATEDB
| CREATEROLE | NOCREATEROLE
| CREATEUSER | NOCREATEUSER
| INHERIT | NOINHERIT
| LOGIN | NOLOGIN
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
ALTER USER <replaceable class="PARAMETER">name</replaceable> RENAME TO <replaceable>newname</replaceable>
@ -40,218 +44,9 @@ ALTER USER <replaceable class="PARAMETER">name</replaceable> RESET <replaceable>
<title>Description</title>
<para>
<command>ALTER USER</command> changes the attributes of a
<productname>PostgreSQL</productname> user account. Attributes not
mentioned in the command retain their previous settings.
</para>
<para>
The first variant of this command listed in the synopsis changes certain
per-user privileges and authentication settings. (See below for
details.) Database superusers can change any of these settings for any
user. Ordinary users can only change their own password.
</para>
<para>
The second variant changes the name of the user. Only a database
superuser can rename user accounts. The current session user cannot be
renamed. (Connect as a different user if you need to do that.)
Because <literal>MD5</>-encrypted passwords use the user name as
cryptographic salt, renaming a user clears their <literal>MD5</>
password.
</para>
<para>
The third and the fourth variant change a user's session default for
a specified configuration variable. Whenever the user subsequently
starts a new session, the specified value becomes the session default,
overriding whatever setting is present in <filename>postgresql.conf</>
or has been received from the <command>postmaster</command> command line.
Ordinary users can change their own session defaults.
Superusers can change anyone's session defaults.
Certain variables cannot be set this way, or can only be
set by a superuser.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the user whose attributes are to be altered.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEDB</literal></term>
<term><literal>NOCREATEDB</literal></term>
<listitem>
<para>
These clauses define a user's ability to create databases. If
<literal>CREATEDB</literal> is specified, the user
will be allowed to create his own databases. Using
<literal>NOCREATEDB</literal> will deny a user the ability to
create databases. (If the user is also a superuser, then this
setting has no real effect.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEUSER</literal></term>
<term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
These clauses determine whether a user will be permitted to
create new users himself. <literal>CREATEUSER</literal> will also make
the user a superuser, who can override all access restrictions.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">password</replaceable></term>
<listitem>
<para>
The new password to be used for this account.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCRYPTED</literal></term>
<term><literal>UNENCRYPTED</literal></term>
<listitem>
<para>
These key words control whether the password is stored
encrypted in <literal>pg_shadow</>. (See
<xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
for more information about this choice.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="PARAMETER">abstime</replaceable></term>
<listitem>
<para>
The date (and, optionally, the time)
at which this user's password is to expire. To set the password
never to expire, use <literal>'infinity'</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>newname</replaceable></term>
<listitem>
<para>
The new name of the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable>parameter</replaceable></term>
<term><replaceable>value</replaceable></term>
<listitem>
<para>
Set this user's session default for the specified configuration
parameter to the given value. If
<replaceable>value</replaceable> is <literal>DEFAULT</literal>
or, equivalently, <literal>RESET</literal> is used, the
user-specific variable setting is removed, so the user will
inherit the system-wide default setting in new sessions. Use
<literal>RESET ALL</literal> to clear all user-specific settings.
</para>
<para>
See <xref linkend="sql-set" endterm="sql-set-title"> and <xref
linkend="runtime-config"> for more information about allowed
parameter names and values.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
to add new users, and <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title"> to remove a user.
</para>
<para>
<command>ALTER USER</command> cannot change a user's group memberships.
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
to do that.
</para>
<para>
The <literal>VALID UNTIL</> clause defines an expiration time for a
password only, not for the user account <foreignphrase>per se</>. In
particular, the expiration time is not enforced when logging in using
a non-password-based authentication method.
</para>
<para>
It is also possible to tie a
session default to a specific database rather than to a user; see
<xref linkend="sql-alterdatabase" endterm="sql-alterdatabase-title">.
User-specific settings override database-specific
ones if there is a conflict.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Change a user's password:
<programlisting>
ALTER USER davide WITH PASSWORD 'hu8jmn3';
</programlisting>
</para>
<para>
Change the expiration date of the user's password:
<programlisting>
ALTER USER manuel VALID UNTIL 'Jan 31 2030';
</programlisting>
</para>
<para>
Change a password expiration date, specifying that the password
should expire at midday on 4th May 2005 using
the time zone which is one hour ahead of <acronym>UTC</>:
<programlisting>
ALTER USER chris VALID UNTIL 'May 4 12:00:00 2005 +1';
</programlisting>
</para>
<para>
Make a password valid forever:
<programlisting>
ALTER USER fred VALID UNTIL 'infinity';
</programlisting>
</para>
<para>
Give a user the ability to create other users and new databases:
<programlisting>
ALTER USER miriam CREATEUSER CREATEDB;
</programlisting>
<command>ALTER USER</command> is now an alias for
<xref linkend="sql-alterrole" endterm="sql-alterrole-title">,
which see for more information.
</para>
</refsect1>
@ -269,9 +64,7 @@ ALTER USER miriam CREATEUSER CREATEDB;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
<member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
<member><xref linkend="sql-set" endterm="sql-set-title"></member>
<member><xref linkend="sql-alterrole" endterm="sql-alterrole-title"></member>
</simplelist>
</refsect1>
</refentry>

104
doc/src/sgml/ref/create_group.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_group.sgml,v 1.15 2005/01/04 00:39:53 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/create_group.sgml,v 1.16 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>CREATE GROUP</refname>
<refpurpose>define a new user group</refpurpose>
<refpurpose>define a new database role</refpurpose>
</refnamediv>
<indexterm zone="sql-creategroup">
@ -23,9 +23,21 @@ PostgreSQL documentation
CREATE GROUP <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
SYSID <replaceable class="PARAMETER">gid</replaceable>
| USER <replaceable class="PARAMETER">username</replaceable> [, ...]
SUPERUSER | NOSUPERUSER
| CREATEDB | NOCREATEDB
| CREATEROLE | NOCREATEROLE
| CREATEUSER | NOCREATEUSER
| INHERIT | NOINHERIT
| LOGIN | NOLOGIN
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
| IN ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| IN GROUP <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ADMIN <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| USER <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| SYSID <replaceable class="PARAMETER">uid</replaceable>
</synopsis>
</refsynopsisdiv>
@ -33,89 +45,18 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<title>Description</title>
<para>
<command>CREATE GROUP</command> will create a new group of users.
You must be a database superuser to use this command.
<command>CREATE GROUP</command> is now an alias for
<xref linkend="sql-createrole" endterm="sql-createrole-title">,
which see for more information.
</para>
<para>
Note that both users and groups are defined at the database cluster
level, and so are valid in all databases in the cluster.
</para>
<para>
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
to change a group's membership, and <xref linkend="SQL-DROPGROUP"
endterm="SQL-DROPGROUP-title"> to remove a group.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the group.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">gid</replaceable></term>
<listitem>
<para>
The <literal>SYSID</literal> clause can be used to choose
the <productname>PostgreSQL</productname> group ID of the new
group.
This is normally not necessary, but may
be useful if you need to recreate a group referenced in the
permissions of some object.
</para>
<para>
If this is not specified, the highest assigned group ID plus one
(with a minimum of 100) will be used as default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">username</replaceable></term>
<listitem>
<para>
A list of users to include in the group. The users must already exist.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Create an empty group:
<programlisting>
CREATE GROUP staff;
</programlisting>
</para>
<para>
Create a group with members:
<programlisting>
CREATE GROUP marketing WITH USER jonathan, david;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>CREATE GROUP</command> statement in the SQL
standard. Roles are similar in concept to groups.
standard.
</para>
</refsect1>
@ -123,8 +64,7 @@ CREATE GROUP marketing WITH USER jonathan, david;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-altergroup" endterm="sql-altergroup-title"></member>
<member><xref linkend="sql-dropgroup" endterm="sql-dropgroup-title"></member>
<member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
</simplelist>
</refsect1>
</refentry>

428
doc/src/sgml/ref/create_role.sgml Normal file
View File

@ -0,0 +1,428 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_role.sgml,v 1.1 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-CREATEROLE">
<refmeta>
<refentrytitle id="sql-createrole-title">CREATE ROLE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>CREATE ROLE</refname>
<refpurpose>define a new database role</refpurpose>
</refnamediv>
<indexterm zone="sql-createrole">
<primary>CREATE ROLE</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
CREATE ROLE <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
SUPERUSER | NOSUPERUSER
| CREATEDB | NOCREATEDB
| CREATEROLE | NOCREATEROLE
| CREATEUSER | NOCREATEUSER
| INHERIT | NOINHERIT
| LOGIN | NOLOGIN
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
| IN ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| IN GROUP <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ADMIN <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| USER <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| SYSID <replaceable class="PARAMETER">uid</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>CREATE ROLE</command> adds a new role to a
<productname>PostgreSQL</productname> database cluster. A role is
an entity that can own database objects and have database privileges;
a role can be considered a <quote>user</>, a <quote>group</>, or both
depending on how it is used. Refer to
<xref linkend="user-manag"> and <xref
linkend="client-authentication"> for information about managing
users and authentication. You must have <literal>CREATEROLE</>
privilege or be a database superuser to use this command.
</para>
<para>
Note that roles are defined at the database cluster
level, and so are valid in all databases in the cluster.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the new role.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SUPERUSER</literal></term>
<term><literal>NOSUPERUSER</literal></term>
<listitem>
<para>
These clauses determine whether the new role is a <quote>superuser</>,
who can override all access restrictions within the database.
Superuser status is dangerous and should be used only when really
needed. You must yourself be a superuser to create a new superuser.
If not specified,
<literal>NOSUPERUSER</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEDB</></term>
<term><literal>NOCREATEDB</></term>
<listitem>
<para>
These clauses define a role's ability to create databases. If
<literal>CREATEDB</literal> is specified, the role being
defined will be allowed to create new databases. Specifying
<literal>NOCREATEDB</literal> will deny a role the ability to
create databases. If not specified,
<literal>NOCREATEDB</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEROLE</literal></term>
<term><literal>NOCREATEROLE</literal></term>
<listitem>
<para>
These clauses determine whether a role will be permitted to
create new roles (that is, execute <literal>CREATE ROLE</literal>).
A role with <literal>CREATEROLE</literal> privilege can also alter
and drop other roles.
If not specified,
<literal>NOCREATEROLE</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEUSER</literal></term>
<term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
These clauses are an obsolete, but still accepted, spelling of
<literal>SUPERUSER</literal> and <literal>NOSUPERUSER</literal>.
Note that they are <emphasis>not</> equivalent to
<literal>CREATEROLE</literal> as one might naively expect!
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>INHERIT</literal></term>
<term><literal>NOINHERIT</literal></term>
<listitem>
<para>
These clauses determine whether a role <quote>inherits</> the
privileges of roles it is a member of.
A role with <literal>INHERIT</literal> privilege can automatically
use whatever database privileges have been granted to all roles
it is directly or indirectly a member of.
Without <literal>INHERIT</literal>, membership in another role
only grants the ability to <command>SET ROLE</> to that other role;
the privileges of the other role are only available after having
done so.
If not specified,
<literal>INHERIT</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>LOGIN</literal></term>
<term><literal>NOLOGIN</literal></term>
<listitem>
<para>
These clauses determine whether a role is allowed to log in;
that is, whether the role can be given as the initial session
authorization name during client connection. A role having
<literal>LOGIN</literal> privilege can be thought of as a user.
Roles without this attribute are useful for managing database
privileges, but are not users in the usual sense of the word.
If not specified,
<literal>NOLOGIN</literal> is the default, except when
<command>CREATE ROLE</> is invoked through its alternate spelling
<command>CREATE USER</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>PASSWORD</> <replaceable class="parameter">password</replaceable></term>
<listitem>
<para>
Sets the role's password. (A password is only of use for
roles having <literal>LOGIN</literal> privilege, but you can
nonetheless define one for roles without it.)
If you do not plan to use password
authentication you can omit this option.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCRYPTED</></term>
<term><literal>UNENCRYPTED</></term>
<listitem>
<para>
These key words control whether the password is stored
encrypted in the system catalogs. (If neither is specified,
the default behavior is determined by the configuration
parameter <xref linkend="guc-password-encryption">.) If the
presented password string is already in MD5-encrypted format,
then it is stored encrypted as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
(since the system cannot decrypt the specified encrypted
password string). This allows reloading of encrypted
passwords during dump/restore.
</para>
<para>
Note that older clients may lack support for the MD5
authentication mechanism that is needed to work with passwords
that are stored encrypted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>VALID UNTIL</literal> '<replaceable class="parameter">timestamp</replaceable>'</term>
<listitem>
<para>
The <literal>VALID UNTIL</literal> clause sets a date and
time after which the role's password is no longer valid. If
this clause is omitted the password will be valid for all time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN ROLE</> <replaceable class="parameter">rolename</replaceable></term>
<listitem>
<para>
The <literal>IN ROLE</literal> clause lists one or more existing
roles to which the new role will be immediately added as a new
member. (Note that there is no option to add the new role as an
administrator; use a separate <command>GRANT</> command to do that.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>IN GROUP</> <replaceable class="parameter">rolename</replaceable></term>
<listitem>
<para>
<literal>IN GROUP</literal> is an obsolete spelling of
<literal>IN ROLE</>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ROLE</> <replaceable class="parameter">rolename</replaceable></term>
<listitem>
<para>
The <literal>ROLE</literal> clause lists one or more existing
roles which are automatically added as members of the new role.
(This in effect makes the new role a <quote>group</>.)
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ADMIN</> <replaceable class="parameter">rolename</replaceable></term>
<listitem>
<para>
The <literal>ADMIN</literal> clause is like <literal>ROLE</literal>,
but the named roles are added to the new role <literal>WITH ADMIN
OPTION</>, giving them the right to grant membership in this role
to others.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>USER</> <replaceable class="parameter">rolename</replaceable></term>
<listitem>
<para>
The <literal>USER</literal> clause is an obsolete spelling of
the <literal>ROLE</> clause.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>SYSID</> <replaceable class="parameter">uid</replaceable></term>
<listitem>
<para>
The <literal>SYSID</literal> clause is ignored, but is accepted
for backwards compatibility.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <xref linkend="SQL-ALTERROLE" endterm="SQL-ALTERROLE-title"> to
change the attributes of a role, and <xref linkend="SQL-DROPROLE"
endterm="SQL-DROPROLE-title"> to remove a role. All the attributes
specified by <command>CREATE ROLE</> can be modified by later
<command>ALTER ROLE</> commands.
</para>
<para>
The preferred way to add and remove members of roles that are being
used as groups is to use
<xref linkend="SQL-GRANT" endterm="SQL-GRANT-title"> and
<xref linkend="SQL-REVOKE" endterm="SQL-REVOKE-title">.
</para>
<para>
The <literal>VALID UNTIL</> clause defines an expiration time for a
password only, not for the role <foreignphrase>per se</>. In
particular, the expiration time is not enforced when logging in using
a non-password-based authentication method.
</para>
<para>
<literal>INHERIT</> privilege is the default for reasons of backwards
compatibility: in prior releases of <productname>PostgreSQL</productname>,
users always had access to all privileges of groups they were members of.
However, <literal>NOINHERIT</> provides a closer match to the semantics
specified in the SQL standard.
</para>
<para>
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
the same functionality as <command>CREATE ROLE</command> (in fact,
it calls this command) but can be run from the command shell.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Create a role that can log in, but don't give it a password:
<programlisting>
CREATE ROLE jonathan LOGIN;
</programlisting>
</para>
<para>
Create a role with a password:
<programlisting>
CREATE USER davide WITH PASSWORD 'jw8s0F4';
</programlisting>
(<literal>CREATE USER</> is the same as <literal>CREATE ROLE</> except
that it implies <literal>LOGIN</>.)
</para>
<para>
Create a role with a password that is valid until the end of 2004.
After one second has ticked in 2005, the password is no longer
valid.
<programlisting>
CREATE ROLE miriam WITH LOGIN PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
</programlisting>
</para>
<para>
Create a role that can create databases and manage roles:
<programlisting>
CREATE ROLE admin WITH CREATEDB CREATEROLE;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The <command>CREATE ROLE</command> statement is in the SQL standard,
but the standard only requires the syntax
<synopsis>
CREATE ROLE <replaceable class="PARAMETER">name</> [ WITH ADMIN <replaceable class="PARAMETER">rolename</> ]
</synopsis>
Multiple initial administrators, and all the other options of
<command>CREATE ROLE</command>, are
<productname>PostgreSQL</productname> extensions.
</para>
<para>
The SQL standard defines the concepts of users and roles, but it
regards them as distinct concepts and leaves all commands defining
users to be specified by each database implementation. In
<productname>PostgreSQL</productname> we have chosen to unify
users and roles into a single kind of entity. Roles therefore
have many more optional attributes than they do in the standard.
</para>
<para>
The behavior specified by the SQL standard is most closely approximated
by giving users the <literal>NOINHERIT</> attribute, while roles are
given the <literal>INHERIT</> attribute.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-set-role" endterm="sql-set-role-title"></member>
<member><xref linkend="sql-alterrole" endterm="sql-alterrole-title"></member>
<member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
<member><xref linkend="sql-grant" endterm="sql-grant-title"></member>
<member><xref linkend="sql-revoke" endterm="sql-revoke-title"></member>
<member><xref linkend="app-createuser"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

218
doc/src/sgml/ref/create_user.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/create_user.sgml,v 1.36 2005/01/06 00:11:14 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/create_user.sgml,v 1.37 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>CREATE USER</refname>
<refpurpose>define a new database user account</refpurpose>
<refpurpose>define a new database role</refpurpose>
</refnamediv>
<indexterm zone="sql-createuser">
@ -24,12 +24,20 @@ CREATE USER <replaceable class="PARAMETER">name</replaceable> [ [ WITH ] <replac
where <replaceable class="PARAMETER">option</replaceable> can be:
SYSID <replaceable class="PARAMETER">uid</replaceable>
SUPERUSER | NOSUPERUSER
| CREATEDB | NOCREATEDB
| CREATEROLE | NOCREATEROLE
| CREATEUSER | NOCREATEUSER
| IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
| INHERIT | NOINHERIT
| LOGIN | NOLOGIN
| [ ENCRYPTED | UNENCRYPTED ] PASSWORD '<replaceable class="PARAMETER">password</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
| VALID UNTIL '<replaceable class="PARAMETER">timestamp</replaceable>'
| IN ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| IN GROUP <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ROLE <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| ADMIN <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| USER <replaceable class="PARAMETER">rolename</replaceable> [, ...]
| SYSID <replaceable class="PARAMETER">uid</replaceable>
</synopsis>
</refsynopsisdiv>
@ -37,194 +45,14 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<title>Description</title>
<para>
<command>CREATE USER</command> adds a new user to a
<productname>PostgreSQL</productname> database cluster. Refer to
<xref linkend="user-manag"> and <xref
linkend="client-authentication"> for information about managing
users and authentication. You must be a database superuser to use
this command.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="parameter">name</replaceable></term>
<listitem>
<para>
The name of the new user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">uid</replaceable></term>
<listitem>
<para>
The <literal>SYSID</literal> clause can be used to choose the
<productname>PostgreSQL</productname> user ID of the new user.
This is normally not necessary, but may
be useful if you need to recreate the owner of an orphaned
object.
</para>
<para>
If this is not specified, the highest assigned user ID plus one
(with a minimum of 100) will be used as default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEDB</></term>
<term><literal>NOCREATEDB</></term>
<listitem>
<para>
These clauses define a user's ability to create databases. If
<literal>CREATEDB</literal> is specified, the user being
defined will be allowed to create his own databases. Using
<literal>NOCREATEDB</literal> will deny a user the ability to
create databases. If not specified,
<literal>NOCREATEDB</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>CREATEUSER</literal></term>
<term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
These clauses determine whether a user will be permitted to
create new users himself. <literal>CREATEUSER</literal> will also make
the user a superuser, who can override all access restrictions.
If not specified,
<literal>NOCREATEUSER</literal> is the default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">groupname</replaceable></term>
<listitem>
<para>
A name of an existing group into which to insert the user as a new
member. Multiple group names may be listed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">password</replaceable></term>
<listitem>
<para>
Sets the user's password. If you do not plan to use password
authentication you can omit this option, but then the user
won't be able to connect if you decide to switch to password
authentication. The password can be set or changed later,
using <xref linkend="SQL-ALTERUSER"
endterm="SQL-ALTERUSER-title">.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>ENCRYPTED</></term>
<term><literal>UNENCRYPTED</></term>
<listitem>
<para>
These key words control whether the password is stored
encrypted in the system catalogs. (If neither is specified,
the default behavior is determined by the configuration
parameter <xref linkend="guc-password-encryption">.) If the
presented password string is already in MD5-encrypted format,
then it is stored encrypted as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified
(since the system cannot decrypt the specified encrypted
password string). This allows reloading of encrypted
passwords during dump/restore.
</para>
<para>
Note that older clients may lack support for the MD5
authentication mechanism that is needed to work with passwords
that are stored encrypted.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><replaceable class="parameter">abstime</replaceable></term>
<listitem>
<para>
The <literal>VALID UNTIL</literal> clause sets an absolute
time after which the user's password is no longer valid. If
this clause is omitted the password will be valid for all time.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Use <xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title"> to
change the attributes of a user, and <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title"> to remove a user. Use <xref
linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title"> to add the
user to groups or remove the user from groups.
</para>
<para>
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-title"> that has
the same functionality as <command>CREATE USER</command> (in fact, it calls this
command) but can be run from the command shell.
</para>
<para>
The <literal>VALID UNTIL</> clause defines an expiration time for a
password only, not for the user account <foreignphrase>per se</>. In
particular, the expiration time is not enforced when logging in using
a non-password-based authentication method.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
Create a user with no password:
<programlisting>
CREATE USER jonathan;
</programlisting>
</para>
<para>
Create a user with a password:
<programlisting>
CREATE USER davide WITH PASSWORD 'jw8s0F4';
</programlisting>
</para>
<para>
Create a user with a password that is valid until the end of 2004.
After one second has ticked in 2005, the password is no longer
valid.
<programlisting>
CREATE USER miriam WITH PASSWORD 'jw8s0F4' VALID UNTIL '2005-01-01';
</programlisting>
</para>
<para>
Create an account where the user can create databases:
<programlisting>
CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB;
</programlisting>
<command>CREATE USER</command> is now an alias for
<xref linkend="sql-createrole" endterm="sql-createrole-title">,
which see for more information.
The only difference is that when the command is spelled
<command>CREATE USER</command>, <literal>LOGIN</> is assumed
by default, whereas <literal>NOLOGIN</> is assumed when
the command is spelled
<command>CREATE ROLE</command>.
</para>
</refsect1>
@ -242,9 +70,7 @@ CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
<member><xref linkend="sql-dropuser" endterm="sql-dropuser-title"></member>
<member><xref linkend="app-createuser"></member>
<member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
</simplelist>
</refsect1>
</refentry>

51
doc/src/sgml/ref/drop_group.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.10 2005/01/09 05:57:45 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/drop_group.sgml,v 1.11 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>DROP GROUP</refname>
<refpurpose>remove a user group</refpurpose>
<refpurpose>remove a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-dropgroup">
@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
DROP GROUP <replaceable class="PARAMETER">name</replaceable>
DROP GROUP <replaceable class="PARAMETER">name</replaceable> [, ...]
</synopsis>
</refsynopsisdiv>
@ -28,48 +28,12 @@ DROP GROUP <replaceable class="PARAMETER">name</replaceable>
<title>Description</title>
<para>
<command>DROP GROUP</command> removes the specified group. The
users in the group are not removed.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of an existing group.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
It is unwise to drop a group that has any
granted permissions on objects. Currently, this is not enforced,
but it is likely that future versions of
<productname>PostgreSQL</productname> will check for the error.
<command>DROP GROUP</command> is now an alias for
<xref linkend="sql-droprole" endterm="sql-droprole-title">,
which see for more information.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
To drop a group:
<programlisting>
DROP GROUP staff;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
@ -82,8 +46,7 @@ DROP GROUP staff;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-altergroup" endterm="sql-altergroup-title"></member>
<member><xref linkend="sql-creategroup" endterm="sql-creategroup-title"></member>
<member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
</simplelist>
</refsect1>

126
doc/src/sgml/ref/drop_role.sgml Normal file
View File

@ -0,0 +1,126 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/drop_role.sgml,v 1.1 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-DROPROLE">
<refmeta>
<refentrytitle id="SQL-DROPROLE-TITLE">DROP ROLE</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>DROP ROLE</refname>
<refpurpose>remove a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-droprole">
<primary>DROP ROLE</primary>
</indexterm>
<refsynopsisdiv>
<synopsis>
DROP ROLE <replaceable class="PARAMETER">name</replaceable> [, ...]
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>DROP ROLE</command> removes the specified role(s).
To drop a superuser role, you must be a superuser yourself;
to drop non-superuser roles, you must have <literal>CREATEROLE</>
privilege.
</para>
<para>
A role cannot be removed if it is still referenced in any database
of the cluster; an error will be raised if so. Before dropping the role,
you must drop all the objects it owns (or reassign their ownership)
and revoke any privileges the role has been granted.
</para>
<para>
However, it is not necessary to remove role memberships involving
the role; <command>DROP ROLE</> automatically revokes any memberships
of the target role in other roles, and of other roles in the target role.
The other roles are not dropped nor otherwise affected.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the role to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> that has the
same functionality as this command (in fact, it calls this command)
but can be run from the command shell.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
To drop a role:
<programlisting>
DROP ROLE jonathan;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The SQL standard defines <command>DROP ROLE</command>, but it allows
only one role to be dropped at a time, and it specifies different
privilege requirements than <productname>PostgreSQL</productname> uses.
</para>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
<member><xref linkend="sql-alterrole" endterm="sql-alterrole-title"></member>
<member><xref linkend="sql-set-role" endterm="sql-set-role-title"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"../reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

66
doc/src/sgml/ref/drop_user.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.20 2005/01/04 00:39:53 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.21 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -11,7 +11,7 @@ PostgreSQL documentation
<refnamediv>
<refname>DROP USER</refname>
<refpurpose>remove a database user account</refpurpose>
<refpurpose>remove a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-dropuser">
@ -20,7 +20,7 @@ PostgreSQL documentation
<refsynopsisdiv>
<synopsis>
DROP USER <replaceable class="PARAMETER">name</replaceable>
DROP USER <replaceable class="PARAMETER">name</replaceable> [, ...]
</synopsis>
</refsynopsisdiv>
@ -28,64 +28,15 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
<title>Description</title>
<para>
<command>DROP USER</command> removes the specified user.
It does not remove tables, views, or other objects owned by the user. If the
user owns any database, an error is raised.
<command>DROP USER</command> is now an alias for
<xref linkend="sql-droprole" endterm="sql-droprole-title">,
which see for more information.
</para>
</refsect1>
<refsect1>
<title>Parameters</title>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
<listitem>
<para>
The name of the user to remove.
</para>
</listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-DROPUSER" endterm="APP-DROPUSER-title"> that has the
same functionality as this command (in fact, it calls this command)
but can be run from the command shell.
</para>
<para>
To drop a user who owns a database, first drop the database or change
its ownership.
</para>
<para>
It is unwise to drop a user who either owns any database objects or has any
granted permissions on objects. Currently, this is only enforced for
the case of owners of databases, but it is likely that future versions of
<productname>PostgreSQL</productname> will check other cases.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<para>
To drop a user account:
<programlisting>
DROP USER jonathan;
</programlisting>
</para>
</refsect1>
<refsect1>
<title>Compatibility</title>
<para>
The <command>DROP USER</command> statement is a
<productname>PostgreSQL</productname> extension. The SQL standard
@ -97,8 +48,7 @@ DROP USER jonathan;
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
<member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
<member><xref linkend="sql-droprole" endterm="sql-droprole-title"></member>
</simplelist>
</refsect1>

73
doc/src/sgml/ref/grant.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.47 2005/05/26 20:05:03 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/grant.sgml,v 1.48 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -44,6 +44,9 @@ GRANT { { CREATE | USAGE } [,...] | ALL [ PRIVILEGES ] }
GRANT { CREATE | ALL [ PRIVILEGES ] }
ON TABLESPACE <replaceable>tablespacename</> [, ...]
TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH GRANT OPTION ]
GRANT <replaceable class="PARAMETER">role</replaceable> [, ...]
TO { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...] [ WITH ADMIN OPTION ]
</synopsis>
</refsynopsisdiv>
@ -51,20 +54,39 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
<title>Description</title>
<para>
The <command>GRANT</command> command gives specific privileges on
an object (table, view, sequence, database, function,
procedural language, schema, or tablespace) to
one or more users or groups of users. These privileges are added
The <command>GRANT</command> command has two basic variants: one
that grants privileges on a database object (table, view, sequence,
database, function, procedural language, schema, or tablespace),
and one that grants membership in a role. These variants are
similar in many ways, but they are different enough to be described
separately.
</para>
<para>
As of <productname>PostgreSQL</productname> 8.1, the concepts of users and
groups have been unified into a single kind of entity called a role.
It is therefore no longer necessary to use the keyword <literal>GROUP</>
to identify whether a grantee is a user or a group. <literal>GROUP</>
is still allowed in the command, but it is a noise word.
</para>
<refsect2 id="sql-grant-description-objects">
<title>GRANT on Database Objects</title>
<para>
This variant of the <command>GRANT</command> command gives specific
privileges on a database object to
one or more roles. These privileges are added
to those already granted, if any.
</para>
<para>
The key word <literal>PUBLIC</literal> indicates that the
privileges are to be granted to all users, including those that may
privileges are to be granted to all roles, including those that may
be created later. <literal>PUBLIC</literal> may be thought of as an
implicitly defined group that always includes all users.
Any particular user will have the sum
of privileges granted directly to him, privileges granted to any group he
implicitly defined group that always includes all roles.
Any particular role will have the sum
of privileges granted directly to it, privileges granted to any role it
is presently a member of, and privileges granted to
<literal>PUBLIC</literal>.
</para>
@ -72,9 +94,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
<para>
If <literal>WITH GRANT OPTION</literal> is specified, the recipient
of the privilege may in turn grant it to others. Without a grant
option, the recipient cannot do that. At present, grant options can
only be granted to individual users, not to groups or
<literal>PUBLIC</literal>.
option, the recipient cannot do that. Grant options cannot be granted
to <literal>PUBLIC</literal>.
</para>
<para>
@ -258,6 +279,24 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
The privileges required by other commands are listed on the
reference page of the respective command.
</para>
</refsect2>
<refsect2 id="sql-grant-description-roles">
<title>GRANT on Roles</title>
<para>
This variant of the <command>GRANT</command> command grants membership
in a role to one or more other roles. Membership in a role is significant
because it conveys the privileges granted to a role to each of its
members.
</para>
<para>
If <literal>WITH ADMIN OPTION</literal> is specified, the member may
in turn grant membership in the role to others. Without the admin
option, the recipient cannot do that.
</para>
</refsect2>
</refsect1>
@ -296,6 +335,8 @@ GRANT { CREATE | ALL [ PRIVILEGES ] }
command, the command is performed as though it were issued by the
owner of the affected object. In particular, privileges granted via
such a command will appear to have been granted by the object owner.
(For role membership, the membership appears to have been granted
by the containing role itself.)
</para>
<para>
@ -392,6 +433,14 @@ GRANT ALL PRIVILEGES ON kinds TO manuel;
else it will only grant those permissions for which the someone else has
grant options.
</para>
<para>
Grant membership in role <literal>admins</> to user <literal>joe</>:
<programlisting>
GRANT admins TO joe;
</programlisting>
</para>
</refsect1>
<refsect1 id="sql-grant-compatibility">

32
doc/src/sgml/ref/revoke.sgml
View File

@ -1,5 +1,5 @@
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.33 2005/05/26 20:05:03 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/ref/revoke.sgml,v 1.34 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
@ -56,6 +56,11 @@ REVOKE [ GRANT OPTION FOR ]
ON TABLESPACE <replaceable>tablespacename</replaceable> [, ...]
FROM { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
REVOKE [ ADMIN OPTION FOR ]
<replaceable class="PARAMETER">role</replaceable> [, ...]
FROM { <replaceable class="PARAMETER">username</replaceable> | GROUP <replaceable class="PARAMETER">groupname</replaceable> | PUBLIC } [, ...]
[ CASCADE | RESTRICT ]
</synopsis>
</refsynopsisdiv>
@ -64,9 +69,9 @@ REVOKE [ GRANT OPTION FOR ]
<para>
The <command>REVOKE</command> command revokes previously granted
privileges from one or more users or groups of users. The key word
privileges from one or more roles. The key word
<literal>PUBLIC</literal> refers to the implicitly defined group of
all users.
all roles.
</para>
<para>
@ -75,13 +80,13 @@ REVOKE [ GRANT OPTION FOR ]
</para>
<para>
Note that any particular user will have the sum
of privileges granted directly to him, privileges granted to any group he
Note that any particular role will have the sum
of privileges granted directly to it, privileges granted to any role it
is presently a member of, and privileges granted to
<literal>PUBLIC</literal>. Thus, for example, revoking <literal>SELECT</> privilege
from <literal>PUBLIC</literal> does not necessarily mean that all users
from <literal>PUBLIC</literal> does not necessarily mean that all roles
have lost <literal>SELECT</> privilege on the object: those who have it granted
directly or via a group will still have it.
directly or via another role will still have it.
</para>
<para>
@ -103,6 +108,11 @@ REVOKE [ GRANT OPTION FOR ]
Thus, the affected users may effectively keep the privilege if it
was also granted through other users.
</para>
<para>
When revoking membership in a role, <literal>GRANT OPTION</> is instead
called <literal>ADMIN OPTION</>, but the behavior is similar.
</para>
</refsect1>
<refsect1 id="SQL-REVOKE-notes">
@ -173,6 +183,14 @@ REVOKE ALL PRIVILEGES ON kinds FROM manuel;
Note that this actually means <quote>revoke all privileges that I
granted</>.
</para>
<para>
Revoke membership in role <literal>admins</> from user <literal>joe</>:
<programlisting>
REVOKE admins FROM joe;
</programlisting>
</para>
</refsect1>
<refsect1 id="SQL-REVOKE-compatibility">

46
doc/src/sgml/ref/set_role.sgml
View File

@ -1,4 +1,8 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/set_role.sgml,v 1.1 2005/07/25 22:12:31 tgl Exp $ -->
<!--
$PostgreSQL: pgsql/doc/src/sgml/ref/set_role.sgml,v 1.2 2005/07/26 23:24:02 tgl Exp $
PostgreSQL documentation
-->
<refentry id="SQL-SET-ROLE">
<refmeta>
<refentrytitle id="sql-set-role-title">SET ROLE</refentrytitle>
@ -29,9 +33,10 @@ RESET ROLE
This command sets the current user
identifier of the current SQL-session context to be <replaceable
class="parameter">rolename</replaceable>. The role name may be
written as either an identifier or a string literal. Using this
command, it is possible to either add privileges or restrict one's
privileges.
written as either an identifier or a string literal.
After <command>SET ROLE</>, permissions checking for SQL commands
is carried out as though the named role were the one that had logged
in originally.
</para>
<para>
@ -53,6 +58,39 @@ RESET ROLE
</para>
</refsect1>
<refsect1>
<title>Notes</title>
<para>
Using this command, it is possible to either add privileges or restrict
one's privileges. If the session user role has the <literal>INHERITS</>
attribute, then it automatically has all the privileges of every role that
it could <command>SET ROLE</> to; in this case <command>SET ROLE</>
effectively drops all the privileges assigned directly to the session user
and to the other roles it is a member of, leaving only the privileges
available to the named role. On the other hand, if the session user role
has the <literal>NOINHERITS</> attribute, <command>SET ROLE</> drops the
privileges assigned directly to the session user and instead acquires the
privileges available to the named role.
</para>
<para>
In particular, when a superuser chooses to <command>SET ROLE</> to a
non-superuser role, she loses her superuser privileges.
</para>
<para>
<command>SET ROLE</> has effects comparable to
<xref linkend="sql-set-session-authorization"
endterm="sql-set-session-authorization-title">, but the privilege
checks involved are quite different. Also,
<command>SET SESSION AUTHORIZATION</> determines which roles are
allowable for later <command>SET ROLE</> commands, whereas changing
roles with <command>SET ROLE</> does not change the set of roles
allowed to a later <command>SET ROLE</>.
</para>
</refsect1>
<refsect1>
<title>Examples</title>

6
doc/src/sgml/ref/set_session_auth.sgml
View File

@ -1,4 +1,4 @@
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.13 2005/07/25 22:12:31 tgl Exp $ -->
<!-- $PostgreSQL: pgsql/doc/src/sgml/ref/set_session_auth.sgml,v 1.14 2005/07/26 23:24:02 tgl Exp $ -->
<refentry id="SQL-SET-SESSION-AUTHORIZATION">
<refmeta>
<refentrytitle id="sql-set-session-authorization-title">SET SESSION AUTHORIZATION</refentrytitle>
@ -89,8 +89,8 @@ SELECT SESSION_USER, CURRENT_USER;
<para>
The SQL standard allows some other expressions to appear in place
of the literal <replaceable>username</replaceable> which are not
important in practice. <productname>PostgreSQL</productname>
of the literal <replaceable>username</replaceable>, but these options
are not important in practice. <productname>PostgreSQL</productname>
allows identifier syntax (<literal>"username"</literal>), which SQL
does not. SQL does not allow this command during a transaction;
<productname>PostgreSQL</productname> does not make this

5
doc/src/sgml/reference.sgml
View File

@ -1,5 +1,5 @@
<!-- reference.sgml
$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.54 2005/07/25 22:12:30 tgl Exp $
$PostgreSQL: pgsql/doc/src/sgml/reference.sgml,v 1.55 2005/07/26 23:24:01 tgl Exp $
PostgreSQL Reference Manual
-->
@ -48,6 +48,7 @@ PostgreSQL Reference Manual
&alterLanguage;
&alterOperator;
&alterOperatorClass;
&alterRole;
&alterSchema;
&alterSequence;
&alterTable;
@ -76,6 +77,7 @@ PostgreSQL Reference Manual
&createLanguage;
&createOperator;
&createOperatorClass;
&createRole;
&createRule;
&createSchema;
&createSequence;
@ -100,6 +102,7 @@ PostgreSQL Reference Manual
&dropLanguage;
&dropOperator;
&dropOperatorClass;
&dropRole;
&dropRule;
&dropSchema;
&dropSequence;