CREATEUSER(UNIX)

NAME
createuser - create a Postgres user

SYNOPSIS
createuser [-a system] [-d ] [-D ] [-h host] [-i id] [-p port] [-u ] [-U ] [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 create 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 to use in connecting to the postmaster process. This option no longer has any effect.

-d  Allows the user to create databases.

-D  Does not allow the user to create databases.

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

-i id
    Use id as the user id.

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

-u  Allows the user to create other users.

-U  Does not allow the user to create other users.

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
create_user(l), 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 message, 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 authentication 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; contact 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.

NOTE
The command internally runs create user from psql connected to the template1 database to perform the operation.