CREATEDB(UNIX)

NAME
       createdb - create a database

SYNOPSIS
       createdb  [-a  system]  [-h host] [-p port] [-u] [-D loca-
       tion] [dbname]

DESCRIPTION
       createdb creates a new database.  The person who  executes
       this  command  becomes the database administrator, or DBA,
       for this database and is the only person, other  than  the
       Postgres super-user, who can destroy it.

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

       The  optional  argument  dbname  specifies the name of the
       database to be created.  The name must be unique among all
       Postgres  databases.   dbname defaults to the value of the
       USER environment variable.

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

       -D dbpath
            Specifies the alternate database  location  for  this
            database.

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

       -p port
            Specifies  the  Internet  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   Use password authentication. Prompts for username and
            password.

EXAMPLES
       # create the demo database using the postmaster on the local host, port 5432.
       createdb demo
       # create the demo database using the postmaster on host eden,

       # port 5000.
       createdb -p 5000 -h eden demo

FILES
       $PGDATA/base/dbname
            The  location  of  the  files  corresponding  to  the
            database dbname.

SEE ALSO
       createdb(l) destroydb(1) initdb(1) psql(1) postmas- 
       ter(1). 

DIAGNOSTICS
       Error: Failed to connect to backend (host=xxx, port=xxx)
            Createdb 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_user"
            You do  not  have  a  valid  entry  in  the  relation
            "pg_user"  and  cannot  do  anything with Postgres at
            all; contact your Postgres site administrator.

       user "username" is not allowed to create/destroy databases
            You  do  not have permission to create new databases;
            contact your Postgres site administrator.

       dbname already exists
            The database already exists.

       database creation failed on dbname
            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.