File: app-initdb.html

package info (click to toggle)
mpsql 2.1-2
links: PTS
area: non-free
in suites: potato
size: 3,528 kB
ctags: 4,886
sloc: ansic: 35,184; makefile: 3,761; sh: 44
file content (631 lines) | stat: -rw-r--r-- 10,085 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML
><HEAD
><TITLE
>initdb</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet version 1.19"><LINK
REL="HOME"
TITLE="PostgreSQL User's Guide"
HREF="user.html"><LINK
REL="UP"
TITLE="Utility Applications"
HREF="utilities.html"><LINK
REL="PREVIOUS"
TITLE="destroyuser"
HREF="app-destroyuser.html"><LINK
REL="NEXT"
TITLE="initlocation"
HREF="app-initlocation.html"></HEAD
><BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
><DIV
CLASS="NAVHEADER"
><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>PostgreSQL User's Guide</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="app-destroyuser.html"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="app-initlocation.html"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><SPAN
CLASS="APPLICATION"
>initdb</SPAN
></H1
><DIV
CLASS="REFNAMEDIV"
><H2
>Name</H2
><SPAN
CLASS="APPLICATION"
>initdb</SPAN
> &#8212; Create a new <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> database installation</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><PRE
CLASS="SYNOPSIS"
>initdb [ --pgdata=<TT
CLASS="REPLACEABLE"
><I
>dbdir</I
></TT
> | -r <TT
CLASS="REPLACEABLE"
><I
>dbdir</I
></TT
> ]
    [ --pglib=<TT
CLASS="REPLACEABLE"
><I
>libdir</I
></TT
> | -l <TT
CLASS="REPLACEABLE"
><I
>libdir</I
></TT
> ]
    [ --template=<TT
CLASS="REPLACEABLE"
><I
>template</I
></TT
> | -t <TT
CLASS="REPLACEABLE"
><I
>template</I
></TT
> ]
    [ --username=<TT
CLASS="REPLACEABLE"
><I
>name</I
></TT
> | -u <TT
CLASS="REPLACEABLE"
><I
>name</I
></TT
> ]
    [ --noclean | -n ] [ --debug | -d ]</PRE
><DIV
CLASS="REFSECT2"
><H3
>Inputs</H3
><P
><P
></P
></P><DL
><DT
>--pglib=<TT
CLASS="REPLACEABLE"
><I
>libdir</I
></TT
>, -l <TT
CLASS="REPLACEABLE"
><I
>libdir</I
></TT
>, <TT
CLASS="ENVAR"
>PGLIB</TT
></DT
><DD
><P
>Where are the files that make up <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>? 
 Apart from files that
have to go in particular directories because of their function, the
files that make up the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> software 
were installed in a directory
called the <TT
CLASS="REPLACEABLE"
><I
>libdir</I
></TT
> directory.
An example of a file that will be found
there that <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
needs is <TT
CLASS="FILENAME"
>global1.bki.source</TT
>,
 which contains all the information that goes
into the shared catalog tables.&#13;</P
></DD
><DT
>--pgdata=<TT
CLASS="REPLACEABLE"
><I
>dbdir</I
></TT
>, -r <TT
CLASS="REPLACEABLE"
><I
>dbdir</I
></TT
>, <TT
CLASS="ENVAR"
>PGDATA</TT
></DT
><DD
><P
>Where in your Unix filesystem do you want the database data to go?
The top level directory is called the <TT
CLASS="ENVAR"
>PGDATA</TT
> directory.&#13;</P
></DD
><DT
>--username=<TT
CLASS="REPLACEABLE"
><I
>name</I
></TT
>, -u <TT
CLASS="REPLACEABLE"
><I
>name</I
></TT
>, <TT
CLASS="ENVAR"
>PGUSER</TT
></DT
><DD
><P
>Who will be the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> superuser
 for this database system?  The
<SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> 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
<SPAN
CLASS="APPLICATION"
>initdb</SPAN
>).

<BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>Only the Unix superuser (<TT
CLASS="LITERAL"
>root</TT
>)
 can create a database system with an owner
different from the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> superuser.</P
></BLOCKQUOTE
>&#13;</P
></DD
></DL
><P>&#13;</P
><P
>Other, less commonly used, parameters are also available:

<P
></P
></P><DL
><DT
>--template=<TT
CLASS="REPLACEABLE"
><I
>template</I
></TT
>, -t <TT
CLASS="REPLACEABLE"
><I
>template</I
></TT
></DT
><DD
><P
>Replace the <TT
CLASS="LITERAL"
>template1</TT
>
database in an existing database system, and don't touch anything else.
This is useful when you need to upgrade your <TT
CLASS="LITERAL"
>template1</TT
>
database using <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
from a newer release of <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
>, 
or when your <TT
CLASS="LITERAL"
>template1</TT
>
database has become corrupted by some system problem.  Normally the
contents of <TT
CLASS="LITERAL"
>template1</TT
>
remain constant throughout the life of the database system.  You can't
destroy anything by running <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
with the 
<SPAN
CLASS="OPTION"
>--template</SPAN
>
option.&#13;</P
></DD
><DT
>--noclean, -n</DT
><DD
><P
>By default, when <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
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.&#13;</P
></DD
><DT
>--debug, -d</DT
><DD
><P
>Print debugging output from the bootstrap backend.  
The bootstrap backend is the program <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
uses to create the catalog tables.  This option generates a tremendous
amount of output.  It also turns off the final vacuuming step.&#13;</P
></DD
></DL
><P>&#13;</P
><P
>Files are also input to <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>:

<P
></P
></P><DL
><DT
><SPAN
CLASS="APPLICATION"
>postconfig</SPAN
></DT
><DD
><P
>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.&#13;</P
></DD
><DT
><TT
CLASS="FILENAME"
><TT
CLASS="ENVAR"
>PGLIB</TT
>/global1.bki.source</TT
></DT
><DD
><P
>Contents for the shared catalog tables in the new database system.  This
file is part of the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> software.&#13;</P
></DD
><DT
><TT
CLASS="FILENAME"
><TT
CLASS="ENVAR"
>PGLIB</TT
>/local1_template1.bki.source</TT
></DT
><DD
><P
>Contents for the template1 tables in the new database system.  This
file is part of the <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> software.&#13;</P
></DD
></DL
><P>&#13;</P
></DIV
><DIV
CLASS="REFSECT2"
><H3
>Outputs</H3
><P
><SPAN
CLASS="APPLICATION"
>initdb</SPAN
> will create files in the <TT
CLASS="ENVAR"
>PGDATA</TT
>
data area which are the system tables and framework for a complete
installation.&#13;</P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><H2
>Description</H2
><P
><SPAN
CLASS="APPLICATION"
>initdb</SPAN
> creates a new 
<SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> 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.&#13;</P
><P
>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 <TT
CLASS="LITERAL"
>template1</TT
>
database.  What is the <TT
CLASS="LITERAL"
>template1</TT
>
database?  When you create a database, <SPAN
CLASS="PRODUCTNAME"
>Postgres</SPAN
> 
does it by copying
everything from the <TT
CLASS="LITERAL"
>template1</TT
>
database.  It contains catalog tables filled in for things like the
builtin types.&#13;</P
><P
>After <SPAN
CLASS="APPLICATION"
>initdb</SPAN
> 
creates the database, it completes the initialization by running
<SPAN
CLASS="APPLICATION"
>vacuum</SPAN
>, which resets some optimization parameters.&#13;</P
><P
>There are three ways to give parameters to <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>.

First, you can use <SPAN
CLASS="APPLICATION"
>initdb</SPAN
> command options.
  Second, you can set environment
variables before invoking <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>.  
Third, you can have a program called <SPAN
CLASS="APPLICATION"
>postconfig</SPAN
>
in your Unix command search path. 
<SPAN
CLASS="APPLICATION"
>initdb</SPAN
> invokes that program and that program then writes 
<SPAN
CLASS="APPLICATION"
>initdb</SPAN
> parameters to its standard output stream.
This third option is not a common thing to do, however.&#13;</P
><P
>Command options always override parameters specified any other way.
The values returned by <SPAN
CLASS="APPLICATION"
>postconfig</SPAN
>
override any environment variables, but your
<SPAN
CLASS="APPLICATION"
>postconfig</SPAN
> 
program may base its output on the environment variables if you want
their values to be used.&#13;</P
><P
>The value that <SPAN
CLASS="APPLICATION"
>postconfig</SPAN
> 
outputs must have the format
<PRE
CLASS="PROGRAMLISTING"
>    <TT
CLASS="REPLACEABLE"
><I
>var1</I
></TT
>=<TT
CLASS="REPLACEABLE"
><I
>value1</I
></TT
> <TT
CLASS="REPLACEABLE"
><I
>var2</I
></TT
>=<TT
CLASS="REPLACEABLE"
><I
>value2</I
></TT
> ...</PRE
>

It can output nothing if it doesn't want to supply any parameters.
The <TT
CLASS="REPLACEABLE"
><I
>var</I
></TT
> values are equal to 
the corresponding environment variable
names.  For example,
<PRE
CLASS="PROGRAMLISTING"
>PGDATA=/tmp/postgres_test</PRE
>
has the
same effect as invoking <SPAN
CLASS="APPLICATION"
>initdb</SPAN
>
with an environment variable called <TT
CLASS="ENVAR"
>PGDATA</TT
> whose value is
<TT
CLASS="FILENAME"
>/tmp/postgres_test</TT
>.&#13;</P
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="app-destroyuser.html"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="user.html"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="app-initlocation.html"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><SPAN
CLASS="APPLICATION"
>destroyuser</SPAN
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="utilities.html"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><SPAN
CLASS="APPLICATION"
>initlocation</SPAN
></TD
></TR
></TABLE
></DIV
></BODY
></HTML
>