initdb [-l directory] [-r directory] [-u username] [-t] [-n] [-d]
Creating a database system consists of creating the directories in which the database data will live, generating the shared catalog tables (tables that don't belong to any particular database), and creating the template1 database. What is the template1 database? When you create a database, Postgres does it by copying everything from the template1 database. It contains catalog tables filled in for things like the builtin types.
After initdb creates the database, it vacuum's it.
There are 3 ways to give parameters to initdb. First, you can use initdb command options. Second, you can set environment variables before invoking initdb. Third, you can have a program called postconfig in your Unix command search path. Initdb invokes that program and the program writes initdb parameters to its standard output stream.
Command options always override parameters specified any other way. The values returned by postconfig override any environment variables, but your postconfig program may base its output on the environment variables if you want their values to be used.
The value that postconfig outputs must have the format
var1=value1 var2=value2 ...
It can output nothing if it doesn't want to supply any parameters. The "varN" values are equal to the corresponding environment variable names. For example, outputting "PGDATA=/tmp/postgres_test" has the same effect as invoking initdb with an environment variable called "PGDATA" whose value is "/tmp/postgres_test".
There are 3 parameters you must supply to initdb to tell it how to create the database system:
1) Where are the files that make up Postgres? Apart from files that have to go in particular directories because of their function, the files that make up the Postgres software were installed in a directory called the "pglib" directory. An example of a file that will be found there that initdb needs is global1.bki.source, which contains all the information that goes into the shared catalog tables. Use the --pglib (-l) option or the PGLIB environment variable.
2) Where in your Unix filesystem do you want the database data to go? The top level directory is called the "pgdata" directory. Use the --pgdata (-d) option or the PGDATA environment variable.
3) Who will be the Postgres superuser for this database system? The Postgres superuser is a Unix user that owns all files that store the database system and also owns the postmaster and backend processes that access them. Use the --username (-u) option or the PGUSER environment variable. Or just let it default to you (the Unix user who runs initdb). Note that only the Unix superuser can create a database system with a different user as Postgres superuser.
Initdb understands the following command-line options:
--pglib=directory -l directory
Use the Postgres files in the specified directory, as explained above.
--pgdata=directory -r directory
Put the database system in this directory, as explained above.
--username=username -u username
Build the database system with the specified Unix user as the Postgres superuser for it, as explained above.
--template -t
Replace the template1 database in an existing database system, and don't touch anything else. This is useful when you need to upgrade your template1 database using initdb from a newer release of Postgres, or when your template1 database has become corrupted by some system problem. Normally the contents of template1 remain constant throughout the life of the database system. You can't destroy anything by running initdb with the --template option.
--noclean -n
Run in `noclean' mode. By default, when initdb determines that error prevent it from completely creating the database system, it removes any files it may have created before determining that it can't finish the job. That includes any core files left by the programs it invokes. This option inhibits any tidying-up and is thus useful for debugging.
--debug -d
Print debugging output from the bootstrap backend. The bootstrap backend is the program initdb uses to create the catalog tables. This option generates a tremendous amount of output. It also turns off the final vacuuming step.