INITDB(1)                                               INITDB(1)

NAME
       initdb - Create a new Postgres database installation

SYNOPSIS
       initdb [ --pgdata=dbdir | -r dbdir ]
           [ --pglib=libdir | -l libdir ]
           [ --template=template | -t template ]
           [ --username=name | -u name ]
           [ --noclean | -n ] [ --debug | -d ]

   INPUTS
       --pglib=libdir

       -l libdir

       PGLIB  Where  are  the files that make up Postgres?  Apart
              from files that have to go in  particular  directo-
              ries because of their function, the files that make
              up the Postgres software were installed in a direc-
              tory  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 informa-
              tion that goes into the shared catalog tables.

       --pgdata=dbdir

       -r dbdir

       PGDATA Where in your  Unix  filesystem  do  you  want  the
              database  data  to  go?  The top level directory is
              called the PGDATA directory.

       --username=name

       -u name

       PGUSER 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:

       --template=template

       -t template
              Replace  the  template1  database  in  an  existing
              database system, and  don't  touch  anything  else.
              This  is  useful when you need to upgrade your tem-
              plate1 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 through-
              out the life of  the  database  system.  You  can't
              destroy  anything by running initdb with the --tem-
              plate option.

       --noclean

       -n     By default, when initdb determines that error  pre-
              vent  it from completely creating the database sys-
              tem, 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 are also input to initdb:

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

       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.

   OUTPUTS
       initdb will create files in the PGDATA data area which are
       the system tables and framework for a  complete  installa-
       tion.

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 completes the ini-
       tialization by running vacuum, which resets some optimiza-
       tion parameters.

       There are three ways to give parameters to initdb.

       o You can use initdb command options.

       o You   can  set  environment  variables  before  invoking
         initdb.

       o 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  stan-
         dard  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_test

       has the same effect as invoking initdb with an environment
       variable  called PGDATA whose value is /tmp/postgres_test.

Application               15 August 1999                        1