<!--
doc/src/sgml/ref/create_role.sgml
PostgreSQL documentation
-->

<refentry id="sql-createrole">
 <indexterm zone="sql-createrole">
  <primary>CREATE ROLE</primary>
 </indexterm>

 <refmeta>
  <refentrytitle>CREATE ROLE</refentrytitle>
  <manvolnum>7</manvolnum>
  <refmiscinfo>SQL - Language Statements</refmiscinfo>
 </refmeta>

 <refnamediv>
  <refname>CREATE ROLE</refname>
  <refpurpose>define a new database role</refpurpose>
 </refnamediv>

 <refsynopsisdiv>
<synopsis>
CREATE ROLE <replaceable class="parameter">name</replaceable> [ [ WITH ] <replaceable class="parameter">option</replaceable> [ ... ] ]

<phrase>where <replaceable class="parameter">option</replaceable> can be:</phrase>

      SUPERUSER | NOSUPERUSER
    | CREATEDB | NOCREATEDB
    | CREATEROLE | NOCREATEROLE
    | INHERIT | NOINHERIT
    | LOGIN | NOLOGIN
    | REPLICATION | NOREPLICATION
    | BYPASSRLS | NOBYPASSRLS
    | CONNECTION LIMIT <replaceable class="parameter">connlimit</replaceable>
    | [ ENCRYPTED ] PASSWORD '<replaceable class="parameter">password</replaceable>' | PASSWORD NULL
    | VALID UNTIL '<replaceable class="parameter">timestamp</replaceable>'
    | IN ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
    | ROLE <replaceable class="parameter">role_name</replaceable> [, ...]
    | ADMIN <replaceable class="parameter">role_name</replaceable> [, ...]
    | SYSID <replaceable class="parameter">uid</replaceable>
</synopsis>
 </refsynopsisdiv>

<!--
CAUTION: remember to keep create_user.sgml and create_group.sgml
in sync when changing the above synopsis!
-->

 <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</quote>, a <quote>group</quote>, 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</literal>
   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>

  <para>
   During role creation it is possible to immediately assign the newly created
   role to be a member of an existing role, and also assign existing roles
   to be members of the newly created role.  The rules for which initial
   role membership options are enabled are described below in the
   <literal>IN ROLE</literal>, <literal>ROLE</literal>, and
   <literal>ADMIN</literal> clauses.  The <xref linkend="sql-grant"/>
   command has fine-grained option control during membership creation,
   and the ability to modify these options after the new role is created.
  </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</quote>,
        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</literal></term>
      <term><literal>NOCREATEDB</literal></term>
      <listitem>
       <para>
        These clauses define a role's