INITDB(UNIX)
NAME
initdb - create a new Postgres database system
SYNOPSIS
initdb [--pglib=directory] [--pgdata=directory] [--user-
name=username] [--template] [--noclean] [--debug]
initdb [-l directory] [-r directory] [-u username] [-t]
[-n] [-d]
DESCRIPTION
Initdb Creates a new Postgres database system. A database
system is a collection of databases that are all adminis-
tered by the same Unix user and managed by a single post-
master.
Creating a database system consists of creating the direc-
tories 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 envi-
ronment 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 corre-
sponding environment variable names. For example, out-
putting "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 soft-
ware 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 environ-
ment 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 vari-
able. Or just let it default to you (the Unix user who
runs initdb). Note that only the Unix superuser can cre-
ate 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 tem-
plate1 database has become corrupted by some system
problem. Normally the contents of template1 remain con-
stant throughout the life of the database system. You
can't destroy anything by running initdb with the --tem-
plate 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.
FILES
postconfig
(Somewhere in the Unix command search path (defined
by the PATH environment variable)). This is a pro-
gram that specifies defaults for some of the com-
mand options. See above.
PGLIB/global1.bki.source
Contents for the shared catalog tables in the new
database system. This file is part of the Postgres
software.
PGLIB/local1_template1.bki.source
Contents for the template1 tables in the new
database system. This file is part of the Postgres
software.
SEE ALSO
vacuum(l) bki(5) create_database(l) createuser(1)
psql(1)