be rewritten, but at least the reference pages are reasonably sane.
<!--
-$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.
-->
<!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">
<!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">
<!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">
<!--
-$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
-->
<refnamediv>
<refname>ALTER GROUP</refname>
- <refpurpose>change a user group</refpurpose>
+ <refpurpose>change role name or membership</refpurpose>
</refnamediv>
<indexterm zone="sql-altergroup">
<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>
<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>
<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>
<para>
There is no <command>ALTER GROUP</command> statement in the SQL
- standard. The concept of roles is similar.
+ standard.
</para>
</refsect1>
<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>
--- /dev/null
+<!--
+$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:
+-->
<!--
-$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
-->
<refnamediv>
<refname>ALTER USER</refname>
- <refpurpose>change a database user account</refpurpose>
+ <refpurpose>change a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-alteruser">
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>
<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>
<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>
<!--
-$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
-->
<refnamediv>
<refname>CREATE GROUP</refname>
- <refpurpose>define a new user group</refpurpose>
+ <refpurpose>define a new database role</refpurpose>
</refnamediv>
<indexterm zone="sql-creategroup">
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>
<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.
- </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.
+ <command>CREATE GROUP</command> is now an alias for
+ <xref linkend="sql-createrole" endterm="sql-createrole-title">,
+ which see for more information.
</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>
<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>
--- /dev/null
+<!--
+$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:
+-->
<!--
-$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
-->
<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">
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>
<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>
<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>
<!--
-$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
-->
<refnamediv>
<refname>DROP GROUP</refname>
- <refpurpose>remove a user group</refpurpose>
+ <refpurpose>remove a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-dropgroup">
<refsynopsisdiv>
<synopsis>
-DROP GROUP <replaceable class="PARAMETER">name</replaceable>
+DROP GROUP <replaceable class="PARAMETER">name</replaceable> [, ...]
</synopsis>
</refsynopsisdiv>
<title>Description</title>
<para>
- <command>DROP GROUP</command> removes the specified group. The
- users in the group are not removed.
+ <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>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.
- </para>
- </refsect1>
-
- <refsect1>
- <title>Examples</title>
- <para>
- To drop a group:
-<programlisting>
-DROP GROUP staff;
-</programlisting>
- </para>
- </refsect1>
-
<refsect1>
<title>Compatibility</title>
<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>
--- /dev/null
+<!--
+$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:
+-->
<!--
-$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
-->
<refnamediv>
<refname>DROP USER</refname>
- <refpurpose>remove a database user account</refpurpose>
+ <refpurpose>remove a database role</refpurpose>
</refnamediv>
<indexterm zone="sql-dropuser">
<refsynopsisdiv>
<synopsis>
-DROP USER <replaceable class="PARAMETER">name</replaceable>
+DROP USER <replaceable class="PARAMETER">name</replaceable> [, ...]
</synopsis>
</refsynopsisdiv>
<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
<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>
<!--
-$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
-->
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>
<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>
<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>
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>
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>
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">
<!--
-$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
-->
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>
<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>
</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>
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">
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">
-<!-- $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>
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>
</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>
-<!-- $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>
<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
<!-- 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
-->
&alterLanguage;
&alterOperator;
&alterOperatorClass;
+ &alterRole;
&alterSchema;
&alterSequence;
&alterTable;
&createLanguage;
&createOperator;
&createOperatorClass;
+ &createRole;
&createRule;
&createSchema;
&createSequence;
&dropLanguage;
&dropOperator;
&dropOperatorClass;
+ &dropRole;
&dropRule;
&dropSchema;
&dropSequence;
projects / thirdparty / postgresql.git / commitdiff
