247 lines
5.8 KiB
Groff
247 lines
5.8 KiB
Groff
.\" This is -*-nroff-*-
|
|
.\" $Header: /cvsroot/pgsql/src/man/Attic/initdb.1,v 1.4 1998/06/24 13:21:26 momjian Exp $
|
|
.TH INITDB UNIX 11/29/96 PostgreSQL PostgreSQL
|
|
.SH NAME
|
|
initdb - create a new Postgres database system
|
|
.SH SYNOPSIS
|
|
.BR "initdb"
|
|
[\c
|
|
.BR "--pglib="\c
|
|
.IR "directory"\c
|
|
]
|
|
[\c
|
|
.BR "--pgdata="\c
|
|
.IR "directory"\c
|
|
]
|
|
[\c
|
|
.BR "--username="\c
|
|
.IR "username"\c
|
|
]
|
|
[\c
|
|
.BR "--template"\c
|
|
]
|
|
[\c
|
|
.BR "--noclean"\c
|
|
]
|
|
[\c
|
|
.BR "--debug"\c
|
|
]
|
|
|
|
.BR "initdb"
|
|
[\c
|
|
.BR "-l"
|
|
.IR "directory"\c
|
|
]
|
|
[\c
|
|
.BR "-r"
|
|
.IR "directory"\c
|
|
]
|
|
[\c
|
|
.BR "-u"
|
|
.IR "username"\c
|
|
]
|
|
[\c
|
|
.BR "-t"\c
|
|
]
|
|
[\c
|
|
.BR "-n"\c
|
|
]
|
|
[\c
|
|
.BR "-d"\c
|
|
]
|
|
|
|
|
|
.SH DESCRIPTION
|
|
.IR 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.
|
|
.PP
|
|
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
|
|
.IR template1
|
|
database. What is the
|
|
.IR template1
|
|
database? When you create a database, Postgres does it by copying
|
|
everything from the
|
|
.IR template1
|
|
database. It contains catalog tables filled in for things like the
|
|
builtin types.
|
|
.PP
|
|
After
|
|
.IR initdb
|
|
creates the database, it
|
|
.BR vacuum 's
|
|
it.
|
|
.PP
|
|
There are 3 ways to give parameters to
|
|
.IR initdb .
|
|
First, you can use initdb command options. Second, you can set environment
|
|
variables before invoking initdb. Third, you can have a program called
|
|
.IR postconfig
|
|
in your Unix command search path.
|
|
.IR Initdb
|
|
invokes that program and the program writes
|
|
.IR initdb
|
|
parameters to its standard output stream.
|
|
.PP
|
|
Command options always override parameters specified any other way.
|
|
The values returned by
|
|
.IR postconfig
|
|
override any environment variables, but your
|
|
.IR postconfig
|
|
program may base its output on the environment variables if you want
|
|
their values to be used.
|
|
.PP
|
|
The value that
|
|
.IR postconfig
|
|
outputs must have the format
|
|
.PP
|
|
var1=value1 var2=value2 ...
|
|
.PP
|
|
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
|
|
.IR initdb
|
|
with an environment variable called "PGDATA" whose value is
|
|
"/tmp/postgres_test".
|
|
.PP
|
|
There are 3 parameters you must supply to initdb to tell it how to
|
|
create the database system:
|
|
.PP
|
|
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
|
|
.IR initdb
|
|
needs is global1.bki.source, which contains all the information that goes
|
|
into the shared catalog tables. Use the
|
|
.BR --pglib
|
|
(\c
|
|
.BR -l )
|
|
option or the
|
|
.BR PGLIB
|
|
environment variable.
|
|
.PP
|
|
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
|
|
.BR --pgdata
|
|
(\c
|
|
.BR -d )
|
|
option or the
|
|
.BR PGDATA
|
|
environment variable.
|
|
.PP
|
|
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
|
|
.BR --username
|
|
(\c
|
|
.BR -u )
|
|
option or the
|
|
.BR PGUSER
|
|
environment variable. Or just let it default to you (the Unix user who
|
|
runs
|
|
.IR initdb ).
|
|
Note that only the Unix superuser can create a database system with a
|
|
different user as Postgres superuser.
|
|
|
|
|
|
|
|
.PP
|
|
.IR Initdb
|
|
understands the following command-line options:
|
|
|
|
.BR "--pglib="\c
|
|
.IR "directory"
|
|
.BR "-l"
|
|
.IR "directory"
|
|
|
|
Use the Postgres files in the specified directory, as explained above.
|
|
|
|
.BR "--pgdata="\c
|
|
.IR "directory"
|
|
.BR "-r"
|
|
.IR "directory"
|
|
|
|
Put the database system in this directory, as explained above.
|
|
|
|
.BR "--username="\c
|
|
.IR "username"
|
|
.BR "-u"
|
|
.IR "username"
|
|
|
|
Build the database system with the specified Unix user as the Postgres
|
|
superuser for it, as explained above.
|
|
|
|
.BR "--template"
|
|
.BR "-t"
|
|
|
|
Replace the
|
|
.IR template1
|
|
database in an existing database system, and don't touch anything else.
|
|
This is useful when you need to upgrade your
|
|
.IR template1
|
|
database using
|
|
.IR initdb
|
|
from a newer release of Postgres, or when your
|
|
.IR template1
|
|
database has become corrupted by some system problem. Normally the
|
|
contents of
|
|
.IR template1
|
|
remain constant throughout the life of the database system. You can't
|
|
destroy anything by running
|
|
.IR initdb
|
|
with the
|
|
.BR --template
|
|
option.
|
|
|
|
.BR "--noclean"
|
|
.BR "-n"
|
|
|
|
Run in \*(lqnoclean\*(rq mode. By default,
|
|
when
|
|
.IR 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.
|
|
|
|
.BR "--debug"
|
|
.BR "-d"
|
|
|
|
Print debugging output from the bootstrap backend.
|
|
The bootstrap backend is the program
|
|
.IR initdb
|
|
uses to create the catalog tables. This option generates a tremendous
|
|
amount of output. It also turns off the final vacuuming step.
|
|
|
|
|
|
.SH FILES
|
|
.TP
|
|
postconfig
|
|
(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 above.
|
|
.TP
|
|
PGLIB/global1.bki.source
|
|
Contents for the shared catalog tables in the new database system. This
|
|
file is part of the Postgres software.
|
|
.TP
|
|
PGLIB/local1_template1.bki.source
|
|
Contents for the template1 tables in the new database system. This
|
|
file is part of the Postgres software.
|
|
|
|
.SH "SEE ALSO"
|
|
vacuum(l),
|
|
bki(5),
|
|
create_database(l),
|
|
createuser(1),
|
|
psql(1).
|