Provided by: postgresql-client-8.3_8.3.8-1_i386 bug

NAME

       createuser - define a new PostgreSQL user account

SYNOPSIS

       createuser [ option... ]  [ username ]

DESCRIPTION

       createuser  creates  a new PostgreSQL user (or more precisely, a role).
       Only superusers and users with  CREATEROLE  privilege  can  create  new
       users,  so  createuser  must be invoked by someone who can connect as a
       superuser or a user with CREATEROLE privilege.

       If you wish to create a new superuser, you must connect as a superuser,
       not  merely  with  CREATEROLE privilege.  Being a superuser implies the
       ability to bypass all access permission checks within the database,  so
       superuserdom should not be granted lightly.

       createuser   is   a   wrapper   around  the  SQL  command  CREATE  ROLE
       [create_role(7)].  There is no effective  difference  between  creating
       users  via this utility and via other methods for accessing the server.

OPTIONS

       createuser accepts the following command-line arguments:

       username
              Specifies the name of the PostgreSQL user to be  created.   This
              name   must  be  different  from  all  existing  roles  in  this
              PostgreSQL installation.

       -s

       --superuser
              The new user will be a superuser.

       -S

       --no-superuser
              The new user will not be a superuser.  This is the default.

       -d

       --createdb
              The new user will be allowed to create databases.

       -D

       --no-createdb
              The new user will not be allowed to create databases.   This  is
              the default.

       -r

       --createrole
              The  new user will be allowed to create new roles (that is, this
              user will have CREATEROLE privilege).

       -R

       --no-createrole
              The new user will not be allowed to create new roles.   This  is
              the default.

       -l

       --login
              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.

       -L

       --no-login
              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.)

       -i

       --inherit
              The  new  role will automatically inherit privileges of roles it
              is a member of.  This is the default.

       -I

       --no-inherit
              The new role will not automatically inherit privileges of  roles
              it is a member of.

       -c number

       --connection-limit number
              Set  a  maximum  number  of  connections  for the new user.  The
              default is to set no limit.

       -P

       --pwprompt
              If given, createuser will issue a prompt for the password of the
              new  user.  This  is  not  necessary if you do not plan on using
              password authentication.

       -E

       --encrypted
              Encrypts the user’s password stored  in  the  database.  If  not
              specified, the default password behavior is used.

       -N

       --unencrypted
              Does  not encrypt the user’s password stored in the database. If
              not specified, the default password behavior is used.

       -e

       --echo Echo the commands that createuser generates  and  sends  to  the
              server.

       You  will be prompted for a name and other missing information if it is
       not specified on the command line.

       createuser  also  accepts  the  following  command-line  arguments  for
       connection parameters:

       -h host

       --host host
              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.

       -p port

       --port port
              Specifies  the  TCP  port  or  local  Unix  domain  socket  file
              extension on which the server is listening for connections.

       -U username

       --username username
              User name to connect as (not the user name to create).

       -W

       --password
              Force createuser to prompt for a password (for connecting to the
              server, not for the password of the new user).

              This   option   is   never   essential,  since  createuser  will
              automatically prompt  for  a  password  if  the  server  demands
              password  authentication.   However,  createuser  will  waste  a
              connection attempt finding out that the server wants a password.
              In  some  cases  it  is  worth  typing  -W  to  avoid  the extra
              connection attempt.

ENVIRONMENT

       PGHOST

       PGPORT

       PGUSER Default connection parameters

       This utility, like most  other  PostgreSQL  utilities,  also  uses  the
       environment variables supported by libpq (see in the documentation).

DIAGNOSTICS

       In case of difficulty, see CREATE ROLE [create_role(7)] and psql(1) 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 variables used by the libpq  front-
       end library will apply.

EXAMPLES

       To create a user joe on the default database server:

       $ createuser joe
       Shall the new role be a superuser? (y/n) n
       Shall the new role be allowed to create databases? (y/n) n
       Shall the new role be allowed to create more new roles? (y/n) n

       To  create  the same user joe using the server on host eden, port 5000,
       avoiding the prompts and taking a look at the underlying command:

       $ createuser -h eden -p 5000 -S -D -R -e joe
       CREATE ROLE joe NOSUPERUSER NOCREATEDB NOCREATEROLE INHERIT LOGIN;

       To  create  the  user  joe  as  a  superuser,  and  assign  a  password
       immediately:

       $ createuser -P -s -e joe
       Enter password for new role: xyzzy
       Enter it again: xyzzy
       CREATE ROLE joe PASSWORD ’md5b5f5ba1a423792b526f799ae4eb3d59e’ SUPERUSER CREATEDB CREATEROLE INHERIT LOGIN;

       In  the  above  example,  the  new  password isn’t actually echoed when
       typed, but we show what was typed for clarity. As you see, the password
       is   encrypted  before  it  is  sent  to  the  client.  If  the  option
       --unencrypted is used, the password will appear in the  echoed  command
       (and  possibly also in the server log and elsewhere), so you don’t want
       to use -e in that case, if anyone else can see your screen.

SEE ALSO

       dropuser(1), CREATE ROLE [create_role(7)]