CREATEUSER(UNIX)

NAME
       createuser - create a Postgres user

SYNOPSIS
       createuser [-a system] [-h host] [-p port] [username]

DESCRIPTION
       Createuser  creates  a new Postgres user.  Only users with
       "usesuper" set in the "pg_shadow"  class  can  create  new
       Postgres  users.  As shipped, the user "postgres" can cre-
       ate users.

       Createuser is a shell script that invokes psql.  Hence,  a
       postmaster  process must be running on the database server
       host before createuser  is  executed.   In  addition,  the
       PGOPTION  and PGREALM environment variables will be passed
       on to psql and processed as described in psql(1).

       The optional argument username specifies the name  of  the
       Postgres  user  to  be  created.   (The  invoker  will  be
       prompted for a name if none is specified  on  the  command
       line.)  This name must be unique among all Postgres users.

       Createuser understands the following command-line options:

       -a system
            Specifies  an authentication system system (see pgin-
            tro(1)) to use in connecting to the  postmaster  pro-
            cess.  This option no longer has any effect.

       -h host
            Specifies  the  hostname  of the machine on which the
            postmaster is running.  Defaults to using local  Unix
            domain sockets.

       -p port
            Specifies the TCP/IP port or local Unix domain socket
            file extension on which the postmaster  is  listening
            for  connections.   Defaults to 5432, or the value of
            the PGPORT environment variable (if set).

INTERACTIVE QUESTIONS
       Once invoked with the above options, createuser will ask a
       series  of  questions.  The new users's login name (if not
       given on the command line) and user-id must be  specified.
       (Note  that  the  Postgres user-id must be the same as the
       user's Unix user-id.)  In addition, you must describe  the
       security  capabilities of the new user.  Specifically, you
       will be asked whether the new user should be able  to  act
       as  Postgres  super-user,  create new databases and update
       the system catalogs manually.

SEE ALSO
       destroyuser(1) psql(1) postmaster(1). 

DIAGNOSTICS
       Error: Failed to connect to backend (host=xxx, port=xxx)
            Createuser could not attach to the postmaster process
            on the specified host and port.  If you see this mes-
            sage, ensure that the postmaster is  running  on  the
            proper  host  and  that you have specified the proper
            port.  If your site uses  an  authentication  system,
            ensure  that you have obtained the required authenti-
            cation credentials.

       user "username" is not in "pg_shadow"
            You do  not  have  a  valid  entry  in  the  relation
            "pg_shadow"  and  cannot do anything with Postgres at
            all; contact your Postgres site administrator.

       username cannot create users.
            You do not have permission to create new users;  con-
            tact your Postgres site administrator.

       user "username" already exists
            The  user  to  be  added  already has an entry in the
            "pg_shadow" class.

       database access failed
            An internal error occurred in  psql  or  the  backend
            server.  Ensure that your Postgres site administrator
            has properly installed Postgres and  initialized  the
            site with initdb.

BUGS
       Postgres  user-ids and user names should not have anything
       to do with the constraints of Unix.