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

be rewritten, but at least the reference pages are reasonably sane.

1 files changed, 428 insertions, 0 deletions

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