<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title> Practical PostgreSQL</title>
<meta name="keywords" content="postgresql, support, recovery, design, software, hosting, expterise, programming, postgres, pgsql, replication, mysql, firebird, database, sql, free, open source, software" />
<meta name="description" content="Command Prompt, Inc. is the largest and oldest US based commercial PostgreSQL support provider. We provide the only commercially viable integrated PostgreSQL replication solution, but also custom programming, and support. We authored the book Practical PostgreSQL, the procedural language plPHP, and adding trigger capability to plPerl. " />
<link rel="shortcut icon" href="../favicon.ico" type="image/x-icon" />
<link rel="stylesheet" type="text/css" href="../css/layout.css" />
<link rel="stylesheet" type="text/css" href="../css/cmd4.css" />
<script language="javascript" type="text/javascript"><!--
greymenuhomewideLit = new Image();
greymenuhomewideLit.src = "/images/greymenu_homewide_lit.gif";
greymenuaboutLit = new Image();
greymenuaboutLit.src = "/images/greymenu_about_lit.gif";
greymenuproductsLit = new Image();
greymenuproductsLit.src = "/images/greymenu_products_lit.gif";
greymenuservicesLit = new Image();
greymenuservicesLit.src = "/images/greymenu_services_lit.gif";
greymenusupportLit = new Image();
greymenusupportLit.src = "/images/greymenu_support_lit.gif";
greymenucommunityLit = new Image();
greymenucommunityLit.src = "/images/greymenu_community_lit.gif";
//--></script>
</head>
<body>
<div align="center">
<div id="widecontainer">
<div id="widetop">
<div class="throwleft" style="width: 300px; text-align: left;"><a href="http://www.commandprompt.com/"><img src="../images/cmd4logo_wide.gif" border="0" alt="Command Prompt, Inc." /></a></div>
<div class="throwright" style="width: 400px; text-align: right;">
<div id="topright">
<form action="index.html" name="cmdform" method="post">
<ul>
<li><input type="text" name="search" value="" /></li>
<li><input type="submit" name="action" value="Search Book" /></li>
</ul>
</form>
</div>
</div>
</div>
<ul id="greymenu_wide">
<li><a href="http://www.commandprompt.com/home/"><img onmouseover="this.src = greymenuhomewideLit.src;" onmouseout="this.src = '/images/greymenu_homewide.gif';" src="../images/greymenu_homewide.gif" border="0" height="22" title="" alt="" /></a></li><li><img src="../images/greymenu_divider.gif" border="0" width="2" height="22" alt="|" /></li><li><a href="http://www.commandprompt.com/about/"><img onmouseover="this.src = greymenuaboutLit.src;" onmouseout="this.src = '/images/greymenu_about.gif';" src="../images/greymenu_about.gif" border="0" height="22" title="" alt="" /></a></li><li><img src="../images/greymenu_divider.gif" border="0" width="2" height="22" alt="|" /></li><li><a href="http://www.commandprompt.com/products/"><img onmouseover="this.src = greymenuproductsLit.src;" onmouseout="this.src = '/images/greymenu_products.gif';" src="../images/greymenu_products.gif" border="0" height="22" title="" alt="" /></a></li><li><img src="../images/greymenu_divider.gif" border="0" width="2" height="22" alt="|" /></li><li><a href="http://www.commandprompt.com/services/"><img onmouseover="this.src = greymenuservicesLit.src;" onmouseout="this.src = '/images/greymenu_services.gif';" src="../images/greymenu_services.gif" border="0" height="22" title="" alt="" /></a></li><li><img src="../images/greymenu_divider.gif" border="0" width="2" height="22" alt="|" /></li><li><a href="http://www.commandprompt.com/support/"><img onmouseover="this.src = greymenusupportLit.src;" onmouseout="this.src = '/images/greymenu_support.gif';" src="../images/greymenu_support.gif" border="0" height="22" title="" alt="" /></a></li><li><img src="../images/greymenu_divider.gif" border="0" width="2" height="22" alt="|" /></li><li><a href="http://www.commandprompt.com/community/"><img onmouseover="this.src = greymenucommunityLit.src;" onmouseout="this.src = '/images/greymenu_community.gif';" src="../images/greymenu_community.gif" border="0" height="22" title="" alt="" /></a></li> </ul>
<div style="padding-left: 16px; width: 96%;">
<HTML
><HEAD
><TITLE
>10 Steps to Installing PostgreSQL</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.72
"><LINK
REL="HOME"
TITLE="Practical PostgreSQL"
href="book1"><LINK
REL="UP"
TITLE="Installing PostgreSQL"
href="c360"><LINK
REL="PREVIOUS"
TITLE="Installing PostgreSQL"
href="c360"><LINK
REL="NEXT"
TITLE="Using PostgreSQL"
href="p1162"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Practical PostgreSQL</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
href="c360"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 2. Installing PostgreSQL</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
href="p1162"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="TENSTEPSTOINSTALLINGPOSTGRESQL"
>10 Steps to Installing PostgreSQL</A
></H1
><P
>PostgreSQL is included on the CD distributed with this book, but you may want to visit the PostgreSQL website to see if
there is a newer version available. Many FTP sites make the source files for PostgreSQL available for download; a complete
list of FTP mirrors can be found at <SPAN
><I
CLASS="EMPHASIS"
>http://www.postgresql.org</I
></SPAN
>.</P
><P
>Once you have connected to a PostgreSQL FTP mirror, you will see the stable releases located within a directory
beginning with <SPAN
><I
CLASS="EMPHASIS"
>v</I
></SPAN
> followed by a version (such as <SPAN
><I
CLASS="EMPHASIS"
>v7.1.3/</I
></SPAN
>). There should also be a
symbolic link to the most recent stable release’s directory called <SPAN
><I
CLASS="EMPHASIS"
>latest/</I
></SPAN
>.</P
><P
>Within this sub-directory is a list of package files. The complete PostgreSQL installation package is named
<SPAN
><I
CLASS="EMPHASIS"
>postgresql-[version].tar.gz</I
></SPAN
> and should be the largest file in the list. The following sub-packages are
also made available for download, and may be installed in any combination (though at least <SPAN
><I
CLASS="EMPHASIS"
>base</I
></SPAN
> is
required):</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>postgresql-base-[version].tar.gz</DT
><DD
><P
> The <SPAN
><I
CLASS="EMPHASIS"
>base</I
></SPAN
> package contains the bare minimum of source code required to build and run PostgreSQL.
</P
></DD
><DT
>postgresql-docs-[version].tar.gz</DT
><DD
><P
> The <SPAN
><I
CLASS="EMPHASIS"
>docs</I
></SPAN
> package contains the PostgreSQL documentation in HTML format. Note that the PostgreSQL
<SPAN
><I
CLASS="EMPHASIS"
>man</I
></SPAN
> pages are automatically installed with the <SPAN
><I
CLASS="EMPHASIS"
>base</I
></SPAN
> package.
</P
></DD
><DT
>postgresql-opt-[version].tar.gz</DT
><DD
><P
> The <SPAN
><I
CLASS="EMPHASIS"
>opt</I
></SPAN
> package contains several optional extensions to PostgreSQL, such as the interfaces for
C++ (<SPAN
><I
CLASS="EMPHASIS"
>libpq++</I
></SPAN
>), JDBC, ODBC, Perl, Python, and Tcl. It also contains the source required for
multibyte support.
</P
></DD
><DT
>postgresql-test-[version].tar.gz</DT
><DD
><P
> The <SPAN
><I
CLASS="EMPHASIS"
>test</I
></SPAN
> package contains the regression test suite. This package is required to run regression
tests after compiling PostgreSQL.
</P
></DD
></DL
></DIV
>
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN528"
>Step 1: Creating the “postgres” User</A
></H2
><P
>Create a UNIX user account to own and manage the PostgreSQL database files. Typically, this user is named
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
>, but it can be named anything that you choose. For consistency throughout the book, the user
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> is considered the PostgreSQL root or superuser.</P
><P
>You will need to have root privileges to create the PostgreSQL superuser. On a Linux machine, you can use the
command shown in <A
href="x486#ADDINGPOSTGRES"
>Example 2-5</A
> to add the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="ADDINGPOSTGRES"
></A
><P
><B
>Example 2-5. Adding the postgres User</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>su - -c "useradd postgres"</B
></TT
></PRE
></DIV
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Warning</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>Do not try to use the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user as the PostgreSQL superuser. Doing so presents a large
security hole.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN547"
>Step 2: Installing the PostgreSQL Source Package</A
></H2
><P
>Once you have acquired the source for PostgreSQL, you should copy the PostgreSQL source package to a temporary
compilation directory. This directory will be the path where you install and configure PostgreSQL. Within this path, you
will extract the contents from the <SPAN
><I
CLASS="EMPHASIS"
>tar.gz</I
></SPAN
> file and proceed with installation.</P
><P
>Bear in mind that this will not be the location of the installed database files. This is a temporary location for
configuration and compilation of the source package itself. If you have downloaded the PostgreSQL package from the
Internet, it is probably not saved in your intended compilation directory (unless you explicitly chose to save there). A
common convention for building source on UNIX and Linux machines is to build within the <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src</I
></SPAN
>
path. You will most likely need root privileges to access this path. As such, the remaining examples in this chapter will
involve the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user until otherwise specified.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>If you are a user of a commercial Linux distribution, we strongly suggest that you verify whether or not you have
PostgreSQL already installed. On RPM-based systems, such as SuSe, Mandrake, or RedHat, this can be done by using the
following command: <SPAN
><I
CLASS="EMPHASIS"
>rpm -qa | grep -i postgres</I
></SPAN
>. If you do have PostgreSQL installed, there is a good
chance that it is outdated. You will want to download and install the latest version of PostgreSQL available. An RPM
installation of PostgreSQL will sometimes install scripts and programs such as <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> and
<SPAN
><I
CLASS="EMPHASIS"
>psql</I
></SPAN
> into globally accessible directories. This can cause conflicts with source-built versions, so
before installing a new version, be sure to remove the RPM by using the <SPAN
><I
CLASS="EMPHASIS"
>rpm -e <package name></I
></SPAN
>
command.</P
></BLOCKQUOTE
></DIV
><P
>To unpack PostgreSQL source code on a Linux system, first move (or copy, from the CD) the compressed source file into
<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src</I
></SPAN
> (most people move their source files here to keep them separate from their home
directories and/or other locations they may keep downloaded files). After moving it to the filesystem location where you
wish to unpack it, use <SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> to unpack the source files. The commands to perform these actions are
shown in <A
href="x486#UNPACKSOURCE"
>Example 2-6</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="UNPACKSOURCE"
></A
><P
><B
>Example 2-6. Unpacking the PostgreSQL source package</B
></P
><PRE
CLASS="SCREEN"
>[root@host root]# <TT
CLASS="USERINPUT"
><B
>mv postgresql-7.1.3.tar.gz /usr/local/src</B
></TT
>
[root@host root]# <TT
CLASS="USERINPUT"
><B
>cd /usr/local/src</B
></TT
>
[root@host src]# <TT
CLASS="USERINPUT"
><B
>tar -xzvf postgresql-7.1.3.tar.gz</B
></TT
>
postgresql-7.1.3/
postgresql-7.1.3/ChangeLogs/
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1-7.1.1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC1-to-7.1RC2
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC2-to-7.1RC3
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1RC3-to-7.1rc4
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta1-to-7.1beta3
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta3-to-7.1beta4
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta4-to-7.1beta5
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta5-to-7.1beta6
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1beta6-7.1RC1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1rc4-7.1
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1.1-7.1.2
postgresql-7.1.3/ChangeLogs/ChangeLog-7.1.2-7.1.3
postgresql-7.1.3/COPYRIGHT
[...]
[root@host root]# <TT
CLASS="USERINPUT"
><B
>chown -R postgres.postgres postgresql-7.1.3</B
></TT
></PRE
></DIV
><P
>Notice the last command used in <A
href="x486#UNPACKSOURCE"
>Example 2-6</A
>. The command is
<SPAN
><I
CLASS="EMPHASIS"
>chown -R postgres.postgres postgresql-7.1.3</I
></SPAN
>. This command grants the ownership of the PostgreSQL
source directory tree to <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
>, which in turn enables you to compile PostgreSQL as the
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user. Once the extraction and ownership change has completed, you can switch to the
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user to compile PostgreSQL, resulting in all compiled files automatically being owned by
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
>.</P
><P
>For reference purposes, the following list is a description of the <SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> options used to extract
the PostgreSQL source distribution:</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>x (extract)</DT
><DD
><P
><SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> will extract from the passed filename (as opposed to creating a new
file).</P
></DD
><DT
>v (verbose)</DT
><DD
><P
><SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> will print verbose output as files are extracted. You may omit this flag if you
do not wish to see each file as it is unpacked.</P
></DD
><DT
>z (zipped)</DT
><DD
><P
><SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> will use <SPAN
><I
CLASS="EMPHASIS"
>gunzip</I
></SPAN
> to decompress the source. This option
assumes that you are using the GNU tools; other versions of <SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> may not support the
<SPAN
><I
CLASS="EMPHASIS"
>z</I
></SPAN
> flag. In the event that you are not using the GNU tools, you will need to manually unzip the file
using <SPAN
><I
CLASS="EMPHASIS"
>gunzip</I
></SPAN
> before you can unpack it with <SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
>.</P
></DD
><DT
>f (file)</DT
><DD
><P
><SPAN
><I
CLASS="EMPHASIS"
>tar</I
></SPAN
> will use the filename following the <SPAN
><I
CLASS="EMPHASIS"
>f</I
></SPAN
> parameter to
determine which file to extract. In our examples, this file is <SPAN
><I
CLASS="EMPHASIS"
>postgresql-7.1.3.tar.gz</I
></SPAN
>.</P
></DD
></DL
></DIV
>
</P
><P
>After you have completed the extraction of the files, switch to the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user and change
into the newly created directory (e.g., <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src/postgres-7.1.3</I
></SPAN
>). The remaining installation
steps will take place in that directory.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="SECTCONFIGURINGSOURCETREE"
>Step 3: Configuring the Source Tree</A
></H2
><P
>Before compilation, you must configure the source, and specify installation options specific to your needs. This is done
with the <SPAN
><I
CLASS="EMPHASIS"
>configure</I
></SPAN
> script.</P
><P
>The <SPAN
><I
CLASS="EMPHASIS"
>configure</I
></SPAN
> script is also used to check for software dependencies that are required to compile
PostgreSQL. As <SPAN
><I
CLASS="EMPHASIS"
>configure</I
></SPAN
> checks for dependencies, it will create the necessary files for use with
the <SPAN
><I
CLASS="EMPHASIS"
>gmake</I
></SPAN
> command.</P
><P
>To use the default installation script, issue the following command: <SPAN
><I
CLASS="EMPHASIS"
>./configure</I
></SPAN
>. To specify
options that will enable certain non-default features, append the option to the <SPAN
><I
CLASS="EMPHASIS"
>./configure</I
></SPAN
> command.
For a list of all the available configuration options, use <SPAN
><I
CLASS="EMPHASIS"
>./configure --help</I
></SPAN
> </P
><P
>There is a good chance that the default source configuration that <SPAN
><I
CLASS="EMPHASIS"
>configure</I
></SPAN
> uses will not be the
setup you require. For a well-rounded PostgreSQL installation, we recommend you use at least the following options:</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>--with-CXX</DT
><DD
><P
> Allows you to build C++ programs for use with PostgreSQL by building the <SPAN
><I
CLASS="EMPHASIS"
>libpq++</I
></SPAN
> library.
</P
></DD
><DT
>--enable-odbc</DT
><DD
><P
> Allows you to connect to PostgreSQL with programs that have a compatible ODBC driver (such as Microsoft Access).
</P
></DD
><DT
>--enable-multibyte</DT
><DD
><P
> Allows multibyte characters to be used, such as non-English language characters (e.g., Kanji).
</P
></DD
><DT
>--with-maxbackends=<TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
></DT
><DD
><P
> Sets <TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
> as the maximum number of allowed connections (32, by default).
</P
></DD
></DL
></DIV
>
</P
><P
>You can also specify anything from the following complete list of configuration options:</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>--prefix=<TT
CLASS="REPLACEABLE"
><I
>PREFIX</I
></TT
></DT
><DD
><P
>Specifies that files should be installed under the directory
provided with <TT
CLASS="REPLACEABLE"
><I
>PREFIX</I
></TT
>, instead of the
default installation directory (<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql</I
></SPAN
>).
</P
></DD
><DT
>--exec-prefix=<TT
CLASS="REPLACEABLE"
><I
>EXEC-PREFIX</I
></TT
></DT
><DD
><P
>Specifies that architecture-dependent executable files should be installed
under the directory supplied with <TT
CLASS="REPLACEABLE"
><I
>EXEC-PREFIX</I
></TT
>.</P
></DD
><DT
>--bindir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that user executable files (such as <SPAN
><I
CLASS="EMPHASIS"
>psql</I
></SPAN
>)
should be installed into the directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>.
</P
></DD
><DT
>--datadir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that the database should install data files
used by PostgreSQL's program suite (as well as sample
configuration files) into the directory supplied with
<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>. Note that the directory here
is <TT
CLASS="REPLACEABLE"
><I
>not</I
></TT
> used as an alternate
database data directory; it is merely the directory where read-only files used
by the program suite are installed.
</P
></DD
><DT
>--sysconfdir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that system configuration files should be installed into the
directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>. By default, these are put
into the <SPAN
><I
CLASS="EMPHASIS"
>etc</I
></SPAN
> folder within the specified base installation directory.</P
></DD
><DT
>--libdir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that library files should be stored in the directory supplied
with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>. If you are running Linux, this directory
should also be entered into the <SPAN
><I
CLASS="EMPHASIS"
>ld.so.conf</I
></SPAN
> file.</P
></DD
><DT
>--includedir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that C and C++ header files should be installed into the directory
supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>. By default, include files are stored in
the <SPAN
><I
CLASS="EMPHASIS"
>include</I
></SPAN
> folder within the base installation directory.</P
></DD
><DT
>--docdir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that documentation files should be installed into the directory
supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>. This does not include PostgreSQL's
<SPAN
><I
CLASS="EMPHASIS"
>man</I
></SPAN
> files.</P
></DD
><DT
>--mandir=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that <SPAN
><I
CLASS="EMPHASIS"
>man</I
></SPAN
> files should be installed into the
directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>.</P
></DD
><DT
>--with-includes=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORIES</I
></TT
></DT
><DD
><P
>Specifies that the colon-separated list of directories supplied with
<TT
CLASS="REPLACEABLE"
><I
>DIRECTORIES</I
></TT
> should be searched with the purpose of locating additional header files.</P
></DD
><DT
>--with-libraries=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORIES</I
></TT
></DT
><DD
><P
>Specifies that the colon-separated list of directories supplied with
<TT
CLASS="REPLACEABLE"
><I
>DIRECTORIES</I
></TT
> should be searched with the purpose of locating additional libraries.</P
></DD
><DT
>--enable-locale</DT
><DD
><P
>Enables locale support. The use of
locale support will incur a performance penalty and should
only be enabled if you are are not in an English-speaking
location.</P
></DD
><DT
>--enable-recode</DT
><DD
><P
>Enables the use of the <SPAN
><I
CLASS="EMPHASIS"
>recode</I
></SPAN
> translation library.</P
></DD
><DT
>--enable-multibyte</DT
><DD
><P
>Enables multibyte encoding. Enabling this option allows the support of non-ASCII
characters; this is most useful with languages such as Japanese, Korean, and Chinese, which all
use nonstandard character encoding.</P
></DD
><DT
>--with-pgport=<TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
></DT
><DD
><P
>Specifies that the the port number supplied with <TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
>
should be used as the default port by PostgreSQL. This can be
changed when starting the <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> application.</P
></DD
><DT
>--with-maxbackends=<TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
></DT
><DD
><P
> Sets <TT
CLASS="REPLACEABLE"
><I
>NUMBER</I
></TT
> as the maximum number of allowed connections (32, by default).
</P
></DD
><DT
>--with-CXX</DT
><DD
><P
>Specifies that the C++ interface library should be compiled during installation.
You will need this library if you plan to develop C++ applications for use with
PostgreSQL.</P
></DD
><DT
>--with-perl</DT
><DD
><P
>Specifies that the PostgreSQL Perl interface module should be compiled during installation.
This module will need to be installed in a directory that is usually owned by <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
>, so you will
most likely need to be logged in as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user to complete installation with this option
chosen. This configuration option is only required if you plan to use the pl/Perl procedural
language.</P
></DD
><DT
>--with-python</DT
><DD
><P
>Specifies that the PostgreSQL Python interface module should be compiled during installation.
As with the <SPAN
><I
CLASS="EMPHASIS"
>--with-perl</I
></SPAN
> option, you will most likely need to log in as
the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user to complete installation with this option. This option is only required if you plan
to use the pl/Python procedural language.</P
></DD
><DT
>--with-tcl</DT
><DD
><P
>Specifies that Tcl support should be included in the installation. This option will install
PostgreSQL applications and extensions that require Tcl, such as <SPAN
><I
CLASS="EMPHASIS"
>pgaccess</I
></SPAN
> (a popular
graphical database client) and the pl/Tcl procedural language.</P
></DD
><DT
>--without-tk</DT
><DD
><P
>Specifies that Tcl support should be compiled without additional support for Tk, the graphical
application tool kit. Using this option with the <SPAN
><I
CLASS="EMPHASIS"
>--with-tcl</I
></SPAN
> option specifies that
PostgreSQL Tcl applications that require Tk (such as <SPAN
><I
CLASS="EMPHASIS"
>pgtksh</I
></SPAN
> and
<SPAN
><I
CLASS="EMPHASIS"
>pgaccess</I
></SPAN
>) should not be installed.</P
></DD
><DT
>--with-tclconfig=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>, --with-tkconfig=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that the Tcl or Tk (depending on the option) configuration file (either <SPAN
><I
CLASS="EMPHASIS"
>tclConfig.sh</I
></SPAN
> or <SPAN
><I
CLASS="EMPHASIS"
>tkConfig.sh</I
></SPAN
>)
is located in the directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>, instead of the default directory. These two files
are installed by Tcl/Tk, and the information within them is required by PostgreSQL's Tcl/Tk interface modules.</P
></DD
><DT
>--enable-odbc</DT
><DD
><P
>Enables support for ODBC.</P
></DD
><DT
>--with-odbcinst=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Specifies that the ODBC driver should look in the directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
> for its <SPAN
><I
CLASS="EMPHASIS"
>odbcinst.ini</I
></SPAN
> file. By default, this file is held in the <SPAN
><I
CLASS="EMPHASIS"
>etc</I
></SPAN
> directory,
which is located in the installation directory.</P
></DD
><DT
>--with-krb4=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>, --with-krb5=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Enables support for the Kerberos authentication
system. The use of Kerberos is not covered in this book.
</P
></DD
><DT
>--with-krb-srvnam=<TT
CLASS="REPLACEABLE"
><I
>NAME</I
></TT
></DT
><DD
><P
>Specifies the name of the Kerberos service principal. By default, <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> is
set as the service principal name.</P
></DD
><DT
>--with-openssl=<TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
></DT
><DD
><P
>Enables the use of SSL to support encrypted database connections. To build support for SSL,
OpenSSL must be configured correctly and installed in the directory supplied with <TT
CLASS="REPLACEABLE"
><I
>DIRECTORY</I
></TT
>.
This option is required if you plan on using the <SPAN
><I
CLASS="EMPHASIS"
>stunnel</I
></SPAN
> tool.
</P
></DD
><DT
>--with-java</DT
><DD
><P
>Enables Java/JDBC support. The <SPAN
><I
CLASS="EMPHASIS"
>Ant</I
></SPAN
> and JDK packages
are required for PostgreSQL to compile correctly with this feature enabled.</P
></DD
><DT
>--enable-syslog</DT
><DD
><P
>Enables the use of the <SPAN
><I
CLASS="EMPHASIS"
>syslog</I
></SPAN
> daemon for logging. You will need
to specify that you wish to use <SPAN
><I
CLASS="EMPHASIS"
>syslog</I
></SPAN
> for logging at runtime if you wish
to use it.</P
></DD
><DT
>--enable-debug</DT
><DD
><P
>Enables the compilation of all PostgreSQL libraries and applications with debugging
symbols. This will slow down performance and increase binary file size, but the debugging symbols
are useful for developers to help diagnose bugs and problems that can be encountered with PostgreSQL.
</P
></DD
><DT
>--enable-cassert</DT
><DD
><P
>Enables assertion checking. This feature slows down performance and should be used
only during development of PostgreSQL
database itself.
</P
></DD
></DL
></DIV
><P
>If you compile PostgreSQL and find that you are missing a feature, you can return to this step, reconfigure, and
continue with the subsequent steps to build and install PostgreSQL. If you choose to come back to this step and reconfigure
the PostgreSQL source before installing, be sure to use the <SPAN
><I
CLASS="EMPHASIS"
>gmake clean</I
></SPAN
> command from the top-level
directory of the source tree (usually, <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src/postgresql-[version]</I
></SPAN
> ). This will remove any
leftover object files and partially compiled files.</P
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN852"
>Step 4: Compiling the Source</A
></H2
><P
>After using the <SPAN
><I
CLASS="EMPHASIS"
>configure</I
></SPAN
> command, you may begin compiling the PostgreSQL source by entering the
<SPAN
><I
CLASS="EMPHASIS"
>gmake</I
></SPAN
> command.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>On Linux machines, you should be able to use <SPAN
><I
CLASS="EMPHASIS"
>make</I
></SPAN
> instead of <SPAN
><I
CLASS="EMPHASIS"
>gmake</I
></SPAN
>. BSD
users should use <SPAN
><I
CLASS="EMPHASIS"
>gnumake</I
></SPAN
>.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="COMPILESOURCE"
></A
><P
><B
>Example 2-7. Compiling the source with GNU make</B
></P
><PRE
CLASS="SCREEN"
>[postgres@host postgresql-7.1.3]# <TT
CLASS="USERINPUT"
><B
>gmake</B
></TT
>
gmake -C doc all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
gmake[1]: Nothing to be done for all'.
gmake[1]: Leaving directory /usr/local/src/postgresql-7.1.3/doc'
gmake -C src all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/src'
gmake -C backend all
gmake[2]: Entering directory /usr/local/src/postgresql-7.1.3/src/backend'
gmake -C utils fmgroids.h
gmake[3]: Entering directory /usr/local/src/postgresql-7.1.3/src/backend/utils'
[...]</PRE
></DIV
><P
>At this point, depending on the speed of your machine, you may want to get some coffee because the PostgreSQL
compilation could take 10 minutes, an hour, or even more. After the compilation has finished, the following message should
appear: </P
><PRE
CLASS="SCREEN"
>All of PostgreSQL is successfully made. Ready to install.</PRE
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN872"
>Step 5: Regression Testing</A
></H2
><P
><SPAN
><I
CLASS="EMPHASIS"
>Regression tests</I
></SPAN
> are an optional but recommended step. The regression tests help verify that
PostgreSQL will run as expected after you have compiled the source. The tests check tasks such as standard SQL operations,
as well as extended capabilities of PostgreSQL. The regression tests can point out possible (but not necessarily probable)
problems which may arise when running PostgreSQL.</P
><P
>If you decide you would like to run the regression tests, do so by using the following command: <SPAN
><I
CLASS="EMPHASIS"
>gmake check</I
></SPAN
>,
as shown in <A
href="x486#MAKEREGRESSIONTESTS"
>Example 2-8</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="MAKEREGRESSIONTESTS"
></A
><P
><B
>Example 2-8. Making regression tests</B
></P
><PRE
CLASS="SCREEN"
>[postgres@host postgresql-7.1.3]# <TT
CLASS="USERINPUT"
><B
>gmake check</B
></TT
>
gmake -C doc all
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
gmake[1]: Nothing to be done for all'.
gmake[1]: Leaving directory /usr/local/src/postgresql-7.1.3/doc'
[...]</PRE
></DIV
><P
>The <SPAN
><I
CLASS="EMPHASIS"
>gmake check</I
></SPAN
> command will build a test installation of PostgreSQL within the source tree, and
display a list of all the checks it is running. As each test completes, the success or failure will be reported. Items
that fail the check will have a <TT
CLASS="LITERAL"
>failed</TT
> message printed, rather than the successful
<TT
CLASS="LITERAL"
>ok</TT
> message. If any checks fail, <SPAN
><I
CLASS="EMPHASIS"
>gmake check</I
></SPAN
> will display output
similar to that found in <A
href="x486#REGRESSIONCHECKOUTPUT"
>Example 2-9</A
>, though the number of tests failed may be higher on your
system than the number in the example.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="REGRESSIONCHECKOUTPUT"
></A
><P
><B
>Example 2-9. Regression check output</B
></P
><PRE
CLASS="SCREEN"
>=======================
1 of 76 tests failed.
=======================
The differences that caused some tests to fail can be viewed in the
file ./regression.diffs'. A copy of the test summary that you see
above is saved in the file ./regression.out'.</PRE
></DIV
><P
>The files referenced in <A
href="x486#REGRESSIONCHECKOUTPUT"
>Example 2-9</A
> (<SPAN
><I
CLASS="EMPHASIS"
>regression.diffs</I
></SPAN
> and
<SPAN
><I
CLASS="EMPHASIS"
>regression.out</I
></SPAN
>) are placed within the source tree at <SPAN
><I
CLASS="EMPHASIS"
>src/test/regress</I
></SPAN
>. If the
source tree is located in <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src</I
></SPAN
>, the full path to the directory files would be
<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src/postgresql-[version]/src/test/regress</I
></SPAN
>. </P
><P
>The regression tests will not always pick up every possible error. This can be due to inconsistencies in
locale settings (such as time zone support), or hardware-specific issues (such as floating-point results). As with any
application, be sure to perform your own requirements testing while developing with PostgreSQL.</P
><DIV
CLASS="WARNING"
><P
></P
><TABLE
CLASS="WARNING"
BORDER="1"
WIDTH="100%"
><TR
><TD
ALIGN="CENTER"
><B
>Warning</B
></TD
></TR
><TR
><TD
ALIGN="LEFT"
><P
>You cannot run the regression tests as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user. Be sure to run
<SPAN
><I
CLASS="EMPHASIS"
>gmake check</I
></SPAN
> as the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user.</P
></TD
></TR
></TABLE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN911"
>Step 6: Installing Compiled Programs and Libraries</A
></H2
><P
>After you have configured and compiled the PostgreSQL source code, it is time to install the compiled libraries,
binaries, and data files into a more appropriate home on the system. If you are upgrading from a previous version of
PostgreSQL, be sure to back up your database before beginning this step. Information on performing PostgreSQL database
backups can be found in <A
href="c16573"
>Chapter 9</A
>.</P
><P
>Installation of the compiled files is accomplished with the commands demonstrated in <A
href="x486#THEMAKEINSTALLCOMMAND"
>Example 2-10</A
>. When executed in the manner shown in <A
href="x486#THEMAKEINSTALLCOMMAND"
>Example 2-10</A
>, the
<SPAN
><I
CLASS="EMPHASIS"
>su</I
></SPAN
> command temporarily logs you in as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user to execute the required
commands. You must have the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> password to execute both of the commands shown in <A
href="x486#THEMAKEINSTALLCOMMAND"
>Example 2-10</A
>.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>If you specified a non-default installation directory in Step 3, use the directory you specified instead of
<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql</I
></SPAN
>.</P
></BLOCKQUOTE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="THEMAKEINSTALLCOMMAND"
></A
><P
><B
>Example 2-10. The gmake install command</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>su -c "gmake install"</B
></TT
>
Password:
gmake -C doc install
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/doc'
mkdir /usr/local/pgsql
mkdir /usr/local/pgsql/man
mkdir /usr/local/pgsql/doc
mkdir /usr/local/pgsql/doc/html
[...]
$ <TT
CLASS="USERINPUT"
><B
>su -c "chown -R postgres.postgres /usr/local/pgsql"</B
></TT
>
Password: </PRE
></DIV
><P
>The <SPAN
><I
CLASS="EMPHASIS"
>su -c "gmake install"</I
></SPAN
> command will install the freshly compiled source either into the
directory structure you chose in Step 3 with the <SPAN
><I
CLASS="EMPHASIS"
>--prefix</I
></SPAN
> configuration option, or, if this was left
unspecified, into the default directory of <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql</I
></SPAN
>. The use of the
<SPAN
><I
CLASS="EMPHASIS"
>su -c "chown -R postgres.postgres /usr/local/pgsql"</I
></SPAN
> command will ensure that the
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user owns the PostgreSQL installation directories. Using the <SPAN
><I
CLASS="EMPHASIS"
>su -c</I
></SPAN
>
command lets you save a step by only logging you in as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user for the duration of the command’s execution.</P
><P
>If you chose to configure the PostgreSQL source with the Perl or Python interface, but did not have root access, you
can still install the interfaces manually. Use the commands demonstrated in <A
href="x486#PERLANDPYTHONMODULEINSTALLATION"
>Example 2-11</A
> to install the Perl and Python modules manually. </P
><DIV
CLASS="EXAMPLE"
><A
NAME="PERLANDPYTHONMODULEINSTALLATION"
></A
><P
><B
>Example 2-11. Installing Perl and Python modules manually</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>su -c "gmake -C src/interfaces/perl5 install"</B
></TT
>
Password:
Password:
gmake: Entering directory /usr/local/src/postgresql-7.1.3/src/interfaces/perl5'
perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Pg
gmake -f Makefile clean
[...]
$ <TT
CLASS="USERINPUT"
><B
>su -c "gmake -C src/interfaces/python install"</B
></TT
>
Password:
gmake: Entering directory /usr/local/src/postgresql-7.1.3/src/interfaces/python'
sed -e 's,@libpq_srcdir@,../../../src/interfaces/libpq,g' \
-e 's,@libpq_builddir@,../../../src/interfaces/libpq,g' \
-e 's%@EXTRA_LIBS@% -lz -lcrypt -lresolv -lnsl -ldl -lm -lbsd -lreadline -ltermcap %g' \
-e 's%@INCLUDES@%-I../../../src/include%g' \
[...]</PRE
></DIV
><P
>You may also want to install the header files for PostgreSQL. This is important, because the default installation
will only install the header files for client application development. If you are going to be using some of PostgreSQL's
advanced functionality, such as user-defined functions or developing applications in C that use the
<SPAN
><I
CLASS="EMPHASIS"
>libpq</I
></SPAN
> library, you will need this functionality. To install the required header files, perform the
commands demonstrated in <A
href="x486#INSTALLALLHEADERS"
>Example 2-12</A
>. </P
><DIV
CLASS="EXAMPLE"
><A
NAME="INSTALLALLHEADERS"
></A
><P
><B
>Example 2-12. Installing all headers</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>su -c "gmake install-all-headers"</B
></TT
>
Password:
gmake -C src install-all-headers
gmake[1]: Entering directory /usr/local/src/postgresql-7.1.3/src'
gmake -C include install-all-headers
[...]</PRE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN956"
>Step 7: Setting Environment Variables</A
></H2
><P
>The use of the PostgreSQL environment variables is not required. However, they are helpful when performing tasks
within PostgreSQL, including starting and shutting down the <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> processes. The environment
variables that should be set are for the <SPAN
><I
CLASS="EMPHASIS"
>man</I
></SPAN
> pages and the <SPAN
><I
CLASS="EMPHASIS"
>bin</I
></SPAN
> directory. You can
do so by adding the following statements into the <SPAN
><I
CLASS="EMPHASIS"
>/etc/profile</I
></SPAN
> file. This should work for any
<SPAN
><I
CLASS="EMPHASIS"
>sh</I
></SPAN
>-based shell, including bash and ksh.</P
><PRE
CLASS="SCREEN"
>PATH=$PATH:/usr/local/pgsql/bin
MANPATH=$MANPATH:/usr/local/pgsql/man
export PATH MANPATH</PRE
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>You must login to the system <SPAN
><I
CLASS="EMPHASIS"
>after</I
></SPAN
> the <SPAN
><I
CLASS="EMPHASIS"
>/etc/profile</I
></SPAN
> file has had
environment variables added to it in order for your shell to utilize them.</P
></BLOCKQUOTE
></DIV
><P
>Depending on how your system handles shared libraries, you may need to inform the operating system of where your
PostgreSQL shared libraries are located. Systems such as Linux, FreeBSD, NetBSD, OpenBSD, Irix, HP/UX, and Solaris will
most likely not need to do this.</P
><P
>In a default installation, shared libraries will be located in <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql/lib</I
></SPAN
> (this may be
different, depending on whether you changed it with the <SPAN
><I
CLASS="EMPHASIS"
>--prefix</I
></SPAN
> configuration option). One of the
most common ways to accomplish this is to set the <TT
CLASS="LITERAL"
>LD_LIBRARY_PATH </TT
> environment variable to
<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql/lib</I
></SPAN
>. See <A
href="x486#SETTINGTHELIBPATHINBOURNE"
>Example 2-13</A
> for an example of doing this in
Bourne-style shells and <A
href="x486#SETTINGTHELIBPATHINCSH"
>Example 2-14</A
> for an example of doing this in <SPAN
><I
CLASS="EMPHASIS"
>csh</I
></SPAN
>
and <SPAN
><I
CLASS="EMPHASIS"
>tcsh</I
></SPAN
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="SETTINGTHELIBPATHINBOURNE"
></A
><P
><B
>Example 2-13. Setting LD_LIBRARY_PATH in a bash shell</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>LD_LIBRARY_PATH=/usr/local/pgsql/lib</B
></TT
>
$ <TT
CLASS="USERINPUT"
><B
>export LD_LIBRARY_PATH</B
></TT
></PRE
></DIV
><DIV
CLASS="EXAMPLE"
><A
NAME="SETTINGTHELIBPATHINCSH"
></A
><P
><B
>Example 2-14. Setting LD_LIBRARY_PATH in csh and tcsh</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>setenv LD_LIBRARY_PATH /usr/local/pgsql/lib</B
></TT
></PRE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN996"
>Step 8: Initializing and Starting PostgreSQL</A
></H2
><P
>If you are logged in as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user, instead of using the <SPAN
><I
CLASS="EMPHASIS"
>su -c</I
></SPAN
> command
in the previous steps, you will now need to login as the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user you added in step 1. Once you
are logged in as the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user, issue the command shown in <A
href="x486#INITIALIZINGTHEDATABASE"
>Example 2-15</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="INITIALIZINGTHEDATABASE"
></A
><P
><B
>Example 2-15. Initializing the database</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</B
></TT
></PRE
></DIV
><P
>The <SPAN
><I
CLASS="EMPHASIS"
>-D</I
></SPAN
> option in the previous command is the location where the data will be stored. This
location can also be set with the <TT
CLASS="LITERAL"
>PGDATA</TT
> environment variable. If you have set
<TT
CLASS="LITERAL"
>PGDATA</TT
>, the <SPAN
><I
CLASS="EMPHASIS"
>-D</I
></SPAN
> option is unnecessary. If you would like to use a
different directory to hold these data files, make sure the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user account can write to that
directory. When you execute <SPAN
><I
CLASS="EMPHASIS"
>initdb</I
></SPAN
> you will see something similar to what is shown in <A
href="x486#INITDBOUTPUT"
>Example 2-16</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="INITDBOUTPUT"
></A
><P
><B
>Example 2-16. Output from initdb</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>/usr/local/pgsql/bin/initdb -D /usr/local/pgsql/data</B
></TT
>
This database system will be initialized with username "postgres."
This user will own all the data files and must also own the server process.
Creating directory /usr/local/pgsql/data
Creating directory /usr/local/pgsql/data/base
Creating directory /usr/local/pgsql/data/global
Creating directory /usr/local/pgsql/data/pg_xlog
Creating template1 database in /usr/local/pgsql/data/base/1
DEBUG: database system was shut down at 2001-08-24 16:36:35 PDT
DEBUG: CheckPoint record at (0, 8)
DEBUG: Redo record at (0, 8); Undo record at (0, 8); Shutdown TRUE
DEBUG: NextTransactionId: 514; NextOid: 16384
DEBUG: database system is in production state
Creating global relations in /usr/local/pgsql/data/global
DEBUG: database system was shut down at 2001-08-24 16:36:38 PDT
DEBUG: CheckPoint record at (0, 108)
DEBUG: Redo record at (0, 108); Undo record at (0, 0); Shutdown TRUE
DEBUG: NextTransactionId: 514; NextOid: 17199
DEBUG: database system is in production state
Initializing pg_shadow.
Enabling unlimited row width for system tables.
Creating system views.
Loading pg_description.
Setting lastsysoid.
Vacuuming database.
Copying template1 to template0.
Success. You can now start the database server using:
/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data
or
/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l logfile start</PRE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>You can indicate that PostgreSQL should use a different data directory by specifying the directory location with
the <SPAN
><I
CLASS="EMPHASIS"
>-D</I
></SPAN
> option. This path must be initialized through <SPAN
><I
CLASS="EMPHASIS"
>initdb</I
></SPAN
>.</P
></BLOCKQUOTE
></DIV
><P
>When the <SPAN
><I
CLASS="EMPHASIS"
>initdb</I
></SPAN
> command has completed, it will provide you with information on starting the
PostgreSQL server. The first command displayed will start <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> in the foreground. After
entering the command as it is shown in <A
href="x486#POSTMASTERFOREGROUND"
>Example 2-17</A
>, the prompt will be inaccessible until
you press CTRL-C on the keyboard to shut down the <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> process.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="POSTMASTERFOREGROUND"
></A
><P
><B
>Example 2-17. Running postmaster in the foreground</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>/usr/local/pgsql/bin/postmaster -D /usr/local/pgsql/data</B
></TT
>
DEBUG: database system was shut down at 2001-10-12 23:11:00 PST
DEBUG: CheckPoint record at (0, 1522064)
DEBUG: Redo record at (0, 1522064); Undo record at (0, 0); Shutdown TRUE
DEBUG: NextTransactionId: 615; NextOid: 18720
DEBUG: database system is in production state</PRE
></DIV
><P
>Starting PostgreSQL in the foreground is not normally required. We suggest the use of the second command displayed.
The second command will start <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> in the background. It uses <SPAN
><I
CLASS="EMPHASIS"
>pg_ctl</I
></SPAN
> to
start the postmaster service, as shown in <A
href="x486#POSTMASTERBACKGROUND"
>Example 2-18</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="POSTMASTERBACKGROUND"
></A
><P
><B
>Example 2-18. Running postmaster in the background</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>/usr/local/pgsql/bin/pg_ctl -D /usr/local/pgsql/data -l /tmp/pgsql.log start</B
></TT
>
postmaster successfully started </PRE
></DIV
><P
>The major difference between the first command and the second command is that the second runs
<SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> in the background, as well as redirects any debugging information to
<SPAN
><I
CLASS="EMPHASIS"
>/tmp/pgsql.log</I
></SPAN
>. For normal operation, it is generally better to run <SPAN
><I
CLASS="EMPHASIS"
>postmaster</I
></SPAN
> in
the background, with logging enabled.</P
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>The <SPAN
><I
CLASS="EMPHASIS"
>pg_ctl</I
></SPAN
> application can be used to start and stop the PostgreSQL server. See
<A
href="c16573"
>Chapter 9</A
> for more on this command.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="CONFIGURINGSYSVSCRIPT"
>Step 9: Configuring the PostgreSQL SysV Script</A
></H2
><P
>The SysV script will allow the graceful control of the PostgreSQL database through the use of the SysV runlevel
system. The SysV script can be used for starting, stopping, and status-checking of PostgreSQL. It is known to work with
most Red Hat based versions of Linux, including Mandrake; however, it should work with other SysV systems (e.g., UnixWare,
Solaris, etc.) with little modification. The script is named <SPAN
><I
CLASS="EMPHASIS"
>linux</I
></SPAN
>. To use it, you will first need to
copy the <SPAN
><I
CLASS="EMPHASIS"
>linux</I
></SPAN
> script to your <SPAN
><I
CLASS="EMPHASIS"
>init.d</I
></SPAN
> directory. You may require root access to do
this.</P
><P
>First, change to the directory where you unpacked the PostgreSQL source. In our case, the path to that directory is
<SPAN
><I
CLASS="EMPHASIS"
>/usr/local/src/postgresql-7.1.3/</I
></SPAN
>. Then, issue a <SPAN
><I
CLASS="EMPHASIS"
>cp</I
></SPAN
> command to copy the script
from <SPAN
><I
CLASS="EMPHASIS"
>contrib/start-scripts</I
></SPAN
> into the <SPAN
><I
CLASS="EMPHASIS"
>init.d</I
></SPAN
> directory. <A
href="x486#COPYINGTHELINUXSCRIPT"
>Example 2-19</A
> demonstrates how to do this on a Red Hat Linux system.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="COPYINGTHELINUXSCRIPT"
></A
><P
><B
>Example 2-19. Copying the linux script</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>cd /usr/local/src/postgresql-7.1.3/</B
></TT
>
$ <TT
CLASS="USERINPUT"
><B
>su -c "cp contrib/start-scripts/linux /etc/rc.d/init.d/postgresql"</B
></TT
></PRE
></DIV
><P
><A
href="x486#COPYINGTHELINUXSCRIPT"
>Example 2-19</A
> arbitrarily re-names the new copy to <SPAN
><I
CLASS="EMPHASIS"
>postgresql</I
></SPAN
>; you may
call it whatever you prefer, though it is typically named either <SPAN
><I
CLASS="EMPHASIS"
>postgresql</I
></SPAN
>, or
<SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
>.</P
><P
>You will need to make the script file <SPAN
><I
CLASS="EMPHASIS"
>executable</I
></SPAN
> after copying it. To do so, use the command
shown in <A
href="x486#MAKINGTHELINUXSCRIPTEXECUTABLE"
>Example 2-20</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="MAKINGTHELINUXSCRIPTEXECUTABLE"
></A
><P
><B
>Example 2-20. Making the linux script executable</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>su -c "chmod a+x /etc/rc.d/init.d/postgresql"</B
></TT
></PRE
></DIV
><P
>There are no additional requirements to use the SysV script with Red Hat, if you do not intend on using it to start
PostgreSQL automatically (i.e., if you wish to use the script manually). However, if you do wish for the script to startup
PostgreSQL automatically when the machine boots up (or changes runlevels), you will need to have the
<SPAN
><I
CLASS="EMPHASIS"
>chkconfig</I
></SPAN
> program installed. If <SPAN
><I
CLASS="EMPHASIS"
>chkconfig</I
></SPAN
> is installed, you will also need to add
the following two lines, including the hash (<TT
CLASS="LITERAL"
>#</TT
>) symbol, at the beginning of the
<SPAN
><I
CLASS="EMPHASIS"
>/etc/rc.d/init.d/postgresql</I
></SPAN
> file:</P
><PRE
CLASS="SCREEN"
># chkconfig: 345 85 15
# description: PostgreSQL RDBMS</PRE
><P
>These example numbers should work on your system; however, it is good to know what role they perform. The first group
of numbers (<TT
CLASS="LITERAL"
>345</TT
>) represent which runlevels PostgreSQL should be started at. The example
shown would start PostgreSQL at runlevels 3, 4, and 5. The second group of numbers (<TT
CLASS="LITERAL"
>85</TT
>)
represent the order in which PostgreSQL should be started within that runlevel, relative to other programs. You should
probably keep the second number high, to indicate that it should be started later in the runlevel. The third number
(<TT
CLASS="LITERAL"
>15</TT
>) represents the order in which PostgreSQL should be shutdown. It is a good idea to
keep this number low, representing a shutdown order that is inverse from the startup order. As previously mentioned, the
script should work on your system with the numbers provided, but you can change them if it is necessary.</P
><P
>Once these two lines have been added to the script, you can use the commands shown in <A
href="x486#SYSVSTYLEPOSTGRESQLSTARTUP"
>Example 2-21</A
> on Red Hat and Mandrake Linux distributions to start the PostgreSQL database. Be sure
to execute these as the <SPAN
><I
CLASS="EMPHASIS"
>root</I
></SPAN
> user.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="SYSVSTYLEPOSTGRESQLSTARTUP"
></A
><P
><B
>Example 2-21. Starting PostgreSQL with the SysV script</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>service postgresql start</B
></TT
>
Starting PostgreSQL: ok
$ <TT
CLASS="USERINPUT"
><B
>service postgresql stop</B
></TT
>
Stopping PostgreSQL: ok</PRE
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>The SysV script logs redirects all PostgreSQL debugging output to <SPAN
><I
CLASS="EMPHASIS"
>/usr/local/pgsql/data/serverlog</I
></SPAN
>, by default.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="AEN1116"
>Step 10: Creating a Database</A
></H2
><P
>Now that the PostgreSQL database system is running, you have the option of using the default database,
<TT
CLASS="LITERAL"
>template1</TT
>. If you create a new database, and you would like all of your consecutive databases to have
the same system-wide options, then you should first configure the <TT
CLASS="LITERAL"
>template1</TT
> database to have those
options enabled. For instance, if you plan to use the PL/pgSQL language to program, then you should install the PL/pgSQL
language into <TT
CLASS="LITERAL"
>template1</TT
> before using <SPAN
><I
CLASS="EMPHASIS"
>createdb</I
></SPAN
>. Then when you use the
<SPAN
><I
CLASS="EMPHASIS"
>createdb</I
></SPAN
> command, the database created will inherit <TT
CLASS="LITERAL"
>template1</TT
>’s objects, and
thus, inherit the PL/pgSQL language. For more information on installing the PL/pgSQL language into a database, refer to
<A
href="c19610"
>Chapter 11</A
>.</P
><P
>The next step will be to create a new database. This will be a simple test database. We do not recommend using the
default <TT
CLASS="LITERAL"
>template1</TT
> database for testing purposes. As you have not created any users with
database-creation rights, you will want to make sure that you are logged in as the <SPAN
><I
CLASS="EMPHASIS"
>postgres</I
></SPAN
> user when
adding a new database. You can also create users that are allowed to add databases, which is discussed later in <A
href="c18591"
>Chapter 10</A
>. To create a new database named <TT
CLASS="LITERAL"
>testdb</TT
>, enter the command shown in <A
href="x486#CREATINGADATABASEWITHCREATDB"
>Example 2-22</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="CREATINGADATABASEWITHCREATDB"
></A
><P
><B
>Example 2-22. Creating a database</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>createdb testdb</B
></TT
>
CREATE DATABASE </PRE
></DIV
><P
>You should receive a message that says <TT
CLASS="LITERAL"
>CREATE DATABASE</TT
>, indicating that creation of
the database was successful. You can now use PostgreSQL's command line interface, <SPAN
><I
CLASS="EMPHASIS"
>psql</I
></SPAN
>, to access the
newly created database. To do so, enter the command shown in <A
href="x486#ACCESSINGADATABASEWITHPSQL"
>Example 2-23</A
>.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="ACCESSINGADATABASEWITHPSQL"
></A
><P
><B
>Example 2-23. Accessing a database with psql</B
></P
><PRE
CLASS="SCREEN"
>$ <TT
CLASS="USERINPUT"
><B
>psql testdb</B
></TT
></PRE
></DIV
><P
>You can now start entering SQL commands (e.g., such as <TT
CLASS="LITERAL"
>SELECT</TT
>) at the
<SPAN
><I
CLASS="EMPHASIS"
>psql</I
></SPAN
> prompt. If you are unfamiliar with <SPAN
><I
CLASS="EMPHASIS"
>psql</I
></SPAN
>, please see <A
href="c4890"
>Chapter 4</A
> for an introduction.</P
><P
>To verify that the database is working correctly, you can issue the command shown in <A
href="x486#QUERYINGASYSTEMTABLE"
>Example 2-24</A
>, which should give you a listing of the languages installed in the database.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="QUERYINGASYSTEMTABLE"
></A
><P
><B
>Example 2-24. Querying a system table</B
></P
><PRE
CLASS="SCREEN"
>testdb=# <TT
CLASS="USERINPUT"
><B
>SELECT * FROM pg_language;</B
></TT
>
lanname | lanispl | lanpltrusted | lanplcallfoid | lancompiler
----------+---------+--------------+---------------+-------------
internal | f | f | 0 | n/a
C | f | f | 0 | /bin/cc
sql | f | f | 0 | postgres
(3 rows)</PRE
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
href="c360"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
href="book1"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
href="p1162"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Installing PostgreSQL</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
href="c360"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Using PostgreSQL</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
</div>
<br />
<div id="thefineprint">
<a href="http://www.commandprompt.com/products/mammothpostgresql/"><img src="../images/powered_by_mammoth.gif" alt="Powered by Mammoth PostgreSQL" title="Powered by Mammoth PostgreSQL" border="0" /></a>
<br />
Copyright © 2000-2007 Command Prompt, Inc. All Rights Reserved. All trademarks property of their respective owners.
</div>
</div>
</div>
</body>
</html>