.\" This is -*-nroff-*- with -me macros .\" .\" POSTGRES Data Base Management System .\" .\" Copyright (c) 1988 Regents of the University of California .\" .\" Permission to use, copy, modify, and distribute this software and its .\" documentation for educational, research, and non-profit purposes and .\" without fee is hereby granted, provided that the above copyright .\" notice appear in all copies and that both that copyright notice and .\" this permission notice appear in supporting documentation, and that .\" the name of the University of California not be used in advertising .\" or publicity pertaining to distribution of the software without .\" specific, written prior permission. Permission to incorporate this .\" software into commercial products can be obtained from the Campus .\" Software Office, 295 Evans Hall, University of California, Berkeley, .\" Ca., 94720. The University of California makes no representations .\" about the suitability of this software for any purpose. It is .\" provided "as is" without express or implied warranty. .\" .\" ---------------------------------------------------------------- .\" POSTGRES version 4.2 setup instructions .\" .\" ---------------------------------------------------------------- .de RV .ie "\\$2"" \ \{\ . ds VT " . ds VN " . ds VD \*(td .\} .el \ \{\ . ds VT \\$7 . ds VD \\$4 . ds VN \\$3 .\} .. .hx .fo ''%'' .ce 99 .ds PG "\\s-2POSTGRES\\s+2 .ds PV 4.2 .ps 18 .b POSTGRES INSTALLATION INSTRUCTIONS .r .ps 14 .sp 0.25v Release \*(PV .sp 0.25v .ce 0 .sp .\" ---------------- .\" Document Overview .\" ---------------- .sh 0 "Document Overview" .(l Introduction Site Requirements Hardware and Software Distribution Tape Expertise Configuration Programming Environment Disk Requirements Kernel Installing \*(PG Preparation Finding a Good Place for \*(PG Creating the \*(PG Directory Creating the \*(PG User Loading \*(PG Loading \*(PG From Tape Loading \*(PG From a Tar File Kernel Configuration Kernel Reconfiguration for SPARCs Kernel Reconfiguration for DECs (Ultrix only) Compiler Configuration Setup for Solaris 2 Setup for HP-UX Compiling and Installing \*(PG Customization Installing \*(lqbsdinst\*(rq (HP-UX only) Installing \*(lqsolcc\*(rq (Solaris only) Bootstrapping \*(lqbmake\*(rq Building and installing \*(lqlibdl\*(rq (Ultrix only) Installing \*(lqmkldexport\*(rq (AIX only) Compile and Install Creating the Initial Database Testing Running \*(PG The \*(PG Postmaster The \*(PG Terminal Monitor The \*(PG Backend \*(PG Support Programs Optional Installation Installing LIBPQ, the \*(PG Frontend Library \*(PG Header Files Wisconsin Benchmark Database Minimal Installation Documentation Miscellaneous Bug Reports Consulting \*(PG Mailing List .)l .bp .\" ---------------- .\" Introduction .\" ---------------- .sh 1 "Introduction" .lp This document gives installation instructions for the \*(PG database system under development at the University of California, Berkeley. \*(PG is distributed in source code format and is the property of the Regents of the University of California. However, the University will grant unlimited commercialization rights for any derived work on the condition that an educational license to the derived work is obtained. For further information, consult the Berkeley Campus Software Office, 295 Evans Hall, University of California, Berkeley, CA 94720. .lp The University and the \*(PG development group provide no warranty as to the fitness of the code for any purpose whatsoever, and cannot guarantee assistance in fixing problems. This is \fIunsupported\fP software. .\" ---------------- .\" Site Requirements .\" ---------------- .sh 1 "Site Requirements" .lp .sh 2 "Hardware and Software" .lp \*(PG currently has been tested by the \*(PG development team on the following systems: .bu Digital Equipment DECstation 3000 series (Alpha AXP architecture) machines running DEC OSF/1 1.3 and 2.0. .bu Digital Equipment DECstation 3100 and 5000 series (MIPS architecture) machines running Ultrix 4.2A and 4.3A. .bu Hewlett-Packard H-P 9000 Series 700 and 800 (PA-RISC architecture) machines running HP-UX 9.00, 9.01 and 9.03. .bu International Business Machines RS/6000 (POWER architecture) machines running AIX 3.2.5. .bu Sun Microsystems (SPARC architecture) machines running SunOS 4.1.3, (Solaris 1.0.1), SunOS 4.1.3_U1 and Solaris 2.3. .lp In order to use \*(PG, your machine should have at least 8 megabytes of memory and you will require at least 45 megabytes of disk space to hold source, binaries, and user databases. If you choose to compile \*(PG for source-level debugging, you will need roughly twice as much disk space. See the section on compilation for details. .sh 2 "Distribution Tape" .lp These instructions assume you have a \*(PG Version \*(PV distribution tape (in either SCSI cartridge or DEC TK50 cartridge format) or a \*(PG tar file. This release is a source distribution only. The source code is available in tar format over the Internet via anonymous ftp from the site \f(CWs2k-ftp.CS.Berkeley.EDU\fP. Look in the directory \f(CWpub/postgres/postgres-v4r2\fP. The compressed tar file containing the complete source distribution is named \f(CWpostgres-v4r2.tar.Z\fP. .sh 2 "Expertise" .lp Once a site is properly configured and \*(PG is installed, very little UNIX expertise is required to maintain things. However, initially setting things up for your site to run \*(PG may be difficult and we advise that the person installing \*(PG be familiar with system administration procedures. Also note that various steps require superuser privilege on the system, so we recommend that your site's system administrator read this document also. .sh 2 "Configuration" .lp This section briefly describes the configuration you need to run \*(PG. Read this to familiarize yourself with the procedure. Detailed instructions for making appropriate modifications to your system are given later in this document. .sh 3 "Programming Environment" .lp Some compiler environments must be modified in certain ways. For example, under SunOS 4.x, \*(PG expects things to be configured for BSD by default. If the default on your site is to use the SunOS 4.x System V compiler and libraries then you may have to make some changes to this procedure before compiling \*(PG. Under other systems, you may have to apply patches to your compiler. We will describe such modifications later. .lp To compile this release from sources requires a new version of \f(CWmake\fP which comes from the latest BSD release. A bootstrapping version of the \f(CWmake\fP sources is included with this release and additional instructions are provided below. The new \f(CWmake\fP program is installed as \f(CWbmake\fP to avoid any conflict with your native \f(CWmake\fP. .sh 3 "Disk Requirements" .lp \*(PG requires 50 megabytes of disk space, preferably on a single partition, to compile and install from sources. (As with any program, it may require 2-3 times as much space if you compile the system with optimization turned off and compiler debugging support turned on.) .sh 3 "Kernel" .lp \*(PG makes use of the System V inter-process communication (shared memory and semaphore) operations provided by the operating system. Ultrix requires a properly configured kernel which is in general different than the factory-shipped generic kernel. See the section on kernel configuration for details. Also, the original release of Ultrix 4.3 has a kernel bug that causes the operating system to hang when running \*(PG. The bug is in the shared memory module in the kernel, and a patch is available from DEC which fixes the bug. Contact your DEC representative for patch number CLD-CXO09447. (This patch has been included in Ultrix 4.3a.) .\" ---------------- .\" Installation .\" ---------------- .sh 1 "Installing \*(PG" .lp To install the system you must load the sources into your filesystem and build the system from scratch. To run the compiled programs your kernel may need to be configured to support the shared memory and semaphore operations required by the code. Assuming you have run \*(PG in the past, your machine may already be properly configured. .\" ---------------- .\" Preparation .\" ---------------- .sh 2 "Step 1 \- Preparation" .lp Some of the tasks involved in this step normally fall in the domain of the site's system administrator and may require superuser privilege. If possible, we advise you to have your system administrator perform these steps. .sh 3 "Find a good place for \*(PG" .lp First you should locate a disk partition with at least 50 megabytes of free space available for \*(PG. For example: .sp .(l # \fBdf\fR Filesystem kbytes used avail capacity Mounted on /dev/xy0a 8421 6703 875 88% / /dev/xy0f 10829 6743 3003 69% /pub.MC68020 /dev/xy2h 110811 81181 18548 81% /usr3 /dev/xy2g 221279 167405 31746 84% /b /dev/xy1g 221279 138365 60786 69% /usr/local /dev/xy1a 8179 944 6417 13% /tmp /dev/xy0h 119999 101623 6376 94% /usr.MC68020 /dev/xy0g 156033 135499 4930 96% /usr2 /dev/rf0d 539421 465026 20452 96% /a .i /usr/local looks like a good place (it has 60 megs free) so we decide to create the \*(PG directory there... .r .)l .sh 3 "Creating the \*(PG directory" .lp Once you have decided, create the directory to hold the release if it doesn't already exist. Then \fBcd\fR to this directory and type \fBpwd\fR. This is the full path of the directory you will install \*(PG in. For example: .(l # \fBcd /usr/local\fR # \fBmkdir postgres\fR # \fBcd postgres\fR # \fBpwd\fR /usr/local/postgres # .)l .sh 2 "Creating the \*(PG user" .lp Finally, we need to create a user called \*(lqpostgres\*(rq whose shell is \f(CW/bin/csh\fP. Though not necessary, it is convenient to make the home directory of the \*(PG user the pathname where we install the system. This can be done using the \*(lqadduser\*(rq procedures particular to your platform and site. See your system administration manual for details. .lp The reason we make a \*(lqpostgres\*(rq login is so that when we install the system and create the database directory, everything is owned by this \*(lqpostgres\*(rq user. Then, we start the postmaster when logged in as this \*(lqpostgres\*(rq user, and all the backends are also started by the user \*(lqpostgres\*(rq and are able to access the databases. You can make this work without creating a \*(lqpostgres\*(rq login but this is highly discouraged \(em all \*(PG processes run with this user id, and making yourself the \*(PG user essentially grants all of your database users the ability to become .i you without a password. .lp Note that the restriction about having a \*(lqpostgres\*(rq login with UID 6 was removed in \*(PG Version 4.0.1. .\" ---------------- .\" Loading .\" ---------------- .sh 2 "Step 2 \- Loading \*(PG" .lp Now you are ready to load the \*(PG files onto your system. To do this, you will need either a distribution tape or a \*(PG tar file. If you are loading \*(PG from a tape, follow these instructions; if you are loading from a tar file obtained via FTP, skip to the section \*(lqLoading \*(PG from a Tar File.\*(rq .sh 3 "Loading \*(PG from a Tape" .lp Login as \*(lqpostgres\*(rq and change directories to the postgres directory that was created. .lp Run \f(CWtar\fP with the following options .(l % \fBtar xvfp\fP \fI\fP .)l .sp where \fI\fP is the name for your tape device, i.e., \f(CW/dev/rmt0\fP, \f(CW/dev/rst8\fP, etc. .lp The file \f(CWpostgres-v4r2.tar.Z\fP will appear in your \*(PG home directory. You may need to re-wind your tape to get it out of your tape drive - see your system administrator for instructions. .lp Proceed to the next section \*(lqLoading \*(PG from a Tar File.\*(rq .lp .sh 3 "Loading \*(PG from a Tar File" .lp If you are not logged in as \f(CWpostgres\fP already, do so now. .lp Uncompress the tar file. .(l % \fBuncompress postgres-v4r2.tar.Z\fP .)l .lp A larger file should now be in the \*(PG home directory, and the \*(lq.Z\*(rq ending should be gone, so it is now named \f(CWpostgres-v4r2.tar\fP. .lp Extract \*(PG from the tar file using the following command: .(l % \fBtar xvfp postgres-v4r2.tar\fP .)l .lp Lots of file names and such should appear on the screen. This step may take several minutes. .lp Now do an \f(CWls\fP: .(l % \fBls\fP .)l .lp The output should look something like: .(l .ft CW COPYRIGHT README doc local src INITIAL_SETUP bin include man Makefile data lib obj .ft .)l .lp At this point you have loaded the \*(PG files. Remove the tar file to get back the space. .(l % \fBrm postgres-v4r2.tar\fP .)l .sp .\" ---------------- .\" Configuration .\" ---------------- .sh 2 "Step 3 \- Kernel Configuration" .lp This step requires familiarity with configuring a UNIX kernel. If you are unfamiliar with this procedure, we advise you to read the section on configuring a kernel in the system administration manual carefully. This task requires superuser privilege and should probably not be done without the assistance of your system administrator. We assume that whoever undergoes this procedure has an understanding of the process and procedures involved. .lp \*(PG uses shared memory segments which must be compiled into the kernel of the host which will act as the \*(PG server. If you try to run a \*(PG backend process on a machine without enough shared memory, the backend will abort with an error message. .lp This is by far the most complicated part of the installation so \fBthese steps should be performed by someone with system administration experience\fP. Again, we advise you to consult the system administration section of your manual before doing this step. .lp For a brief discussion of shared memory, you may want to consult the manual pages for \f(CWshmget(3)\fP, \f(CWshmop(3)\fP, \f(CWshmctl(3)\fP, etc. Now proceed to the appropriate section for your machine. .lp .sh 3 "Kernel reconfiguration for SPARCs" .lp We previously suggested that you reconfigure your kernel under SunOS. However, the parameters in the generic kernel of current releases of SunOS ought to suffice. (We never reconfigure our kernels and have not noticed any problems while running several \f(CWpostmaster\fPs at once.) .sh 3 "Kernel reconfiguration for DECs (Ultrix only)" .lp In order to reconfigure your DECstation 3100 or 5000 Ultrix kernel, you will have to become the superuser and add some lines to \f(CW/usr/sys/conf/KERNEL\fP (your kernel config file). .lp Remember that Ultrix 4.3 has a kernel bug that causes the operating system to hang when running \*(PG. You should apply the DEC-supplied patch at this point if you have not already. .lp The following lines should be added to \f(CW/usr/sys/conf/KERNEL\fP: .sp .(l .ft CW smmax 256 smseg 12 smbrk 1024 .ft .)l .lp After adding these lines, run \f(CWconfig\fP over the configuration file, install the new kernel (saving a copy of the old kernel first!) and reboot. .sp .\" ---------------- .\" .\" ---------------- .sh 2 "Step 4 \- Compiler Configuration" .lp .sh 3 "Setup for Solaris 2" .lp \*(PG should build without problems using the SunPro SPARCompiler (we used version 3.0). If you do not have the SunPro compiler, you must use a version of the GNU C compiler that fully implements the \f(CW-munaligned-doubles\fP option. You may FTP a suitable set of binaries from \f(CWs2k-ftp.CS.Berkeley.EDU\fP in the directory \f(CWpub/postgres/useful\fP, or you can rebuild your own copy of the GNU C compiler with the required change. The current version as of this writing is 2.5.8, which must be modified with the following one-line patch: .(l M .ft CW --- 1,19 ---- + *** config/sparc/sparc.c Thu Apr 7 09:30:30 1994 + --- config/sparc/sparc.c.orig Thu Apr 7 09:31:35 1994 + *************** + *** 1067,1073 **** + is true, in which case we can only assume that an access is aligned if + it is to an aggregate, it is to a constant address, or the address + involves a LO_SUM. */ + ! else if (! TARGET_UNALIGNED_DOUBLES /* || MEM_IN_STRUCT_P (mem) */ + || CONSTANT_P (addr) || GET_CODE (addr) == LO_SUM) + return 1; + + --- 1067,1073 ---- + is true, in which case we can only assume that an access is aligned if + it is to an aggregate, it is to a constant address, or the address + involves a LO_SUM. */ + ! else if (! TARGET_UNALIGNED_DOUBLES || MEM_IN_STRUCT_P (mem) + || CONSTANT_P (addr) || GET_CODE (addr) == LO_SUM) + return 1; + .ft P .)l We have been told that a later version of the GNU C compiler may incorporate this change (this patch has been sent to both Cygnus Support and the FSF). .sh 3 "Setup for HP-UX" .lp You cannot build \*(PG without the unbundled C compiler. Neither the GNU C compiler nor the (crippled) C compiler that comes with stock HP-UX will work, as both are missing critical compiler options. .lp If you are running HP-UX 9.03, you .b must apply patch PHSS_4307 (or a cumulative patch that supercedes this patch) to your system, as the C preprocessor for HP-UX 9.03 has severe problems. We cannot provide you with this patch; you must obtain it from your H-P support representative. Note that \*(PG should build without problems on 9.01, so you can always build the binaries on a 9.01 system and use them on a 9.03 system. .sp .\" ---------------- .\" Compiling and installing postgres .\" ---------------- .sh 2 "Step 5 \- Compiling and Installing \*(PG" .lp The sources for \*(PG are all under the directory \f(CWsrc/\fP. .sh 3 "Build Step 1: Customization" .lp \f(CWCd\fP into the \f(CWsrc/\fP directory and edit the file \f(CWMakefile.global\fP. You may change the various configuration options here, such as where the \*(PG executable files are installed and where it looks for the database directory. The configuration switches are fairly self-explanatory, but we will go over some of the more commonly-changed options. .lp The PORTNAME option \fBmust\fP be set correctly. By default the PORTNAME is \f(CWultrix4\fP, but .(l aix alpha hpux sparc sparc_solaris ultrix4 .)l are all valid choices. .lp The top-level directory where \*(PG binaries, documentation, header files, libraries, and databases are installed is controlled by the variable POSTGRESDIR. This variable defaults to \f(CW/usr/local/postgres\fP. Whether you change this variable or not, make sure that the directory to which POSTGRESDIR refers exists before proceeding. .lp If you do not want \f(CWbmake\fP installed into \f(CW/usr/local/bin\fP and \f(CW/usr/local/lib\fP, change the values of TOOLSBINDIR and TOOLSLIBDIR and make sure that these directories exist before proceeding. .lp Standards notwithstanding, every system has an \f(CWinstall\fP program with slightly different options and behavior. Our Makefiles assume that \f(CWinstall\fP accepts BSD (as opposed to System V) options. Where possible, we set the INSTALL variable to ensure that the BSD program is called. However, on HP-UX you will have to find a BSD-compatible installation program and set INSTALL to the location of this program. \f(CWbsdinst\fP, which comes with the MIT X Window System distribution (in \f(CWmit/util/scripts\fP), is widely available (we even include it in the \f(CWsrc/tools\fP directory) and works acceptably. The GNU \f(CWinstall\fP program does not. .lp If you are not installing \*(PG using superuser privileges, or you are installing \*(PG without creating a \*(lqpostgres\*(rq user, you may have to set the values of several variables that control the system ownership. For example, \*(lqjaneuser\*(rq who is a member of group \*(lqusers\*(rq may have to set: .(l .ft CW BINGRP= users BINOWN= janeuser LIBGRP= users LIBOWN= janeuser MANGRP= users MANOWN= janeuser .ft .)l to prevent the \f(CWinstall\fP program from complaining. .lp If you absolutely insist on having a \*(PG user other than .q postgres , set the variable POSTGRESLOGIN to the name of that user. .sh 3 "Installing \*(lqbsdinst\*(rq (HP-UX only)" .lp We told you about this above, but in case you missed it, you will have to install \f(CWbsdinst\fP from \f(CWsrc/tools/bsdinst\fP if you don't have it installed already. You can just copy the shell script \f(CWbsdinst.sh\fP into some convenient place (probably \f(CW/usr/local/bin\fP) as \f(CWbsdinst\fP. .sh 3 "Installing \*(lqsolcc\*(rq (Solaris only)" .lp If you are using the GNU C compiler under Solaris 2.3, you must now install the small wrapper in \f(CWsrc/tools/solcc\fP into some convenient place (probably \f(CW/usr/local/bin\fP). You will have to edit this wrapper, changing the line .(l GCCBINDIR=/opt/gnu/bin .)l to point to the directory where you have your (modified) version of \f(CWgcc\fP installed. .lp If you are using the SunPro SPARCompiler, you do not have to install \f(CWsolcc\fP. .sh 3 "Build Step 2: Bootstrapping \*(lqbmake\*(rq" .lp Because the \f(CWbmake\fP program is normally installed into \f(CW/usr/local/{bin,lib}\fP and that directory is usually only writable by root, it will be necessary to temporarily become root to install \f(CWbmake\fP. If you don't have root privilege you can change where \f(CWbmake\fP is installed by changing the value of the TOOLSBINDIR and TOOLSLIBDIR options in \f(CWsrc/Makefile.global\fP, otherwise you will need to \f(CWsu\fP(1) to root. Next make sure that the \f(CWmake\fP program in your PATH environment variable is the system-provided \f(CWmake\fP (usually \f(CW/bin/make\fP) and \fBNOT\fP GNU \f(CWmake\fP (many users have reported problems getting old versions of GNU \f(CWmake\fP to work). .lp \f(CWCd\fP into \f(CWsrc/tools/bmake\fP and type .(l % \fB./Bootstrap\fP \fIportname\fP .)l where \fIportname\fP is the value of PORTNAME (ultrix4, sparc, etc). If you are using the GNU C compiler under Solaris 2.3, type .(l % \fB./Bootstrap\fP \fIportname\fP \fBsolcc\fP .)l to specify the correct compiler. This script should compile and install the \f(CWbmake\fP program and its supporting files, including the \*(PG-related Makefile templates. If all went well you will now be able to use the new program by typing \f(CWbmake\fP, assuming you have \f(CW/usr/local/bin\fP in your shell path. You may have to type \f(CWrehash\fP if you run \f(CWcsh\fP. .sh 3 "Building and installing \*(lqlibdl\*(rq (Ultrix only)" .lp This version of \*(PG uses the \f(CWdlopen(3)\fP interface to implement dynamic function loading. Since there is no such vendor-supplied interface on the Ultrix platform you must build and install a version that we provide. .lp The same previous discussion about being root also holds true here. However, if you cannot become root to install this library, then you will have to change the backend Makefile to look for this library where you have decided to put it using the -L loader flag. .lp To compile and install the library simply \f(CWcd\fP into \f(CWsrc/tools/libdl\fP and type .(l % \fBbmake all install\fP .)l This will build and install the \f(CWlibdl.a\fP library into TOOLSLIBDIR (this is \f(CW/usr/local/lib\fP by default). If your linker/loader doesn't search here by default (it usually does), you may have to \f(CWranlib(1)\fP on it. .sh 3 "Installing \*(lqmkldexport\*(rq (AIX only)" .lp \f(CWCd\fP into \f(CWsrc/tools/mkldexport\fP and type .(l % \fBbmake all install\fP .)l .sh 3 "Build Step 3: Compile and Install" .lp \f(CWCd\fP back to the \f(CWsrc/\fP directory (i.e., \f(CWcd ../..\fP) and type: .(l % \fBbmake all install\fP .)l This builds and installs the entire system. The \f(CWMakefile\fPs contain directives for running all the underlying \f(CWMakefile\fPs in all the directories, so the whole thing should unfold and compile beautifully and install into the target directory. Should this not be the case, it would be a good idea to save the results of the compile in a file. If you run \f(CWcsh\fP, you could type .(l % \fBbmake all install >& mk.log\fP .)l and if you run \f(CWksh\fP or \f(CWsh\fP, type .(l % \fBbmake all install > mk.log 2>&1\fP .)l This will save the results in the file \f(CWmk.log\fP so you can inspect it later. This would be an ideal opportunity to get some doughnuts and coffee. .sp .sh 2 "Step 5 \- Creating the initial database" .lp \*(PG databases are stored in the directory \f(CW.../postgres/data\fP. After you have compiled \*(PG, you will need to create the initial database. If you haven't already put the path to the \*(PG executable programs in the shell path, do the following (assuming the \*(PG programs were loaded into \f(CW/usr/local/postgres/bin\fP). If you run \f(CWcsh\fP, you would put .(l .ft CW set path=(/usr/local/postgres/bin $path) .fT .)l in the \f(CW.login\fP for the \*(PG user. If you run \f(CWsh\fP or \f(CWksh\fP, put .(l .ft CW PATH=/usr/local/postgres/bin:$PATH export PATH .ft .)l in your \f(CW.profile\fP. Then log back in so the change takes effect. .lp Now you can create the initial database by running the following command: .(l % \fBinitdb\fP .)l If that completes successfully, congratulations. .lp Now, to make the system operational you must run the \f(CWpostmaster\fP. The section after \*(lqTesting\*(rq discusses this. .\" ---------------- .\" Testing .\" ---------------- .sh 2 "Step 6 \- Testing" .lp We suggest you run the regression tests to make sure the release was installed successfully. Also, you need to have the \f(CWpostmaster\fP running to run the test, so type the following: .(l % \fBTZ=GMT0\fP % \fBexport TZ\fP % \fBpostmaster -S\fP .)l if you use \f(CWsh\fP or \f(CWksh\fP. If you use \f(CWcsh\fP, type .(l % \fBsetenv TZ GMT0\fP % \fBpostmaster -S\fP .)l instead. The bit about .q TZ is just to make sure that your regression output will be comparable to ours; you don't have to do this every time you start the \f(CWpostmaster\fP. Next, create a new user using the \f(CWcreateuser\fP command (see the Reference Manual). \fBDo not\fP run the regression test script as user \*(lqpostgres\*(rq! .lp Change directories to \f(CWsrc/regress/regress\fP. .(l % \fBcd src/regress/regress\fP .)l Make sure that the \f(CWobj\fP subdirectory is writable by the .q postgres user, as some of the tests involve the .q postgres user copying data into that directory. (We ship it that way, but if you left the .q p flag off of your \f(CWtar\fP command, it will be set according to your umask.) Type the following command to run the test: .(l % \fBbmake clean all runtest\fP .)l .lp This will run a whole slew of regression tests and might take a long time to run. When it's done, the output of the test is in the file \f(CWobj/regress.out\fP. You can compare this to a sample run that we supply in the file \f(CWsample.regress.out\fP with the following command: .(l % \fBsh checkdiff\fP .)l It may take a little while to run as the regression results are quite large. There will be many differences corresponding to the timestamp lines and occasional lines where object id numbers (OIDs) are different. The \f(CWcheckdiff\fP program attempts to weed out these innocuous differences. If you see any differences not corresponding to timestamps, OIDs or very small differences between floating-point numbers, there may be a problem. Have your local \*(PG expert take a look at it. .sp .\" ---------------- .\" Running .\" ---------------- .sh 1 "Running \*(PG" .lp \*(PG is designed to be a multiuser system. In practice, \*(PG consists of three (or more) processes: .ip \0\0\0\(bu the postmaster, .ip \0\0\0\(bu a front-end program (often the terminal monitor), and .ip \0\0\0\(bu the backend server. .lp Users are expected to use the terminal monitor for direct access to the database. The terminal monitor sends commands to the \f(CWpostmaster\fP which forwards commands to a backend. .sh 2 "The \*(PG Postmaster" .lp The \f(CWpostmaster\fP is a process which manages communication between the a front-end program such as the terminal monitor and a \*(PG backend. Without a running \f(CWpostmaster\fP, the front-end program will not be able to connect to a backend. In general, the \f(CWpostmaster\fP must be running for you (or others) to run any of the normal \*(PG commands. Always start the \f(CWpostmaster\fP when logged in as the special \*(lqpostgres\*(rq user, otherwise the system will not be able to access the database files. To start it, type .(l % \fBpostmaster &\fP .)l .sp .sh 2 "The \*(PG Terminal Monitor" .lp The \*(PG terminal monitor is a front-end user interface to the \*(PG backend. .lp Lets assume \fIdatabase\fR is the name of the database you want to use. It is an error if \fIdatabase\fR does not exist, so to create the database, you would type .(l % \fBcreatedb\fP \fIdatabase\fP .)l Now we will run the monitor: .(l % \fBmonitor\fP \fIdatabase\fP .)l .(l .ft CW Welcome to the POSTGRES terminal monitor Go * .ft I The ``*'' is the terminal monitor prompt. We are now talking to the backend, so let's send a simple test query: list the names and user ids of the \*(PG users. We terminate the query with a \eg \*- the ``go'' command to the terminal monitor. .ft CW * \fBretrieve (u.usename, u.usesysid) from u in pg_user\eg\fP .ft CW Query sent to backend is "retrieve (u.usename, u.usesysid) from u in pg_user" ----------------------------- | usename | usesysid | ----------------------------- | postgres | 6 | ----------------------------- | mike | 799 | ----------------------------- | sp | 1511 | ----------------------------- | jhingran | 943 | ----------------------------- | cimarron | 2359 | ----------------------------- | goh | 1994 | ----------------------------- | ong | 2802 | ----------------------------- | hong | 2469 | ----------------------------- | mao | 1806 | ----------------------------- | marc | 2435 | ----------------------------- | margo | 2697 | ----------------------------- | sullivan | 1517 | ----------------------------- | kemnitz | 3491 | ----------------------------- | choi | 3898 | ----------------------------- | mer | 3665 | ----------------------------- Go .ft I Okay, this worked, too. Now we'll quit. .ft CW * \fB\eq\fP .ft CW % .ft R .)l .sh 2 "The \*(PG Backend" .lp The \*(PG backend is the process which does all the \*(lqreal\*(rq work. This process is started by the \f(CWpostmaster\fP when it receives a connection from a terminal monitor, so you should not normally need to start up the backend yourself. Should you wish to start the backend and talk to it directly (without a terminal monitor) you can do this by typing: .(l % \fBpostgres\fR \fIdatabase\fR .)l .lp where \fIdatabase\fR is the name of the database you wish to use. If you run a backend in this manner, you will be talking to the backend parser directly. We recommend using the terminal monitor; if you are using \*(PG as a multiuser system, running the backend can result in locking failures and corrupt databases, as the \f(CWpostmaster\fP handles shared resources such as semaphores and shared memory. In short: never do this if there is a \f(CWpostmaster\fP running. In addition, when using the terminal monitor, returned tuples are displayed more usefully and input is buffered better. The backend should only be used interactively during debugging. .sh 2 "\*(PG Support Programs" .lp Included in \*(PG are a handful of support programs. Most of these are used internally by the system but here is a list of them for your information. .(l initdb \- creates the initial template database cleardbdir \- totally destroys the data/ directory, allowing a new initdb createdb \- creates new \*(PG databases createuser \- add a new user to the \*(PG system destroydb \- destroys \*(PG databases destroyuser \- delete a user from the database system ipcclean \- frees up garbage shared memory from failed backends newbki \- adjust userid of "postgres" in the database pg_version \- make version numbers for createdb pg_id \- gets user id's - used by various commands pagedoc \- disk page doctor reindexdb \- rebuild system catalog indices after disaster shmemdoc \- shared memory buffer pool doctor vacuum \- database vacuum cleaner icopy \- inversion filesystem file management utility pcat \- inversion filesystem cat command pcd \- inversion filesystem cd command pls \- inversion filesystem ls command pmkdir \- inversion filesystem mkdir command pmv \- inversion filesystem mv command ppwd \- inversion filesystem pwd command prm \- inversion filesystem rm command prmdir \- inversion filesystem rmdir command .)l .sh 1 "Optional Installation" .sh 2 "Installing LIBPQ, the \*(PG frontend library" .lp The file \f(CW.../lib/libpq.a\fP is created when you install the system. This library contains various routines intended for use by frontend programs. You use this library if you want to execute \*(PG queries from a C program. If you plan on doing software development, you may wish to copy this file to \f(CW/usr/local/lib\fP or \f(CW/usr/lib\fP so that the C compiler can reference it with \f(CW-lpq\fP. If you do not, you will have to use the \f(CW-L\fP directive to the \f(CWcc\fP and \f(CWld\fP commands so that they can find \f(CWlibpq.a\fP. .sh 2 "Postgres Header Files" .lp The directory \f(CW.../include\fP contains copies of most of the header files that front-end applications might need. You can compile a frontend program with the \f(CW-I\fP directive to \f(CWcc\fP as illustrated in the following example: .(l % \fBcc -I/usr/local/postgres/include -o\fP \fIfoo foo.c\fP \fB-lpq\fP .)l .lp Occassionally a front-end program source might reference header files from the \*(PG source that were not copied into the \f(CWinclude\fP directory. If your front-end program complains about not being able to find header files, either add the missing header files to the \f(CWinclude/\fP directory and notify us of the problem, or just point the \f(CW-I\fP compiler directive directly into the source as was done in the past. E.g., .(l % \fBcc -I/usr/local/postgres/src/backend -o\fP \fIfoo foo.c\fP \fB-lpq\fP .)l If you do this, you may need to add the following \f(CW#define\fPs in your source to set the PORTNAME \(em add them prior to any \f(CW#include\fPs: .(l .ft CW #define PORTNAME_\fIPORTNAME\fP .ft .)l For example, if you are running on the ultrix4 port, you would put .(l .ft CW #define PORTNAME_ultrix4 .ft .)l in your program, or if you're running the sparc port put .(l .ft CW #define PORTNAME_sparc .ft .)l in your program source. .sh 2 "Wisconsin Benchmark Database" .lp In \f(CW.../postgres/src/regress/bench\fP are files which are the queries used in the \*(PG version of the Wisconsin benchmark. The Wisconsin benchmark illustrates basic relational performance using B-tree indices on nontrivial amounts of data. To run the benchmark, \f(CWcd\fP to that directory and type .(l % \fBbmake runtest\fP .)l .lp .sh 2 "Minimal Installation" .lp It is the intention that everything below the \f(CWsrc/\fP directory can be removed. Sometimes however, as stated earlier, the \f(CWinclude/\fP directory may not have all the necessary files to compile all the frontend programs, so you may might get burned if you remove the source. Should you really wish to remove the source to reclaim space you could always copy all the header files from the backend into the include directory (preserving the directory structure of course). .\" ---------------- .\" Documentation .\" ---------------- .sh 1 "Documentation" .lp Plain text and PostScript versions of the manual pages and documents are available in the directories \f(CWman/\fP and \f(CWdoc/\fP at the top level. To recreate these documents, there are corresponding directories in \f(CWsrc/{man,doc}\fP. They are currently configured to require \f(CWgroff\fP and friends, but you may be able to change the \f(CWMakefile\fP to use other facilities if you have them. If you change directories to \f(CWman/\fP and \f(CWdoc/\fP and type: .(l % \fBbmake\fP % \fBbmake install\fP .)l in each, it will format and install the documents into the corresponding destination directories. In general, recreating documents from their source is very difficult due to differences in macro packages and formatting programs (in short, good luck!). .\" ---------------- .\" Miscellaneous .\" ---------------- .sh 1 "Miscellaneous" .sh 2 "Bug reports" .lp If you find a bug in \*(PG, please send mail to .(l .ft CW bug-postgres@postgres.Berkeley.EDU .ft .)l or .(l .ft CW uunet!ucbvax!postgres!bug-postgres .ft .)l describing as precisely as possible the command that caused the problem, concise instructions on how to repeat the bug, and a script showing the bug. If possible, a stack trace (generated using a debugger such as \f(CWdbx\fP or \f(CWgdb\fP) should also be provided. (The backend program will leave its core dumps in the directory PGDATA\f(CW/base/your_database\fP, where \*(lqyour_database\*(rq is the name of your database.) However, see the next section. .sh 2 "Consulting" .lp This software is unsupported, public domain software. Although we are interested in feedback, it is impossible for us to make any commitment to provide support in a research environment. .lp If you do want to talk directly to the \*(PG group, electronic mail is the only method. We can be reached via the Internet as .(l .ft CW post_questions@postgres.Berkeley.EDU .ft .)l or .(l .ft CW uunet!ucbvax!postgres!post_questions .ft .)l Please be aware that this was the last release of \*(PG from the University of California, and for all practical purposes there is no longer a \*(PG group. However some of us may still be reading mail for a while and it is likely that some correspondence will occur. .lp .sh 2 "Postgres Mailing List" .lp A mailing list for \*(PG announcements and discussion is available for anyone who is interested. If you wish to subscribe to this mailing list, send mail to .(l .ft CW postgres-request@postgres.Berkeley.EDU .ft .)l or .(l .ft CW uunet!ucbvax!postgres!postgres-request .ft .)l with \f(CWADD\fP as the subject. Note that mail sent to this address is processed .b electronically . (Deletion requests are handled by sending mail to the same address with subject \f(CWDEL\fP.) .lp The mailing list itself is called .(l .ft CW postgres@postgres.Berkeley.EDU .ft .)l or .(l .ft CW uunet!ucbvax!postgres!postgres .ft .)l and all mail sent to this address will be will be routed to the mailing list membership. As of the time of this release, this mailing list was being distributed to over 600 sites around the world, so please do .b NOT send administrative requests to this address. If you have any problems with the mailing list, send mail to \f(CWpost_questions\fP.