Update the createuser utility for the ROLEs world. Alvaro Herrera

1 files changed, 124 insertions, 60 deletions

diff --git a/doc/src/sgml/ref/createuser.sgml b/doc/src/sgml/ref/createuser.sgml
index a2efe9d7897..3656349f5e3 100644
--- a/doc/src/sgml/ref/createuser.sgml
+++ b/doc/src/sgml/ref/createuser.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.41 2005/05/29 03:32:18 momjian Exp $
+$PostgreSQL: pgsql/doc/src/sgml/ref/createuser.sgml,v 1.42 2005/08/14 20:16:02 tgl Exp $
 PostgreSQL documentation
 -->
 
@@ -32,24 +32,24 @@ PostgreSQL documentation
   <title>Description</title>
   <para>
    <application>createuser</application> creates a 
-   new <productname>PostgreSQL</productname> user.  
-   Only superusers (users with <literal>usesuper</literal> set in
-   the <literal>pg_shadow</literal> table) can create 
-   new <productname>PostgreSQL</productname> users,
-   so <application>createuser</application> must be
-   invoked by someone who can connect as a <productname>PostgreSQL</productname>
-   superuser.
+   new <productname>PostgreSQL</productname> user (or more precisely, a role).
+   Only superusers and users with <literal>CREATEROLE</> privilege can create
+   new users, so <application>createuser</application> must be
+   invoked by someone who can connect as a superuser or a user with
+   <literal>CREATEROLE</> privilege.
   </para>
 
   <para>
-   Being a superuser also implies the ability to bypass access permission
+   If you wish to create a new superuser, you must connect as a
+   superuser, not merely with <literal>CREATEROLE</> privilege.
+   Being a superuser implies the ability to bypass all access permission
    checks within the database, so superuserdom should not be granted lightly.
   </para>
 
   <para>
    <application>createuser</application> is a wrapper around the
-   <acronym>SQL</acronym> command <xref linkend="SQL-CREATEUSER"
-   endterm="SQL-CREATEUSER-title">.
+   <acronym>SQL</acronym> command <xref linkend="SQL-CREATEROLE"
+   endterm="SQL-CREATEROLE-title">.
    There is no effective difference between creating users via
    this utility and via other methods for accessing the server.
   </para>
@@ -70,32 +70,28 @@ PostgreSQL documentation
        <para>
         Specifies the name of the <productname>PostgreSQL</productname> user
         to be created.
-        This name must be unique among all users of this
+        This name must be different from all existing roles in this
         <productname>PostgreSQL</productname> installation.
        </para>
       </listitem>
      </varlistentry>  
 
      <varlistentry>
-      <term><option>-a</></term>
-      <term><option>--adduser</></term>
+      <term><option>-s</></term>
+      <term><option>--superuser</></term>
       <listitem>
        <para>
-	The new user is allowed to create other users.
-	(Note: Actually, this makes the new user a <emphasis>superuser</>.
-	The option is poorly named.)
+        The new user will be a superuser.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-A</></term>
-      <term><option>--no-adduser</></term>
+      <term><option>-S</></term>
+      <term><option>--no-superuser</></term>
       <listitem>
        <para>
-	The new user is not allowed to create other users (i.e.,
-	the new user is a regular user, not a superuser).
-	This is the default.
+        The new user will not be a superuser.
        </para>
       </listitem>
      </varlistentry>
@@ -105,7 +101,7 @@ PostgreSQL documentation
       <term><option>--createdb</></term>
       <listitem>
        <para>
-	The new user is allowed to create databases.
+        The new user will be allowed to create databases.
        </para>
       </listitem>
      </varlistentry>
@@ -115,52 +111,86 @@ PostgreSQL documentation
       <term><option>--no-createdb</></term>
       <listitem>
        <para>
-	The new user is not allowed to create databases.
-	This is the default.
+        The new user will not be allowed to create databases.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-e</></term>
-      <term><option>--echo</></term>
+      <term><option>-r</></term>
+      <term><option>--createrole</></term>
       <listitem>
        <para>
-        Echo the commands that <application>createuser</application> generates
-	and sends to the server.
+        The new user will be allowed to create new roles (that is,
+        this user will have <literal>CREATEROLE</> privilege).
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-E</></term>
-      <term><option>--encrypted</></term>
+      <term><option>-R</></term>
+      <term><option>--no-createrole</></term>
       <listitem>
        <para>
-	Encrypts the user's password stored in the database. If not
-	specified, the default password behavior is used.
+        The new user will not be allowed to create new roles.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-i <replaceable class="parameter">number</replaceable></></term>
-      <term><option>--sysid <replaceable class="parameter">number</replaceable></></term>
+      <term><option>-l</></term>
+      <term><option>--login</></term>
       <listitem>
        <para>
-       Allows you to pick a non-default user ID for the new user. This is not
-       necessary, but some people like it.
+        The new user will be allowed to log in (that is, the user name
+        can be used as the initial session user identifier).
+        This is the default.
        </para>
       </listitem>
      </varlistentry>
 
      <varlistentry>
-      <term><option>-N</></term>
-      <term><option>--unencrypted</></term>
+      <term><option>-L</></term>
+      <term><option>--no-login</></term>
       <listitem>
        <para>
-	Does not encrypt the user's password stored in the database. If
-	not specified, the default password behavior is used.
+        The new user will not be allowed to log in.
+        (A role without login privilege is still useful as a means of
+        managing database permissions.)
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-i</></term>
+      <term><option>--inherit</></term>
+      <listitem>
+       <para>
+        The new role will automatically inherit privileges of roles
+        it is a member of.
+        This is the default.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-I</></term>
+      <term><option>--no-inherit</></term>
+      <listitem>
+       <para>
+        The new role will not automatically inherit privileges of roles
+        it is a member of.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-c <replaceable class="parameter">number</replaceable></></term>
+      <term><option>--conn-limit <replaceable class="parameter">number</replaceable></></term>
+      <listitem>
+       <para>
+        Set a maximum number of connections for the new user.
+        The default is to set no limit.
        </para>
       </listitem>
      </varlistentry>
@@ -178,6 +208,39 @@ PostgreSQL documentation
      </varlistentry>
 
      <varlistentry>
+      <term><option>-E</></term>
+      <term><option>--encrypted</></term>
+      <listitem>
+       <para>
+        Encrypts the user's password stored in the database. If not
+        specified, the default password behavior is used.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-N</></term>
+      <term><option>--unencrypted</></term>
+      <listitem>
+       <para>
+        Does not encrypt the user's password stored in the database. If
+        not specified, the default password behavior is used.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
+      <term><option>-e</></term>
+      <term><option>--echo</></term>
+      <listitem>
+       <para>
+        Echo the commands that <application>createuser</application> generates
+        and sends to the server.
+       </para>
+      </listitem>
+     </varlistentry>
+
+     <varlistentry>
       <term><option>-q</></term>
       <term><option>--quiet</></term>
       <listitem>
@@ -204,10 +267,10 @@ PostgreSQL documentation
       <term><option>--host <replaceable class="parameter">host</replaceable></></term>
       <listitem>
        <para>
-	Specifies the host name of the machine on which the 
-	server
-	is running.  If the value begins with a slash, it is used 
-	as the directory for the Unix domain socket.
+        Specifies the host name of the machine on which the 
+        server
+        is running.  If the value begins with a slash, it is used 
+        as the directory for the Unix domain socket.
        </para>
       </listitem>
      </varlistentry>
@@ -217,9 +280,9 @@ PostgreSQL documentation
       <term><option>--port <replaceable class="parameter">port</replaceable></></term>
       <listitem>
        <para>
-	Specifies the TCP port or local Unix domain socket file 
-	extension on which the server
-	is listening for connections.
+        Specifies the TCP port or local Unix domain socket file 
+        extension on which the server
+        is listening for connections.
        </para>
       </listitem>
      </varlistentry>
@@ -272,8 +335,8 @@ PostgreSQL documentation
   <title>Diagnostics</title>
 
   <para>
-   In case of difficulty, see <xref linkend="SQL-CREATEUSER"
-   endterm="sql-createuser-title"> and <xref linkend="APP-PSQL"> for
+   In case of difficulty, see <xref linkend="SQL-CREATEROLE"
+   endterm="sql-createrole-title"> and <xref linkend="APP-PSQL"> for
    discussions of potential problems and error messages.
    The database server must be running at the
    targeted host.  Also, any default connection settings and environment
@@ -292,8 +355,9 @@ PostgreSQL documentation
     server:
 <screen>
 <prompt>$ </prompt><userinput>createuser joe</userinput>
-<computeroutput>Shall the new user be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
-<computeroutput>Shall the new user be allowed to create more new users? (y/n) </computeroutput><userinput>n</userinput>
+<computeroutput>Shall the new role be a superuser? (y/n) </computeroutput><userinput>n</userinput>
+<computeroutput>Shall the new role be allowed to create databases? (y/n) </computeroutput><userinput>n</userinput>
+<computeroutput>Shall the new role be allowed to create more new roles? (y/n) </computeroutput><userinput>n</userinput>
 <computeroutput>CREATE USER</computeroutput>
 </screen>
    </para>
@@ -303,9 +367,9 @@ PostgreSQL documentation
     server on host <literal>eden</>, port 5000, avoiding the prompts and
     taking a look at the underlying command:
 <screen>
-<prompt>$ </prompt><userinput>createuser -h eden -p 5000 -D -A -e joe</userinput>
-<computeroutput>CREATE USER joe NOCREATEDB NOCREATEUSER;</computeroutput>
-<computeroutput>CREATE USER</computeroutput>
+<prompt>$ </prompt><userinput>createuser -h eden -p 5000 -S -D -R -e joe</userinput>
+<computeroutput>CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;</computeroutput>
+<computeroutput>CREATE ROLE</computeroutput>
 </screen>
    </para>
 
@@ -313,11 +377,11 @@ PostgreSQL documentation
     To create the user <literal>joe</literal> as a superuser,
     and assign a password immediately:
 <screen>
-<prompt>$ </prompt><userinput>createuser -P -d -a -e joe</userinput>
-<computeroutput>Enter password for new user: </computeroutput><userinput>xyzzy</userinput>
+<prompt>$ </prompt><userinput>createuser -P -s -e joe</userinput>
+<computeroutput>Enter password for new role: </computeroutput><userinput>xyzzy</userinput>
 <computeroutput>Enter it again: </computeroutput><userinput>xyzzy</userinput>
-<computeroutput>CREATE USER joe PASSWORD 'xyzzy' CREATEDB CREATEUSER;</computeroutput>
-<computeroutput>CREATE USER</computeroutput>
+<computeroutput>CREATE ROLE joe PASSWORD 'xyzzy' SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;</computeroutput>
+<computeroutput>CREATE ROLE</computeroutput>
 </screen>
     In the above example, the new password isn't actually echoed when typed,
     but we show what was typed for clarity.  However the password
@@ -333,7 +397,7 @@ PostgreSQL documentation
 
   <simplelist type="inline">
    <member><xref linkend="app-dropuser"></member>
-   <member><xref linkend="sql-createuser" endterm="sql-createuser-title"></member>
+   <member><xref linkend="sql-createrole" endterm="sql-createrole-title"></member>
    <member>Environment Variables (<xref linkend="libpq-envars">)</member>
   </simplelist>
  </refsect1>