Complete Linux

home *** CD-ROM | disk | FTP | other *** search

/ Complete Linux / Complete Linux.iso / docs / apps / database / postgres / postgre2.z / postgre2 / doc / postgres-setup < prev next >

Wrap

Text File | 1992-08-27 | 34.4 KB | 1,150 lines

.\" .\" 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.0.1 setup instructions .\" .\" ---------------------------------------------------------------- .de RV .ie "\\$2"" \ \{\ . ds VT "<No Title> . ds VN "<Unaudited Revision> . ds VD \*(td .\} .el \ \{\ . ds VT \\$7 . ds VD \\$4 . ds VN \\$3 .\} .. .hx .fo ''%'' .ce 99 .ps 18 .b POSTGRES INSTALLATION INSTRUCTIONS .r .ps 14 .sp 0.25v C-Only Release 4.0.1 .sp 0.25v .ce 0 .sp .\" ---------------- .tm Document Overview .\" ---------------- .ds PG "\\s-2POSTGRES\\s+2 .sh 0 "Document Overview" .(l Document Overview Introduction Site Requirements Hardware Software Distribution Tape Expertise Configuration Operating System Disk Partition Swap Partition Kernel Lisp Installing \*(PG Overview Preparation Finding Space for \*(PG Creating /usr/postgres Creating the \*(lqpostgres\*(rq user Loading Loading \*(PG Configuration Kernel reconfiguration Configuring \*(PG Compiling Compiling \*(PG Creating the initial database Testing Testing \*(PG Running \*(PG The \*(PG Postmaster The \*(PG Terminal Monitor The \*(PG Backend \*(PG Support Programs Optional Installation Installing LIBPQ, the \*(PG frontend library Performance Tuning Demo Database Minimal Installation Documentation Printing the Manual and Reference If you do not have a Postscript printer Printing the Technical Reports and Tutorials If the directory has a makefile Miscellaneous Bug Reports Known Bug List Consulting Postgres BBS .)l .bp .\" ---------------- .tm Introduction .\" ---------------- .sh 1 "Introduction" .pp 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 it obtain an educational license to the derived work. For further information, consult the Berkeley Campus Software Office, 295 Evans Hall, University of California, Berkeley, CA 94720. .pp The University and the \*(PG development group provide no warranty as to the fitness of the code for any purpose whatsoever, and cannot guarantee to assist in fixing problems. This is *unsupported* software. .\" ---------------- .tm Site Requirements .\" ---------------- .sh 1 "Site Requirements" .pp .sh 2 "Hardware" .pp \*(PG currently has been tested by the Postgres development team on Sun Microsystems 3/xx family of processors with SunOS 3.4, or 3.5, and 4.0, and Sparc architecture machines (Sparcstation and Sun 4) running SunOS 4.0 and higher. Postgres is also supported on DECstations 3100's and 5000's running Ultrix 4.0 and higher. Tested but unsupported ports for DECstation Ultrix lower than 4.0 are included. These ports are unsupported for the following reasons: the old Ultrix dynamic loader is quite buggy. 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. .pp The DECstation version requires a kernel which allows 4 megabytes of shared memory. .sh 2 "Software" .pp This implementation of \*(PG is completely in C. The distribution contains no Lisp or C++ code. .sh 2 "Distribution tape" .pp These instructions assume you have a \*(PG Version 4.0.1 distribution tape (in either 9 track, SCSI cartridge, or TK50 cartridge format) or a \*(PG tar file. .sh 2 "Expertise" .pp Once a site is properly configured and \*(PG is properly 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 the various system administration procedures. Also note that various steps require superuser authority on the system, so we advise that your site's system administrator read this document also. .sh 2 "Configuration" .pp 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 "Operating System" .pp \*(PG expects things to be configured for BSD by default. If the default on your site is to use the SunOS SysV compiler and libraries then you may have to make some changes to this procedure before compiling \*(PG. .pp One exception to this rule is that we use Sun's SysV-compatible .i make to build the system. This is the version of .i make that is installed in both the BSD and SysV environments on Suns, so this should pose no problems on these platforms. We have no problems on DECstations either. .sh 3 "Disk Partition" .pp \*(PG requires 45 megabytes of disk space, preferably on a single partition. If you don't have enough space, it is still possible to compile and run \*(PG but you will have to modify the installation scripts. .sh 3 "Kernel" .pp \*(PG makes use of the optional System V shared memory operations provided by SunOS, DEC Ultrix, and Dynix, which require a properly configured kernel which is in general different than the factory-shipped "generic" kernel. See the section on kernel configuration for details. .\" ---------------- .tm Installation .\" ---------------- .sh 1 "Installing \*(PG" .pp \*(PG installation consists of the following steps: .ip \0\0\0\(bu Preparation .ip \0\0\0\(bu Loading .ip \0\0\0\(bu Configuration .ip \0\0\0\(bu Compilation .ip \0\0\0\(bu Testing .lp Each of these steps is described below. It is advised that you read over each of these steps carefully before beginning the installation. .\" ---------------- .tm Preparation .\" ---------------- .sh 2 "Step 1 \- Preparation" .pp Some of the tasks involved in this step normally fall in the domain of the site's system administrator and may require superuser authority. If possible, we advise you to have your system administrator perform these steps. .sh 3 "Find a good place for \*(PG" .pp You should locate a disk partition with at least 45 megabytes of free space available for \*(PG. If you haven't any single partition with 25 megabytes free, you might have to spread apart the \*(PG directories across several partitions, and glue them together with symbolic links. .sh 3 "Creating the \*(PG directory" .pp Once you have located a partition with enough space, create a directory called .q postgres someplace on this partition. Then \fBcd\fR to this directory and type \fBpwd\fR. This is the full path of the directory you will install postgres in. Write it down in preparation for the next step. 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% /public /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 /public looks like a good place (it has 60 megs free) so we decide to create the postgres directory there... .r # \fBcd /public\fR # \fBmkdir postgres\fR # \fBcd postgres\fR # \fBpwd\fR /public/postgres # .)l .sh 2 "Creating /usr/postgres" .pp \*(PG expects to be .i logically installed in a directory called .q /usr/postgres , so you must create a symbolic link from /usr/postgres to whatever directory you created in the previous step. In our example, we would now type: .sp .(l # \fBln -s /public/postgres /usr/postgres\fR .)l .sh 2 "Creating the \*(lqpostgres\*(rq user" .pp Finally, we need to create a user called \*(lqpostgres\*(rq whose shell is /bin/csh and whose home directory is /usr/postgres. This can be done using the "adduser" procedures particular to your platform and site. See your system administration manual for details. .lp .b Note: .pp Due to a bug in this release, the "postgres" user must be user 6 (six). Otherwise, you may encounter problems with backends hanging, etc. See the .b Release .b Notes (described in Section 6.2 of this document) for instructions on how to get around this problem if it causes problems at your site. If it is not convienent for you to make the "postgres" user userid 6, complete the below instructions on .b Loading \*(PG, but read the .b Release .b Notes notes on how to get around this problem .b before continuing on to the .b Configuration section. .pp .\" ---------------- .tm Loading .\" ---------------- .sh 2 "Step 2 - Loading \*(PG" .pp After completing step 1 (Preparation), you should be ready to load the \*(PG files onto your system. To do this, you will need either a distribution tape or a \*(PG tar file. .pp 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 "Loading \*(PG from a Tar File". .sh 3 "Loading \*(PG from a Tape" .pp Login as postgres. .pp 3. Run "tar" with the "extract, verbose, file" options: .pp % tar xvf <tape-device> .sp where <tape-device> is the name for your tape device, i.e., /dev/rmt0, /dev/rst8, etc. .pp The file "postgres-v4r0r1.tar.Z" 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. .pp Please proceed to the section "Loading \*(PG from a Tar File". .pp .sh 2 "Loading \*(PG from a Tar File" .pp If you are not logged in as \*(PG already, log in as \*(PG. Make sure your current working directory is the \*(PG home directory, and that the \*(PG tar file is there. For the purpose of this discussion, the \*(PG tar file will be called .pp postgres-v4r0r1.tar.Z .pp Uncompress the tar file. .pp % uncompress postgres-v4r0r1.tar.Z .pp A larger file should now be in the \*(PG home directory, and the '.Z' ending should be gone, so it is now named .pp postgres-v4r0r1.tar .pp Extract \*(PG from the tar file, using the "extract, verbose, file" options: .pp % tar xvf postgres-v4r0r1.tar .pp Lots of file names and such should appear on the screen. This step may take several minutes. .pp Now do an "ls": .pp The output of the ls should look something like: .(l COPYRIGHT bench/ demo/ newconf/ src/ README doc/ ref/ test/ sample/ video/ .)l .pp At this point you have loaded the \*(PG files. Other directories will be created by the installation process. .sp .\" ---------------- .tm Configuration .\" ---------------- .sh 2 "Step 3 - Configuration" .pp 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 SunOS or DEC system administration manual carefully. This task requires superuser authority 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. .pp \*(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 postgres backend process on a machine without enough shared memory, the backend will abort with an error message. .pp This is by far the most complicated part of the installation so these steps should be performed by someone with system administration experience. Again, we advise you to consult the system administration section of your manual before doing this step. .pp For a brief discussion of shared memory, you may want to consult the Man pages for \fIshmget()\fR, \fIshmop()\fR, \fIshmctl()\fR, etc. Now proceed to the appropriate section for your machine. .pp .sh 3 "Kernel reconfiguration for Suns and Sparcs" .pp In order to reconfigure Sun or Sparc kernel, you will have to become root and add some lines to /usr/sys/conf (your kernel config file) and /usr/sys/conf/param.c (your kernel parameters file). We .i strongly advise you to make a spare copy of your system's original config and parameter files before you make any changes. .lp The following lines should be added to /usr/sys/conf/KERNEL: .sp .(l options IPCMESSAGE # SystemV IPC Message Facility options IPCSEMAPHORE # SystemV IPC Semaphore Facility options IPCSHMEM # SystemV IPC Shared-Memory Facility options EMOREIPCS # more semaphores and shared memory (for 8M) .)l .sp .lp At Berkeley, we substitute the line: .(l options EMOREIPCS # more semaphores and shared memory (for 8M) .)l .lp with the line: .(l options TTMOREIPCS # more semaphores and shared memory (for 32M) .)l .lp to allocate more shared memory so that we can run more \*(PG backends at the same time. Either of the lines will result in a kernel that has enough shared memory allocated. .lp Also add the following lines to the \fItop\fR of /usr/sys/conf/param.c: .sp .(l /* * LOCAL DEFINITIONS START */ #ifdef EMORESEMS #define EMOREIPCS #endif /* defined(EMORESEMS) */ #ifdef TTMORESEMS #define TTMOREIPCS #endif /* defined(TTMORESEMS) */ #ifdef EMOREIPCS #define SEMMNI 30 /* # of semaphore identifiers */ #define SEMMNS 180 /* # of semaphores in system */ #define SEMUME 10 /* max # of undo entries per process */ #define SEMMNU 30 /* # of undo structures in system */ #define SHMPOOL 1536 /* max total shared memory system wide (in Kbytes) */ #define SHMSEG 6 /* max attached shared memory segments per process */ #define SHMMNI 100 /* # of shared memory identifiers */ #endif /* defined(EMOREIPCS) */ #ifdef TTMOREIPCS #define SEMMNI 60 /* # of semaphore identifiers */ #define SEMMNS 384 /* # of semaphores in system */ #define SEMUME 10 /* max # of undo entries per process */ #define SEMMNU 30 /* # of undo structures in system */ #define SHMPOOL 8192 /* max total shared memory system wide (in Kbytes) */ #define SHMSEG 6 /* max attached shared memory segments per process */ #define SHMMNI 100 /* # of shared memory identifiers */ #endif /* defined(TTMOREIPCS) */ /* * LOCAL DEFINITIONS END */ .)l .pp After adding these lines, run config over the config file, install the new kernel, and reboot. .sp .sh 3 "Kernel reconfiguration for DECs" .pp In order to reconfigure your DECstation 3100 or 5000 Ultrix kernel, you will have to become root and add some lines to /usr/sys/conf (your kernel config file). .sp The following lines should be added to /usr/sys/conf/KERNEL: .sp .(l smmax 256 smseg 12 smbrk 1024 .)l .pp After adding these lines, run .i config over the configuration file, install the new kernel, and reboot. .sp .\" ---------------- .tm Compiling .\" ---------------- .sh 2 "Configuring \*(PG" .pp This release of \*(PG may require some configuration. For performance reasons, Postgres is by default compiled with the optimizer enabled and internal debugging assertions disabled. If you plan to modify Postgres, you may want to enable debugging (note that this will take Postgres up to about 50 megs from about 45 megs otherwise), and enable internal debugging assertions. .pp To enable compiler directives, read the file ./newconf/CONFIG/README for instructions on what to change. Now to edit the configuration file, .(l .sp 0.5v % \fBcd /usr/postgres/newconf/CONFIG\fP .sp 0.5v % \fBvi config.mk.<port>\fP .)l .pp where .i <port> is the following: .(l dec \- DS3100 running Ultrix LOWER than 4.0 ultrix4 \- DS3100, 5000, 5500, etc. running Ultrix 4.0 or higher sun \- Sun 3 running SunOS 3.4 or 3.5 sunos4 \- Sun 3 running SunOS 4.0 or higher sparc \- Sparcstation or Sun 4 .)l The .i only thing we recommend changing is the GCFLAGS variable. Remember the .b port .b name used here as it is necessary for Step 4. .pp .sh 2 "Step 4 - Compiling and Installing \*(PG" Now you are ready to install Postgres. To do so, simply execute the following commands: .(l % \fBcd ~postgres/newconf\fR % \fBsetenv POSTGRESHOME ~postgres\fR % \fB./Make install\fR .)l .pp .lp .i Make .i install will ask you for the port you wish to use. Use the port name that you used in .b Configuring \*(PG. You will also be asked for the name of the object tree directory; the default is ~postgres/obj.<port>. (throughout the rest of this document obj.<port> refers to the object tree directory). This step will take from about 40 minutes on Sparc II or DEC 5000 class machines to several hours on Sun 3's. The POSTGRESHOME environment variable is the home directory of the Postgres user. In the course of the installation process, the Postgres .b bin and .b data directories will be created and populated. .pp .i Make is a C shell script that runs .i make with Makefiles that are constructed on the fly. If you have problems at this point, it is possible that your .i \&.cshrc file does strange things \*- changes directories, sets or unsets environment variables, and so on. .pp You should see no errors during this phase, except possibly for warnings (which can be ignored) when compiling the output of .i yacc and .i lex. .sh 3 "Creating the initial database" .pp \*(PG databases are stored in the directory ~postgres/data. After you have compiled \*(PG, you will need to create the initial database. To do this, type .(l % \fBsetenv POSTGRESHOME ~postgres\fR % \fB~postgres/bin/postmaster &\fR % \fB~postgres/bin/createdb postgres\fR % \fBkill %~postgres/bin/postmaster\fR .)l This will create the bootstrap template database, from which the database .q postgres will be generated. The .i postmaster program will be discussed later - however, you must have it running in order to run .i createdb. If several users wish to use \*(PG, we advise you to create additional databases, one for each user. This can be done by running .i createdb with the username as the first argument. For example, to create a database for the user \*(lqbill\*(rq, type .(l % \fB~postgres/bin/createdb bill\fR .)l .\" ---------------- .tm Testing .\" ---------------- .sh 2 "Step 4 - Testing" .sh 3 "Testing \*(PG" .pp After compiling the \*(PG backend and support programs and creating the initial database, you should test your compilation with the following. Commands you should type appear in \fBboldface\fP. .(l \fB% ~postgres/bin/postgres\fR .ft CW ---debug info--- Quiet = f Noversion = f override = f DatabaseName = [postgres] ---------------- **** Transaction System Active **** InitPostgres().. POSTGRES backend interactive interface $Revision: 1.25 $ $Date: 1992/08/27 06:08:25 $ StartTransactionCommand() at Thu Nov 2 15:43:35 1989 .ft > \fBretrieve (pg_user.all)\fP .ft CW now in make_Var relation = pg_user, attr = usecatupd vnum = 1 ... .ft \fIlots of debugging output...\fP .ft CW ---- parser outputs : ((1 retrieve nil (("pg_user" 86 0 nil nil ))0 nil )((#S(resdom :resno 1 :restype 19 :reslen 16 :resname "usename" :reskey 0 :reskeyop 0)#S(var ... .ft \fIlots more debugging output...\fP .ft CW ProcessQuery() at Thu Nov 2 15:43:50 1989 blank 1: usename (typeid = 19, len = 16, byval = f) 2: usesysid (typeid = 21, len = 2, byval = t) 3: usecreatedb (typeid = 16, len = 1, byval = t) 4: usetrace (typeid = 16, len = 1, byval = t) 5: usesuper (typeid = 16, len = 1, byval = t) 6: usecatupd (typeid = 16, len = 1, byval = t) ---- 1: usename = "postgres" (typeid = 19, len = 16, byval = f) 2: usesysid = "6" (typeid = 21, len = 2, byval = t) 3: usecreatedb = "t" (typeid = 16, len = 1, byval = t) 4: usetrace = "t" (typeid = 16, len = 1, byval = t) 5: usesuper = "t" (typeid = 16, len = 1, byval = t) 6: usecatupd = "t" (typeid = 16, len = 1, byval = t) ---- 1: usename = "goh" (typeid = 19, len = 16, byval = f) 2: usesysid = "234" (typeid = 21, len = 2, byval = t) 3: usecreatedb = "t" (typeid = 16, len = 1, byval = t) 4: usetrace = "t" (typeid = 16, len = 1, byval = t) 5: usesuper = "t" (typeid = 16, len = 1, byval = t) 6: usecatupd = "t" (typeid = 16, len = 1, byval = t) ---- ... CommitTransactionCommand() at Thu Nov 2 15:43:51 1989 StartTransactionCommand() at Thu Nov 2 15:43:51 1989 .ft \fIIt works!\fP \fI The above response is an example of the raw output generated by the backend. Your actual output may be slightly different. Normally, you would use a terminal monitor to talk to the backend instead. To leave the backend, type <ctrl-D>: \fR > ^D % .)l .sp .\" ---------------- .tm Running .\" ---------------- .sh 1 "Running \*(PG" .pp \*(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 the terminal monitor, and .ip \0\0\0\(bu the backend. .lp Users are expected to use the terminal monitor. The terminal monitor sends commands to the postmaster which forwards commands to a backend. If you just completed step 3, then you have already been introduced to the \*(PG backend, so we'll talk about the other two processes now. .sh 2 "The \*(PG Postmaster" .pp The postmaster is a process which manages communication between the user's terminal monitor and a \*(PG backend. Without a running postmaster, the terminal monitor will not be able to connect to a backend. To start the postmaster, type: .(l % \fBcd ~postgres/bin\fR % \fBsetenv POSTGRESHOME ~postgres\fR % \fBpostmaster &\fR .)l Here we are using the default parameters for the postmaster. For more details, consult the Reference. .sh 2 "The \*(PG Terminal Monitor" .pp The \*(PG terminal monitor is a front-end user interface to the \*(PG backend. To start a terminal monitor, type .(l % \fBmonitor <database>\fR .)l .pp \fIDatabase\fR is the name of the database you want to use. Now we will run the monitor: .(l .ft CW Welcome to the C POSTGRES terminal monitor Go * .ft \fI 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 postgres users. We terminate the query with a \eg \*- the ``go'' command to the terminal monitor. \fR *\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 | ----------------------------- | margo | 2697 | ----------------------------- | sullivan | 1517 | ----------------------------- | kemnitz | 3491 | ----------------------------- | choi | 3898 | ----------------------------- | mer | 3665 | ----------------------------- Go .ft .ft I .pp Okay, this worked, too. Now we'll quit. .pp *\fB\eq\fP .ft CW I live to serve you. .ft % .)l .sh 2 "The \*(PG Backend" .pp The \*(PG backend is the process which does all the \*(lqreal\*(rq work. This process is started by the postmaster when the postmaster 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 % \fB~postgres/bin/postgres\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 Postgres as a multiuser system, running the backend can result in locking failures and corrupt databases, as the Postmaster handles shared resources such as semaphores and shared memory. In addition, returned tuples are displayed more usefully and input is buffered better. The backend is used interactively primarily during debugging. .sh 2 "\*(PG Support Programs" .pp 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 createdb \- creates new postgres databases createdb.sh \- creates new postgres databases - old version destroydb \- destroys postgres databases ipcclean \- frees up garbage shared memory from failed backends pg_version \- make version numbers for createdb pg_id \- gets user id's for createdb pg_uid \- gets postgres user id for initializing the template database pagedoc \- disk page doctor shmemdoc \- shared memory buffer pool doctor .)l .sh 1 "Optional Installation" .sh 2 "Installing LIBPQ, the \*(PG frontend library" .pp The file ~postgres/obj.<port>/libpq.a is created when you compile the system. This library contains various routines intended for use by frontend programs. You use this library if you want to execute Postgres queries from a C program. If you plan on doing software development, you may wish to copy this file to /usr/lib so that the C compiler can reference it with -lpq. To do this, type: .(l # \fBcp ~postgres/obj.<port>/libpq.a /usr/lib\fR .)l .sh 2 "Demo Database" .pp In ~postgres/demo are files to be included by the terminal monitor to set up a demo database. Additional files demonstrate inheritance, historical queries, abstract data types, and various other features of \*(PG. A description of the demo database can be found in ~postgres/demo/DEMO-README. .sh 2 "Video Demo Database" .pp In ~postgres/video are files that were used in the 1991 Postgres SIGMOD video. These files demonstrate both the instance level and query rewrite rule systems, views, versions, and spatial queries using R-Tree indices. A description of the video database can be found in ~postgres/video/VIDEO-README. .sh 2 "Wisconsin Benchmark Database" .pp In ~postgres/bench are files which are the queries used in the Postgres version of the Wisconsin benchmark. The Wisconsin benchmark illustrates "basic" relational performance using B-Tree indices on nontrivial amounts of data. Instructions for running the benchmark are in ~postgres/bench/WISC-README. .pp .sh 2 "Minimal Installation" .pp The directories (in ~postgres) necessary for a minimal running system are: .(l bin/ the binary programs comprising \*(PG data/ support files and user created databases files/ database initialization scripts .)l When compiled using the "default" compilation options as shipped, (ie optimization and no debugging), these directories will take up about 5 Mbytes. The following directories are necessary if Postgres is to ever be recompiled. .(l newconf/ the \*(PG configuration directory obj.<port>/ compiled \*(PG object files src/ \*(PG source files .)l .pp When compiled using the "defaults", these directories will use about 16 Mbytes. Additional Postgres directories are as follows: .(l demo/ demo database scripts video/ video demo database scripts bench/ Wisconsin benchmark database scripts sample/ Sample LIBPQ application doc/ postgres technical reports and the \*(PG Manual ref/ \*(PG Reference source .)l .pp These directories take up about 2 Mbytes, and can be reduced to about 200 Kbytes if the Postscript files in doc and ref are deleted. .pp We do not recommend deleting these unless absolutely necessary. .\" ---------------- .tm Documentation .\" ---------------- .sh 1 "Documentation" .sh 2 "Printing the Manual" .pp The \*(PG manual is now in the file .(l \fB~postgres/doc/manual.me\fR .)l This manual replaces the old tutorials, which are no longer distributed. It is recommended that you read this manual before making extensive use of \*(PG. A Postscript version of this manual is in .(l \fB~postgres/doc/psdump/manual.ps\fR .)l .pp .sh 2 "Printing the Reference" .pp The Reference is the document which details the exact syntax used by \*(PG commands, and provides interface definitions for LIBPQ and large objects. It is intended as a reference and should not be read cover to cover. .pp If you have a Postscript printer, you can print the Reference by changing directory to the .(l \fB~postgres/ref\fR .)l directory, where you will find a Postscript file called \fBref.t\fR. This file can be simply sent to the printer in whatever fashion your site uses to print Postscript files. .pp If you do not have a Postscript printer, or you have font problems, etc., the \fBref\fR directory contains a /bin/sh script called "genref". Edit this script and set the appropriate parameters for printing at your site in this script, and then execute it by typing .(l % \fBgenref\fR .)l This script will not actually try to send the job to the printer - rather it will create the \fBref.t\fR output file. You can then print the manual by sending this file directly to the printer with the regular printing commands used by your site. .pp If \fBgenref\fR fails, you may not have the \fBgrn\fR preprocessor. This preprocessor for troff allows pictures drawn with the \fBgremlin\fR graphics editor to be printed using a "troff" command. A script called \fBeatgrn\fR is provided, which will cause \fBgenref\fR to ignore \fBgrn\fR directives and print anyway - this will result in the reference being printed without illustrations. There is only one illustration, so this should not be too much of a problem. .pp .sh 3 "If you do not have a Postscript printer" .pp If you do not have a Postscript printer, change the \fBpsroff\fR command in the \fBgenref\fR script to the text formatting command you use at your site, typically \fBnroff\fR, \fBtroff\fR, or \fBditroff\fR. As stated above, use the \fBeatgrn\fR script if you do not have \fBgrn\fR. Output suitable for a line-printer can be created using \fBnroff\fR. .pp .sh 2 "Printing the Technical Reports and Tutorials" .pp Postscript versions of the Postgres technical reports, tutorials, and release notes are in the directory \fB~postgres/doc/psdump\fR. Some files are not included in Postscript form and are simply regular files - read the file \fB~postgres/doc/README\fR for details. .pp The /bin/sh script \fB~postgres/doc/print\fR contains site-specific printing parameters, and understands the file extension protocol used in the \fBdoc\fR directory. Once you set the site-specific parameters for printing in this script, you should be able to print all the files in the \fBdoc\fR easily, by executing .(l % \fBprint <filename>\fR .)l from the \fB~postgres/doc\fR directory. .pp Unlike the \fBgenref\fR script described above, this script will send the job directly to the printer. If you do not have the \fBgrn\fR utility described above, you should use the \fBeatgrn\fR script here as well. For technical reports which require \fBmake\fR, continue to the following section. .pp .sh 3 "If the directory has a makefile" .pp A couple of the technical reports use makefiles to generate their printable versions rather than the \fBprint\fR script. If the subdirectory has a makefile, you will have to change the site-specific parameters in the makefile, run .(l % \fBmake\fR .)l and then it will either print or create a printable file. Note that if the makefile uses \fBgrn\fR and you do not have access to this utility, you can use the \fBeatgrn\fR script here as well. .sh 2 "The 4.0.1 Release Notes" .pp The Postgres 4.0.1 Release Notes are in the file \fB~postgres/doc/release4.0.1.me\fR. Before working extensively with Postgres, you should read this file to find new features, known bugs, and other useful information about this release. .pp As described above, you can print this file by typing .pp .(l % \fBprint ~postgres/doc/release4.0.1.me\fR .)l .\" ---------------- .tm Miscellaneous .\" ---------------- .sh 1 "Miscellaneous" .sh 2 "Bug reports" .pp If you find a bug with \*(PG, please send mail to .(l \0\0\0\0\0bug-postgres@postgres.Berkeley.EDU or \0\0\0\0\0(ucbvax!postgres!bug-postgres) .)l describing as precisely as possible the command that caused the problem, instructions on how to repeat the bug, and a script showing the bug. .sh 2 "Known Bugs List" .pp A Known Bugs List with suggested workarounds is maintained on the machine \fBpostgres.berkeley.edu\fR in the file \fBpub/postgres-v4r0r1.bugs\fR. The Internet address of this machine is \fB128.32.149.1\fR, and if you cannot access Postgres, this file can be sent to you via e-mail. .sh 2 "Consulting" .pp This software is unsupported, public domain software. Although we are interested in feedback, it is impossible for us to make any commitment to support in a research environment. .pp If you do want to talk directly to the Postgres group, electronic mail is strongly preferred. We can be reached via the Internet as .(l \0\0\0\0\0post_questions@postgres.Berkeley.EDU or \0\0\0\0\0(ucbvax!postgres!post_questions) .)l We can also be reached at (415) 642-7520, Monday through Friday, between 1 and 4 PM Pacific Time. .pp .sh 2 "Postgres BBS" A mailing list for Postgres announcements and discussion is available for anyone who is interested. If you wish to subscribe to this mailing list, send mail to .(l \0\0\0\0\0postgres-request@postgres.Berkeley.EDU .)l with "Add" as the subject. Note that mail sent to this address is processed .b electronically. .pp The mailing list itself is called .(l \0\0\0\0\0postgres@postgres.Berkeley.EDU .)l and all mail sent to this address will be will be routed to the mailing list membership.