createuser -- Create a new Postgres user


createuser [ username ]
createuser [ -h host ] [ -p port ]
    [ -i userid ]
    [ -d | -D ] [ -u | -U ] [ username ]


-h host

Specifies the hostname of the machine on which the postmaster is running. Defaults to using a local Unix domain socket rather than an IP connection..

-p port

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


Allows the user to create databases.


Forbids the user to create databases.

-i userid

Specifies the numeric identifier to be associated with this user. This identifier must be unique among all Postgres users, and is not required to match the operating system UID. You will be prompted for an identifier if none is specified on the command line, and it will suggest an identifier matching the UID.


Allows the user to create other users.


Forbids the user to create other users.


Specifies the name of the Postgres user to be created. This name must be unique among all Postgres users. You will be prompted for a name if none is specified on the command line.


createuser will add an entry in the pg_user or pg_shadow system table.

Connection to database 'template1' failed. connectDB() failed: Is the postmaster running and accepting connections at 'UNIX Socket' on port 'port'? createuser: database access failed.

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.

Connection to database 'template1' failed. FATAL 1: SetUserId: user 'username' is not in 'pg_shadow' createuser: database access failed.

You do not have a valid entry in the relation pg_shadow and and will not be allowed to access Postgres. Contact your Postgres administrator.

createuser: username cannot create users.

You do not have permission to create new users; contact your Postgres site administrator.

createuser: 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 in the backend server. Ensure that your site administrator has properly installed Postgresand initialized the site with initdb.

Note: createuser internally runs CREATE USER from psql while connected to the template1 database.


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. The PGOPTION and PGREALM environment variables will be passed on to psql and processed as described in psql. Once invoked, createuser will ask a series of questions to obtain parameters not specified on the command line. The new user's database login name and a numeric user identifier must be specified.

Note: The Postgres user identifier does not need to be the same as the user's Unix UID. However, typically they are assigned to be the same.

You must also describe the privileges of the new user for security purposes. Specifically, you will be asked whether the new user should be able to act as Postgres super-user, whether the new user may create new databases and whether the new user is allowed to create other new users.