initdb [ --pgdata=dbdir | -r dbdir ]
[ --pglib=libdir | -l libdir ]
[ --template=template | -t template ]
[ --username=name | -u name ]
[ --noclean | -n ] [ --debug | -d ]
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 libdir 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.
Where in your Unix filesystem do you want the database data to go? The top level directory is called the PGDATA directory.
Who will be the Postgres superuser for this database system? The Postgres superuser is a Unix user who owns all files that store the database system and also owns the postmaster and backend processes that access them. Or just let it default to you (the Unix user who runs initdb).
Note: Only the Unix superuser (root) can create a database system with an owner different from the Postgres superuser.
Other, less commonly used, parameters are also available:
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.
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.
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.
Files are also input to initdb:
If appearing somewhere in the Unix command search path (defined by the PATH environment variable). This is a program that specifies defaults for some of the command options. See below.
Contents for the shared catalog tables in the new database system. This file is part of the Postgres software.
Contents for the template1 tables in the new database system. This file is part of the Postgres software.
initdb will create files in the PGDATA data area which are the system tables and framework for a complete installation.
initdb creates a new Postgres database system. A database system is a collection of databases that are all administered by the same Unix user and managed by a single postmaster.
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 completes the initialization by running vacuum, which resets some optimization parameters.
There are three 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 that program then writes initdb parameters to its standard output stream. This third option is not a common thing to do, however.
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 var values are
equal to the corresponding environment variable names. For example,
PGDATA=/tmp/postgres_testhas the same effect as invoking initdb with an environment variable called PGDATA whose value is /tmp/postgres_test.