initdb  --  Creates a new database cluster.


initdb [ --pgdata|-D dbdir ]
    [ --sysid|-i sysid ]
    [ --pwprompt|-W ]
    [ --encoding|-E encoding ]
    [ --pglib|-L libdir ]
    [ --noclean | -n ] [ --debug | -d ] [ --template | -t ]


--pgdata=dbdir, -D dbdir, PGDATA

Use this parameter to provide the directory name where you wish store the new data once creation is finished. The directory name specified here can also be set as the PGDATA environmental variable. If PGDATA is already set to the directory you want to use, it is not necessary to use this parameter.

--sysid=sysid, -i sysid

Use this parameter to set the system ID of the database superuser. If this is unspecified, the ID will be automatically set to the ID of the user who ran the initdb program.

--pwprompt, -W

Passing this parameter will cause initdb to prompt for the password of the new superuser account.

--encoding=encoding, -E encoding

This parameter takes the multibyte encoding type of the template database within this cluster. Whatever type you set here will by default become the type of any databases you create later using this cluster.

--pglib=libdir, -l libdir

The initdb program uses certain libraries when creating a database cluster. The location of these files is normally known by the program and when the location is not found, it will prompt you to specify it; hence, you shouldn't need to use this parameter often, but it is included in the case that you might.

--template, -t

Pass this parameter to replace the template1 database within an already existing database cluster, then exit. This can help during PostgreSQL version updates and if your template1 ever becomes corrupted or destroyed.

--noclean, -n

Use this parameter to specify that initdb should not clean up its files in the event that it is unable to complete cluster creation due to an error. This parameter can be useful for debugging purposes.

--debug, -d

Use this parameter to display debugging information from the bootstrap backend (the program used in creation of catalog tables).


If it completes successfully, initdb will create a database cluster in the specified data directory; this cluster can then be used by the backend to store its database framework.


Use the initdb program to create a database cluster within your filesystem. A database cluster is the framework upon which PostgreSQL databases (and groups of databases) are created; an example of a cluster is the /data directory within your PostgreSQL installation directory. You may use initdb to create a new data directory and then tell postmaster to start up using that data cluster instead of the default. If you use initdb to create a new data cluster, the cluster will be owned by whatever user you are currently logged into when issuing the command.

NoteDon't run as root!

Do not run the initdb program while logged in as root! The cluster needs to be created and owned by whatever normal user is going to become the new cluster's database superuser.

You can also use initdb to correct a corruption of the system database, template1, with the -t or --template parameter.


The following example initializes a new database cluster in the /usr/local/pgsql/booktown_data directory.

$ initdb /usr/local/pgsql/booktown_data
This database system will be initialized with username "postgres".
This user will own all the data files and must also own the server process.
 Creating directory /usr/local/pgsql/booktown_data
 Creating directory /usr/local/pgsql/booktown_data/base
 Creating directory /usr/local/pgsql/booktown_data/global
 Creating directory /usr/local/pgsql/booktown_data/pg_xlog
 Creating template1 database in /usr/local/pgsql/booktown_data/base/1
 DEBUG:  database system was shut down at 2001-08-27 16:51:07 PDT
 DEBUG:  CheckPoint record at (0, 8)
 DEBUG:  Redo record at (0, 8); Undo record at (0, 8); Shutdown TRUE
 DEBUG:  NextTransactionId: 514; NextOid: 16384
 DEBUG:  database system is in production state
 Creating global relations in /usr/local/pgsql/booktown_data/global
 DEBUG:  database system was shut down at 2001-08-27 16:51:14 PDT
 DEBUG:  CheckPoint record at (0, 108)
 DEBUG:  Redo record at (0, 108); Undo record at (0, 0); Shutdown TRUE
 DEBUG:  NextTransactionId: 514; NextOid: 17199
 DEBUG:  database system is in production state
 Initializing pg_shadow.
 Enabling unlimited row width for system tables.
 Creating system views.
 Loading pg_description.
 Setting lastsysoid.
 Vacuuming database.
 Copying template1 to template0.
  Success. You can now start the database server using:
   ./postmaster -D /usr/local/pgsql/booktown_data
    ./pg_ctl -D /usr/local/pgsql/booktown_data -l logfile start