mirrors
/
postgres
mirror of https://github.com/postgres/postgres
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Some cleanups in CREATE/ALTER/DROP USER ref pages.

This commit is contained in:
Peter Eisentraut 2002-02-27 21:14:54 +00:00
parent af1b72d83b
commit 36addaff3d
3 changed files with 317 additions and 357 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -1,28 +1,21 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.18 2001/12/08 03:24:33 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/alter_user.sgml,v 1.19 2002/02/27 21:14:53 petere Exp $
PostgreSQL documentation
-->
<refentry id="SQL-ALTERUSER">
<refmeta>
<refentrytitle id="sql-alteruser-title">
ALTER USER
</refentrytitle>
<refentrytitle id="sql-alteruser-title">ALTER USER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
ALTER USER
</refname>
<refpurpose>
change a database user account
</refpurpose>
<refname>ALTER USER</refname>
<refpurpose>change a database user account</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2001-07-10</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
ALTER USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
@ -31,15 +24,26 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
| CREATEDB | NOCREATEDB
| CREATEUSER | NOCREATEUSER
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect2 id="R2-SQL-ALTERUSER-1">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Inputs
</title>
<refsect1>
<title>Description</title>
<para>
<command>ALTER USER</command> is used to change the attributes of a
<productname>PostgreSQL</productname> user account. Attributes not
mentioned in the command retain their previous settings.
</para>
<para>
Only a database superuser can change privileges and password
expiration with this command. Ordinary users can only change their
own password.
</para>
<refsect2>
<title>Parameters</title>
<para>
<variablelist>
@ -47,7 +51,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<term><replaceable class="PARAMETER">username</replaceable></term>
<listitem>
<para>
The name of the user whose details are to be altered.
The name of the user whose attributes are to be altered.
</para>
</listitem>
</varlistentry>
@ -62,12 +66,12 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
<varlistentry>
<term>ENCRYPTED</term>
<term>UNENCRYPTED</term>
<term><literal>ENCRYPTED</literal></term>
<term><literal>UNENCRYPTED</literal></term>
<listitem>
<para>
These keywords control whether the
password is stored encrypted in <literal>pg_shadow</>. (See
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>
@ -75,21 +79,22 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
<varlistentry>
<term>CREATEDB</term>
<term>NOCREATEDB</term>
<term><literal>CREATEDB</literal></term>
<term><literal>NOCREATEDB</literal></term>
<listitem>
<para>
These clauses define a user's ability to create databases.
If CREATEDB is specified, the user being defined will
be allowed to create his own databases. Using NOCREATEDB
will deny a user the ability to create databases.
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CREATEUSER</term>
<term>NOCREATEUSER</term>
<term><literal>CREATEUSER</literal></term>
<term><literal>NOCREATEUSER</literal></term>
<listitem>
<para>
These clauses determine whether a user will be permitted to
@ -111,14 +116,11 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</variablelist>
</para>
</refsect2>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<refsect2 id="R2-SQL-ALTERUSER-2">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
Outputs
</title>
<para>
<variablelist>
<varlistentry>
@ -131,9 +133,7 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: ALTER USER: user "username" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: ALTER USER: user "username" does not exist</computeroutput></term>
<listitem>
<para>
Error message returned if the specified user is not known to
@ -143,90 +143,78 @@ ERROR: ALTER USER: user "username" does not exist
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect1 id="R1-SQL-ALTERUSER-1">
<refsect1info>
<date>1998-09-08</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>ALTER USER</command> is used to change the attributes of a user's
<productname>PostgreSQL</productname> account. Attributes not mentioned
in the command retain their previous settings.
</para>
<para>
Only a database superuser
can change privileges and password expiration with this command. Ordinary
users can only change their own password.
Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
to add new users, and <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title"> to remoe 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>
Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
to create a new user and <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title"> to remove a user.
</para>
</refsect1>
<refsect1 id="R1-SQL-ALTERUSER-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
Change a user password:
<programlisting>
ALTER USER davide WITH PASSWORD 'hu8jmn3';
</programlisting>
</para>
<para>
Change a user's valid until date:
<programlisting>
ALTER USER manuel VALID UNTIL 'Jan 31 2030';
</programlisting>
</para>
<para>
Change a user's valid until date, specifying that his
authorization should expire at midday on 4th May 1998 using
the time zone which is one hour ahead of UTC:
<programlisting>
ALTER USER chris VALID UNTIL 'May 4 12:00:00 1998 +1';
</programlisting>
</para>
<para>
Give a user the ability to create other users and new databases:
<programlisting>
ALTER USER miriam CREATEUSER CREATEDB;
</programlisting>
</para>
</refsect1>
<refsect1 id="R1-SQL-ALTERUSER-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-ALTERUSER-4">
<refsect2info>
<date>1998-09-08</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>ALTER USER</command> statement in
<acronym>SQL92</acronym>.
The standard leaves
the definition of users to the implementation.
The <command>ALTER USER</command> statement is a
<productname>PostgreSQL</productname> extension. The SQL standard
leaves the definition of users to the implementation.
</para>
</refsect2>
</refsect1>
<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>
</simplelist>
</refsect1>
</refentry>

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

@ -1,28 +1,21 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.22 2001/12/08 03:24:35 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/create_user.sgml,v 1.23 2002/02/27 21:14:53 petere Exp $
PostgreSQL documentation
-->
<refentry id="SQL-CREATEUSER">
<refmeta>
<refentrytitle id="sql-createuser-title">
CREATE USER
</refentrytitle>
<refentrytitle id="sql-createuser-title">CREATE USER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
CREATE USER
</refname>
<refpurpose>
define a new database user account
</refpurpose>
<refname>CREATE USER</refname>
<refpurpose>define a new database user account</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>2001-07-10</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
CREATE USER <replaceable class="PARAMETER">username</replaceable> [ [ WITH ] <replaceable class="PARAMETER">option</replaceable> [ ... ] ]
where <replaceable class="PARAMETER">option</replaceable> can be:
@ -33,15 +26,23 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
| CREATEUSER | NOCREATEUSER
| IN GROUP <replaceable class="PARAMETER">groupname</replaceable> [, ...]
| VALID UNTIL '<replaceable class="PARAMETER">abstime</replaceable>'
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para>
<command>CREATE USER</command> will add a new user to an instance
of <productname>PostgreSQL</productname>. Refer to the
<citetitle>Administrator's Guide</citetitle> for information about
managing users and authentication. You must be a database
superuser to use this command.
</para>
<refsect2>
<title>Parameters</title>
<refsect2 id="R2-SQL-CREATEUSER-1">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<variablelist>
@ -58,14 +59,14 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<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 user
that is being created. It is not at all necessary that those
match the <acronym>UNIX</acronym> user ids, but some people
choose to keep the numbers the same.
The <literal>SYSID</literal> clause can be used to choose the
<productname>PostgreSQL</productname> user ID of the user that
is being created. It is not at all necessary that those match
the Unix user IDs, but some people choose to keep the numbers
the same.
</para>
<para>
If this is not specified, the highest assigned user id plus one
If this is not specified, the highest assigned user ID plus one
(with a minimum of 100) will be used as default.
</para>
</listitem>
@ -85,54 +86,57 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
<varlistentry>
<term>ENCRYPTED</term>
<term>UNENCRYPTED</term>
<term><literal>ENCRYPTED</></term>
<term><literal>UNENCRYPTED</></term>
<listitem>
<para>
These keywords control whether the
password is stored encrypted in <literal>pg_shadow</>. (If neither
is specified, the default behavior is determined by the
<varname>PASSWORD_ENCRYPTION</varname> server parameter.)
If the presented string is already in MD5-encrypted format,
then it is stored as-is, regardless of whether
ENCRYPTED or UNENCRYPTED
is specified. This allows reloading of encrypted passwords
during dump/restore.
These keywords control whether the password is stored
encrypted in <literal>pg_shadow</>. (If neither is specified,
the default behavior is determined by the
<varname>PASSWORD_ENCRYPTION</varname> server parameter.) If
the presented string is already in MD5-encrypted format, then
it is stored as-is, regardless of whether
<literal>ENCRYPTED</> or <literal>UNENCRYPTED</> is specified.
This allows reloading of encrypted passwords during
dump/restore.
</para>
<para>
See the chapter on client authentication in the
<citetitle>Administrator's Guide</citetitle> for details on
how to set up authentication mechanisms. Note that older clients
may lack support for the MD5 authentication mechanism that's needed
to work with passwords that are stored encrypted.
how to set up authentication mechanisms. 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>CREATEDB</term>
<term>NOCREATEDB</term>
<term><literal>CREATEDB</></term>
<term><literal>NOCREATEDB</></term>
<listitem>
<para>
These clauses define a user's ability to create databases.
If CREATEDB is specified, the user being defined will
be allowed to create his own databases. Using NOCREATEDB
will deny a user the ability to create databases. If this
clause is omitted, NOCREATEDB is used by default.
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 this clause is omitted,
<literal>NOCREATEDB</literal> is used by default.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>CREATEUSER</term>
<term>NOCREATEUSER</term>
<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. This option will also make the user
a superuser who can override all access restrictions.
Omitting this clause will set the user's value of this
attribute to be NOCREATEUSER.
attribute to be <literal>NOCREATEUSER</literal>.
</para>
</listitem>
</varlistentry>
@ -151,9 +155,9 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
<term><replaceable class="parameter">abstime</replaceable></term>
<listitem>
<para>
The VALID UNTIL clause sets an absolute time after which the
user's password is no longer valid.
If this clause is omitted the login will be valid for all time.
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 login will be valid for all time.
</para>
</listitem>
</varlistentry>
@ -161,13 +165,10 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</para>
</refsect2>
<refsect2 id="R2-SQL-CREATEUSER-2">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
Outputs
</title>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
@ -181,43 +182,31 @@ where <replaceable class="PARAMETER">option</replaceable> can be:
</varlistentry>
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect1 id="R1-SQL-CREATEUSER-1">
<refsect1info>
<date>1998-09-21</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>CREATE USER</command> will add a new user to an instance of
<productname>PostgreSQL</productname>. Refer to the administrator's
guide for information about managing users and authentication.
You must be a database superuser to use this command.
</para>
<para>
Use <xref linkend="SQL-ALTERUSER" endterm="SQL-ALTERUSER-title">
to change a user's password and privileges, and <xref linkend="SQL-DROPUSER"
endterm="SQL-DROPUSER-title"> to remove a user.
Use <xref linkend="SQL-ALTERGROUP" endterm="SQL-ALTERGROUP-title">
to add or remove the user from other groups.
<productname>PostgreSQL</productname>
comes with a script <xref linkend="APP-CREATEUSER"
endterm="APP-CREATEUSER-title">
which has the same functionality as this command (in fact, it calls this command)
but can be run from the command shell.
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.
<productname>PostgreSQL</productname> includes a program <xref
linkend="APP-CREATEUSER" endterm="APP-CREATEUSER-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 id="R1-SQL-CREATEUSER-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
Create a user with no password:
<programlisting>
CREATE USER jonathan
CREATE USER jonathan;
</programlisting>
</para>
@ -246,23 +235,24 @@ CREATE USER manuel WITH PASSWORD 'jw8s0F4' CREATEDB;
</para>
</refsect1>
<refsect1 id="R1-SQL-CREATEUSER-3">
<title>
Compatibility
</title>
<refsect2 id="R2-SQL-CREATEUSER-4">
<refsect2info>
<date>1998-09-21</date>
</refsect2info>
<title>
SQL92
</title>
<refsect1>
<title>Compatibility</title>
<para>
There is no <command>CREATE USER</command> statement in SQL92.
The <command>CREATE USER</command> statement is a
<productname>PostgreSQL</productname> extension. The SQL standard
leaves the definition of users to the implementation.
</para>
</refsect2>
</refsect1>
<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>
</simplelist>
</refsect1>
</refentry>

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

@ -1,40 +1,37 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.14 2002/01/20 22:19:56 petere Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/ref/drop_user.sgml,v 1.15 2002/02/27 21:14:54 petere Exp $
PostgreSQL documentation
-->
<refentry id="SQL-DROPUSER">
<refmeta>
<refentrytitle id="SQL-DROPUSER-TITLE">
DROP USER
</refentrytitle>
<refentrytitle id="SQL-DROPUSER-TITLE">DROP USER</refentrytitle>
<refmiscinfo>SQL - Language Statements</refmiscinfo>
</refmeta>
<refnamediv>
<refname>
DROP USER
</refname>
<refpurpose>
remove a database user account
</refpurpose>
<refname>DROP USER</refname>
<refpurpose>remove a database user account</refpurpose>
</refnamediv>
<refsynopsisdiv>
<refsynopsisdivinfo>
<date>1999-07-20</date>
</refsynopsisdivinfo>
<synopsis>
<synopsis>
DROP USER <replaceable class="PARAMETER">name</replaceable>
</synopsis>
</synopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<refsect2 id="R2-SQL-DROPUSER-1">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Inputs
</title>
<para>
<command>DROP USER</command> removes the specified user from the database.
It does not remove tables, views, or other objects owned by the user. If the
user owns any database, an error is raised.
</para>
<refsect2>
<title>Parameters</title>
<para>
<variablelist>
<varlistentry>
<term><replaceable class="PARAMETER">name</replaceable></term>
@ -48,13 +45,11 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
</para>
</refsect2>
<refsect2 id="R2-SQL-DROPUSER-2">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
Outputs
</title>
</refsect1>
<refsect1>
<title>Diagnostics</title>
<para>
<variablelist>
<varlistentry>
@ -67,9 +62,7 @@ DROP USER <replaceable class="PARAMETER">name</replaceable>
</varlistentry>
<varlistentry>
<term><computeroutput>
ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist
</computeroutput></term>
<term><computeroutput>ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does not exist</computeroutput></term>
<listitem>
<para>
This message occurs if the user name is not found.
@ -78,9 +71,7 @@ ERROR: DROP USER: user "<replaceable class="parameter">name</replaceable>" does
</varlistentry>
<varlistentry>
<term><computeroutput>
DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed
</computeroutput></term>
<term><computeroutput>DROP USER: user "<replaceable class="parameter">name</replaceable>" owns database "<replaceable class="parameter">name</replaceable>", cannot be removed</computeroutput></term>
<listitem>
<para>
You must drop the database first or change its ownership.
@ -90,37 +81,25 @@ DROP USER: user "<replaceable class="parameter">name</replaceable>" owns databas
</variablelist>
</para>
</refsect2>
</refsynopsisdiv>
</refsect1>
<refsect1>
<title>Notes</title>
<refsect1 id="R1-SQL-DROPUSER-1">
<refsect1info>
<date>1998-09-22</date>
</refsect1info>
<title>
Description
</title>
<para>
<command>DROP USER</command> removes the specified user from the database.
It does not remove tables, views, or other objects owned by the user. If the
user owns any database you get an error.
</para>
<para>
Use <xref linkend="SQL-CREATEUSER" endterm="SQL-CREATEUSER-title">
to add new users, and <xref linkend="SQL-ALTERUSER"
endterm="SQL-ALTERUSER-title"> to change a user's properties.
<productname>PostgreSQL</productname>
comes with a script <xref linkend="APP-DROPUSER"
endterm="APP-DROPUSER-title">
which has the same functionality as this command (in fact, it calls this command)
endterm="SQL-ALTERUSER-title"> to change a user's attributes.
<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 id="R1-SQL-DROPUSER-2">
<title>
Usage
</title>
<refsect1>
<title>Examples</title>
<para>
To drop a user account:
<programlisting>
@ -129,23 +108,26 @@ DROP USER jonathan;
</para>
</refsect1>
<refsect1 id="R1-SQL-DROPUSER-3">
<title>
Compatibility
</title>
<refsect1>
<title>Compatibility</title>
<refsect2 id="R2-SQL-DROPUSER-4">
<refsect2info>
<date>1998-09-22</date>
</refsect2info>
<title>
SQL92
</title>
<para>
There is no <command>DROP USER</command> in <acronym>SQL92</acronym>.
The <command>DROP USER</command> statement is a
<productname>PostgreSQL</productname> extension. The SQL standard
leaves the definition of users to the implementation.
</para>
</refsect2>
</refsect1>
<refsect1>
<title>See Also</title>
<simplelist type="inline">
<member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
<member><xref linkend="sql-alteruser" endterm="sql-alteruser-title"></member>
<member><xref linkend="app-dropuser"></member>
</simplelist>
</refsect1>
</refentry>
<!-- Keep this comment at the end of the file