From f1f9ec3344d40961db0ca62cccd9f8f519f5abf2 Mon Sep 17 00:00:00 2001 From: "Thomas G. Lockhart" Date: Fri, 30 Oct 1998 19:37:19 +0000 Subject: [PATCH] Minor editing and markup changes as a result of preparing the Postscript documentation for v6.4. Bigger updates to the installation instructions (install and config). --- doc/src/sgml/Makefile | 4 +- doc/src/sgml/admin.sgml | 23 +- doc/src/sgml/config.sgml | 2 +- doc/src/sgml/datatype.sgml | 35 +-- doc/src/sgml/docguide.sgml | 525 ++++++++++++++++++--------------- doc/src/sgml/info.sgml | 7 +- doc/src/sgml/install.sgml | 310 ++++++++++++------- doc/src/sgml/installation.sgml | 13 +- doc/src/sgml/jdbc.sgml | 187 +++++------- doc/src/sgml/libpgtcl.sgml | 7 +- doc/src/sgml/libpq.sgml | 2 +- doc/src/sgml/odbc.sgml | 3 +- doc/src/sgml/page.sgml | 2 + doc/src/sgml/ports.sgml | 156 +++++----- doc/src/sgml/postgres.sgml | 21 +- doc/src/sgml/programmer.sgml | 30 +- doc/src/sgml/reference.sgml | 25 +- doc/src/sgml/spi.sgml | 36 +-- doc/src/sgml/trigger.sgml | 7 +- doc/src/sgml/user.sgml | 17 +- doc/src/sgml/xaggr.sgml | 66 +++-- doc/src/sgml/xplang.sgml | 2 +- doc/src/sgml/y2k.sgml | 2 +- 23 files changed, 831 insertions(+), 651 deletions(-) diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 83f14df581..47b2c19f99 100644 --- a/doc/src/sgml/Makefile +++ b/doc/src/sgml/Makefile @@ -8,7 +8,7 @@ # # # IDENTIFICATION -# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.6 1998/09/30 05:41:39 thomas Exp $ +# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.7 1998/10/30 19:36:51 thomas Exp $ # #---------------------------------------------------------------------------- @@ -119,5 +119,5 @@ distclean:: # Graphics %.gif: - cp -p ../graphics/%.gif . + cp -p ../graphics/$@ . diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index 5b571d61d1..51330c90fb 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,11 +1,16 @@ @@ -38,7 +43,7 @@ $log$ PostgreSQL Administrator's Guide - Covering v6.3 for general release + Covering v6.4 for general release The PostgreSQL Development Team @@ -61,12 +66,13 @@ $log$ TGL --> - (last updated 1998-02-23) + (last updated 1998-10-27) -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. +PostgreSQL is copyright (C) 1998 +by the Postgres Global Development Group. @@ -114,8 +120,9 @@ It provides SQL92/SQL3 language support, &biblio; - diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml index 0ade15cd3e..7f44b8992a 100644 --- a/doc/src/sgml/config.sgml +++ b/doc/src/sgml/config.sgml @@ -1,5 +1,5 @@ -Configuration Options +Configuration Options Parameters for Configuration (<application>configure</application>) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index f88a66ed80..cc90a0c1c3 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -386,8 +386,8 @@ should use the monetary conventions defined for -<ProductName>Postgres</ProductName> Numeric Types -Numerics +<ProductName>Postgres</ProductName> Monetary Types +Money @@ -1461,7 +1461,7 @@ The inet type stores hosts and networks in CIDR notation.
-<ProductName>Postgres</ProductName>IP Version 4 Type +<ProductName>Postgres</ProductName>IP Version 4 TypesIPV4 @@ -1500,51 +1500,48 @@ network and "/y" is the number of bits in the netmask. If the "/y" part is left off, it is calculated using assumptions from the old class system except that it is extended to include at least all of the octets in the input. -Here are some examples. - - +Here are some examples:
- +<ProductName>Postgres</ProductName>IP Types Examples + - Input - Output + CIDR Input + CIDR Displayed - select '192.168.1'::cidr + 192.168.1 192.168.1/24 - select '192.168'::cidr + 192.168 192.168.0/24 - select '128.1'::cidr + 128.1 128.1/16 - select '128':::cidr + 128 128.0/16 - select '128.1.2'::cidr + 128.1.2 128.1.2/24 - select '10.1.2'::cidr + 10.1.2 10.1.2/24 - select '10.1'::cidr + 10.1 10.1/16 - select '10'::cidr + 10 10/8 diff --git a/doc/src/sgml/docguide.sgml b/doc/src/sgml/docguide.sgml index 314b530ce1..04a5195eb8 100644 --- a/doc/src/sgml/docguide.sgml +++ b/doc/src/sgml/docguide.sgml @@ -1,9 +1,14 @@ -Introduction +The Documentation Project Packaged documentation is available in both @@ -708,9 +727,9 @@ exporting as a Postscript file. for several reasons, including the inability to make minor format fixes before committing to hardcopy and generally inadequate table support in the TeX -stylesheets. +stylesheets. - + Styles and Conventions @@ -756,80 +775,6 @@ be included below. --> - - - -Document Writing - - -Document Structure - - -There are currently five separate documents written in DocBook. Each document -has a container source document which defines the DocBook environment and other -document source files. These primary source files are located in -doc/src/sgml/, along with many of the other source files -used for the documentation. The primary source files are: - - - -postgres.sgml - - -This is the integrated document, including all other documents. - - - - - -tutorial.sgml - - -The introductory tutorial, with examples. Does not include programming topics, -and is intended to help get someone unfamiliar with SQL started. - - - - - -user.sgml - - -The User's Guide. Includes information on data types and user-level interfaces. -This is the place to put information on "why". - - - - - -reference.sgml - - -The Reference Manual. Includes Postgres SQL syntax. - - - - - -programming.sgml - - -The Programmer's Guide. Includes information on Postgres -extensibility and on the programming interfaces. - - - - - -admin.sgml - - -The Administrator's Guide. Include installation and release notes. - - - - - Authoring Tools @@ -925,13 +870,14 @@ by typing -Hardcopy Generation for v6.3 +Hardcopy Generation for v6.4 The hardcopy Postscript documentation is generated by converting the SGML source code to RTF, then -importing into Applixware. After a little cleanup (see the following -section) the output is "printed" to a postscript file. +importing into ApplixWare-4.4.1. +After a little cleanup (see the following +section) the output is "printed" to a postscript file. Some figures were redrawn to avoid having bitmap @@ -941,9 +887,11 @@ was not time to redraw it. It was converted to fit using the following commands: -% convert -v -geometry 400x400'>' figure03.gif con.gif -% convert -v -crop 400x380 con.gif connections.gif - +% convert -monochrome -v -geometry 500x500'>' catalogs.ps catalogs.gif +% convert -v -crop 400x500 catalogs.gif catalogs-cropped.gif + + + <acronym>RTF</acronym> Cleanup Procedure @@ -1069,7 +1017,7 @@ described below. We understand that there are some other packaged distributions for these tools. FreeBSD seems to have them available. Please report package status to the docs mailing list and -we will include that information here. +we will include that information here. <acronym>RPM</acronym> installation on @@ -1085,10 +1033,17 @@ and related packages. <sect2> <title>Manual installation of tools -This is a brief run-through of the process of obtaining and + +This is a brief run-through of the process of obtaining and installing the software you'll need to edit DocBook source with Emacs and process it with Norman Walsh's DSSSL style sheets to create HTML -and RTF. +and RTF. + + +These instructions do not cover new jade/DocBook +support in the sgml-tools package. The authors have +not tried this package since it adopted DocBook, but it is almost certainly +a good candidate for use. Prerequisites @@ -1114,9 +1069,9 @@ James Clark's Jade version 1.1 DocBook version 3.0 - + Norman Walsh's Modular Stylesheets -version 1.07 +version 1.19 @@ -1145,22 +1100,30 @@ Steve Pepper's Whirlwind Guide Robin Cover's database of SGML software - - -Installing Jade + +Installing Jade + -First, read the installation instructions at the above listed -URL. + +Installing Jade + + + +Read the installation instructions at the above listed +URL. -Unzip the distribution kit in a suitable place. The command to do + + +Unzip the distribution kit in a suitable place. The command to do this will be something like unzip -aU jade1_1.zip + Jade is not built using GNU Autoconf, so you'll need to edit a Makefile yourself. Since James Clark has been @@ -1202,17 +1165,24 @@ doesn't need the above settings for the math library and the Makefile. -Now type make to build Jade and the various + +Type make to build Jade and the various SP tools. + Once the software is built, make install will do the obvious. - + + + +Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit -Installing the <productname>DocBook</productname> -<acronym>DTD</acronym> kit + + +Installing the <productname>DocBook</productname> <acronym>DTD</acronym> Kit + You'll want to place the files that make up the DocBook DTD kit in the directory you built Jade to expect them in, @@ -1234,6 +1204,9 @@ the former, by giving it the single line of content: CATALOG /usr/local/share/sgml/CATALOG + + + The CATALOG file should then contain three types of lines. The first is the (optional) SGML declaration, thus: @@ -1250,6 +1223,9 @@ PUBLIC "-//Davenport//ELEMENTS DocBook Information Pool V3.0//EN" dbpool.mod PUBLIC "-//Davenport//ELEMENTS DocBook Document Hierarchy V3.0//EN" dbhier.mod PUBLIC "-//Davenport//ENTITIES DocBook Additional General Entities V3.0//EN" dbgenent.mod + + + Of course, a file containing these comes with the DocBook kit. Note that the last item on each of these lines is a file name, given here without a path. You @@ -1270,14 +1246,20 @@ named ISO. Again, proper catalog entries should accompany the entity kit you fetch. - + -Installing Norman Walsh's <acronym>DSSSL</acronym> -style sheets + +Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets + + + +Installing Norman Walsh's <acronym>DSSSL</acronym> Style Sheets -First, read the installation instructions at the above listed + +Read the installation instructions at the above listed URL. + To install Norman's style sheets, simply unzip the distribution kit in a suitable place. A good place to dot this would be /usr/local/share, which places the kit in a @@ -1288,29 +1270,54 @@ unzip -aU db107.zip + One way to test the installation is to build the HTML and RTF forms of the -PostgreSQL manual. Go to the SGML source +PostgreSQL manual. + + + + + +To build the HTML files, + go to the SGML source directory, doc/src/sgml, and say jade -t sgml -d /usr/local/share/docbook/html/docbook.dsl -D ../graphics postgres.sgml -to build the HTML files ("book1.htm" is the top level node), and + + +book1.htm is the top level node of the output.. + + + +To generate the RTF output, ready for importing +into your favorite word processing system and printing, type: jade -t rtf -d /usr/local/share/docbook/print/docbook.dsl -D ../graphics postgres.sgml -to generate the RTF output, ready for importing -into your favorite word processing system and printing. - + + + -Installing <productname>PSGML</productname> + +Installing <productname>PSGML</productname> + + + +Installing <productname>PSGML</productname> -First, read the installation instructions at the above listed + +Read the installation instructions at the above listed URL. + Unpack the distribution file, run configure, make and make install to put the byte-compiled files and info library in place. + + + Then add the following lines to your /usr/local/share/emacs/site-lisp/site-start.el file to make Emacs properly load @@ -1320,6 +1327,9 @@ file to make Emacs properly load (cons "/usr/local/share/emacs/site-lisp/psgml" load-path)) (autoload 'sgml-mode "psgml" "Major mode to edit SGML files." t) + + + If you want to use PSGML when editing HTML too, also add this: @@ -1328,22 +1338,39 @@ If you want to use PSGML when editing + + There is one important thing to note with PSGML: its author assumed that your main SGML DTD directory would be /usr/local/lib/sgml. If, as in the examples in this chapter, you use /usr/local/share/sgml, you -have to compensate for this. You can set the -SGML_CATALOG_FILES environment variable, you can +have to compensate for this. + + + + +You can set the +SGML_CATALOG_FILES environment variable. + + + +You can customize your PSGML installation (its -manual tells you how), or you can even edit the source file +manual tells you how). + + + +You can even edit the source file psgml.el before compiling and installing PSGML, changing the hard-coded paths to match your own default. - + + + -Optional: installing <productname>JadeTeX</productname> +Installing <productname>JadeTeX</productname> If you want to, you can also install JadeTeX to use @@ -1419,6 +1446,15 @@ vary according to your installation. Alternate Toolsets + +sgml-tools v2.x +now supports jade +and DocBook. It may be the preferred toolset +for working with SGML but we have not had a chance to +evaluate the new package. + + + diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml index 444ed9d35b..0adb2db0ec 100644 --- a/doc/src/sgml/info.sgml +++ b/doc/src/sgml/info.sgml @@ -48,7 +48,9 @@ Installation and management information. List of supported machines. Information for Postgres developers. This is intended for those who are contributing to the Postgres -project; application development information should appear in the Programmer's Guide. +project; application development information should appear in the +Programmer's Guide. +Currently included in the Programmer's Guide. @@ -58,8 +60,7 @@ project; application development information should appear in the Programmer's G Detailed reference information on command syntax. -At the moment, this manual is very sparse, but eventually should contain -information similar to that in the man pages. +Currently included in the User's Guide. diff --git a/doc/src/sgml/install.sgml b/doc/src/sgml/install.sgml index e3d9d593e4..0553c53b8e 100644 --- a/doc/src/sgml/install.sgml +++ b/doc/src/sgml/install.sgml @@ -414,16 +414,20 @@ $ gunzip -c ~/postgresql-v6.4.tar.gz | tar xvf - the build process (see the --prefix option below). Type $ cd /usr/src/pgsql/src -$ ./configure [ options as described below ] +$ ./configure [ options ] + + + Among other chores, the configure script selects a system-specific "template" file from the files provided in the template subdirectory. If it cannot guess which one to use for your system, it will say so and exit. In that case you'll need to figure out which one to use and run - configure again, this time giving the option to + configure again, this time giving the + option to make the right file be chosen. @@ -438,7 +442,14 @@ If your system is not automatically recognized by configure and you have to do t + +Choose configuration options. Check +for details. However, for a plain-vanilla first installation with no extra +options like multi-byte character support or locale collation support it may +be adequate to have chosen the installation areas and to run configure without +extra options specified. + The configure script accepts many additional options that you can use if you don't like the default configuration. To see them all, type @@ -449,35 +460,21 @@ If your system is not automatically recognized by configure and you have to do t --prefix=BASEDIR Selects a different base directory for the installation of the Postgres configuration. The default is /usr/local/pgsql. - --with-template=TEMPLATE Use template file TEMPLATE - the template files are assumed to be in the directory src/template, so look there for proper values. - - --with-pgport=PORT Sets the port that the postmaster process - listens for incoming connections on. The - default is port 5432. - --with-tcl Build interface libraries and programs requiring Tcl/Tk, including libpgtcl, pgtclsh, and pgtksh. - --with-perl Build the Perl interface library. - --with-odbc Build the ODBC driver package. - --enable-hba Enables Host Based Authentication (DEFAULT) - --disable-hba Disables Host Based Authentication - --enable-locale Enables USE_LOCALE - --enable-cassert Enables ASSERT_CHECKING - --with-CC=compiler Use a specific C compiler that the configure script cannot find. - --with-CXX=compiler --without-CXX Use a specific C++ compiler that the configure @@ -487,9 +484,11 @@ If your system is not automatically recognized by configure and you have to do t + -As an example, here is the configure script used on a Sparc Solaris 2.5 system - with /opt/postgres being the installation base directory: +Here is the configure script used on a Sparc Solaris 2.5 system + with /opt/postgres specified as + the installation base directory: $ ./configure --prefix=/opt/postgres \ @@ -497,11 +496,17 @@ $ ./configure --prefix=/opt/postgres \ --enable-hba --disable-locale + + Of course, you may type these three lines all on the same line. + + + + Install the HTML documentation. Type @@ -653,10 +658,13 @@ pg_id: can't load library 'libpq.so' Any account that will use Postgres must be similarly prepared. - -There are several ways to influence the runtime environment of the Postgres -server. Refer to the chapter on Administrator's Guide for more information. +There are several ways to influence the runtime environment of the + Postgres +server. Refer to the Administrator's Guide + for more information. + + The following instructions are for a bash/sh shell. Adapt accordingly for other shells. @@ -664,8 +672,13 @@ The following instructions are for a + + + - Add the following lines to your login shell, ~/.bash_profile: + Add the following lines to your login environment: + + shell, ~/.bash_profile: PATH=$PATH:/usr/local/pgsql/bin MANPATH=$MANPATH:/usr/local/pgsql/man @@ -675,6 +688,30 @@ export PATH MANPATH PGLIB PGDATA + + +Several regression tests could failed if the user's locale collation +scheme is different from that of standard C locale. + + +If you configure and compile Postgres + with the option then + set locale environment to C (or unset all LC_* variables) +by putting these additional lines to your login environment + before starting postmaster: + +LC_COLLATE=C +LC_CTYPE=C +LC_COLLATE=C +export LC_COLLATE LC_CTYPE LC_COLLATE + + + + + + + + Make sure that you have defined these variables before continuing with the remaining steps. The easiest way to do this is to type: @@ -684,10 +721,15 @@ $ source ~/.bash_profile + + - Create the database. Do not do the following as root! - This would be a major security hole. Type + Create the database installation from your Postgres +superuser account (typically account postgres). + +Do not do the following as root! +This would be a major security hole. Type $ initdb @@ -710,15 +752,151 @@ $ initdb - - Run postmaster from your Postgres superuser account (typically - account postgres). -Do not run postmaster from the root account! + +Briefly test that the backend will start and run by running it from +the command line. + + + + + Start the postmaster daemon running in the background by typing + +$ cd +$ postmaster -i + + + + + + +Create a database by typing + +$ createdb + + + + +Connect to the new database: + +$ psql + + + + +And run a sample query: + +postgres=> SELECT datetime 'now'; + + + + +Exit psql: + +postgres=> \q + + + + +Remove the test database (unless you will want to use it later for other tests): + +$ destroydb + + + + + + + Run postmaster in the background from your Postgres +superuser account (typically account postgres). +Do not run postmaster +from the root account! + + +Usually, you will want to modify + your computer so that it will automatically start postmaster whenever + it boots. It is not required; the Postgres +server can +be run successfully from non-privileged accounts without root intervention. + + + Here are some suggestions on how to do this, contributed by various + users. + + + Whatever you do, postmaster must be run by +the Postgres superuser (postgres?) +and not by root. +This is why all of the examples below start by switching user + (su) to postgres. These commands also take into account the fact + that environment variables like PATH and PGDATA may not be set properly. + + The examples are as follows. Use them with extreme caution. + + + + +If you are installing from a non-privileged account and have no root access, then +start the postmaster and send it to the background: + $ cd $ nohup postmaster > regress.log 2>&1 & + + + +Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris + 2.5.1 to contain the following single line: + +su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" + + + + +In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to + contain the following lines and make it chmod 755 and chown + root:bin. + + +#!/bin/sh +[ -x /usr/local/pgsql/bin/postmaster ] && { + su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster + -D/usr/local/pgsql/data + -S -o -F > /usr/local/pgsql/errlog' & + echo -n ' pgsql' +} + + + You may put the line breaks as shown above. The shell is smart + enough to keep parsing beyond end-of-line if there is an + expression unfinished. The exec saves one layer of shell under + the postmaster process so the parent is init. + + + +In RedHat Linux add a file /etc/rc.d/init.d/postgres.init +which is based on the example in contrib/linux/. +Then make a softlink to this file from + /etc/rc.d/rc5.d/S98postgres.init. + + + +In RedHat Linux edit file /etc/inittab to add the + following as a single line: + + +pg:2345:respawn:/bin/su - postgres -c + "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data + >> /usr/local/pgsql/server.log 2>&1 </dev/null" + + + (The author of this example says this example will revive the + postmaster if it dies, but he doesn't know if there are other side + effects.) + + + @@ -819,82 +997,6 @@ $ gmake clean - - - If you haven't already done so, this would be a good time to modify - your computer so that it will automatically start postmaster whenever - you boot your computer. - - Here are some suggestions on how to do this, contributed by various - users. - - - Whatever you do, postmaster must be run by -the Postgres superuser (postgres?) -and not by root. -This is why all of the examples below start by switching user - (su) to postgres. These commands also take into account the fact - that environment variables like PATH and PGDATA may not be set properly. - - The examples are as follows. Use them with extreme caution. - - - - -Edit file rc.local on NetBSD or file rc2.d on SPARC Solaris - 2.5.1 to contain the following single line: - -su postgres -c "/usr/local/pgsql/bin/postmaster -S -D /usr/local/pgsql/data" - - - - -In FreeBSD 2.2-RELEASE edit /usr/local/etc/rc.d/pgsql.sh to - contain the following lines and make it chmod 755 and chown - root:bin. - - -#!/bin/sh -[ -x /usr/local/pgsql/bin/postmaster ] && { - su -l pgsql -c 'exec /usr/local/pgsql/bin/postmaster - -D/usr/local/pgsql/data - -S -o -F > /usr/local/pgsql/errlog' & - echo -n ' pgsql' -} - - - You may put the line breaks as shown above. The shell is smart - enough to keep parsing beyond end-of-line if there is an - expression unfinished. The exec saves one layer of shell under - the postmaster process so the parent is init. - - - -In RedHat Linux add a file /etc/rc.d/init.d/postgres.init -which is based on the example in contrib/linux/. -Then make a softlink to this file from - /etc/rc.d/rc5.d/S98postgres.init. - - - -In RedHat Linux edit file /etc/inittab to add the - following as a single line: - - -pg:2345:respawn:/bin/su - postgres -c - "/usr/local/pgsql/bin/postmaster -D/usr/local/pgsql/data - >> /usr/local/pgsql/server.log 2>&1 </dev/null" - - - (The author of this example says this example will revive the - postmaster if it dies, but he doesn't know if there are other side - effects.) - - - - - - If you haven't already done so, this would be a good time to modify diff --git a/doc/src/sgml/installation.sgml b/doc/src/sgml/installation.sgml index 73c5d02547..278a34ab04 100644 --- a/doc/src/sgml/installation.sgml +++ b/doc/src/sgml/installation.sgml @@ -1,10 +1,15 @@ -PostgreSQL Administrator's Guide +PostgreSQL Installation Guide - Covering v6.3 for general release + Covering v6.4 for general release The PostgreSQL Development Team @@ -115,6 +121,7 @@ and installing documentation, and then print or browse the &ports; +&config; &install; &release; diff --git a/doc/src/sgml/jdbc.sgml b/doc/src/sgml/jdbc.sgml index 71758ddcfa..4a3485e01b 100644 --- a/doc/src/sgml/jdbc.sgml +++ b/doc/src/sgml/jdbc.sgml @@ -50,7 +50,7 @@ as the driver uses some dynamic loading techniques for performance reasons, and javac cannot cope. The Makefile will generate the jar archive. - + Installing the Driver @@ -76,7 +76,7 @@ Loading the driver is covered later on in this chapter. -Preparing the database for <acronym>JDBC</acronym> +Preparing the Database for <acronym>JDBC</acronym> Because Java can only use TCP/IP connections, the Postgres postmaster @@ -89,10 +89,12 @@ to add something like: host all 127.0.0.1 255.255.255.255 password -Here access to all databases are possible from the local machine with JDBC. +Here access to all databases are possible from the local machine +with JDBC. -The JDBC Driver supports trust, ident, password and crypt authentication methods. +The JDBC Driver supports trust, ident, +password and crypt authentication methods. @@ -193,15 +195,15 @@ forms: -jdbc:postgresql:database -jdbc:postgresql://database +jdbc:postgresql://host/database -jdbc:postgresql://port/host:port/database where: @@ -209,7 +211,7 @@ where: -host @@ -217,7 +219,7 @@ The hostname of the server. Defaults to "localhost". -port @@ -226,7 +228,7 @@ standard port number (5432). -database @@ -243,7 +245,7 @@ Connection db = DriverManager.getConnection(url,user,pwd); -Issuing a query and processing the result +Issuing a Query and Processing the Result Any time you want to issue SQL statements to the database, you require a @@ -252,11 +254,13 @@ method to issue a query. This will return a ResultSet instance, which contains the entire result. - -Some notes about using the Statement interface: + +Using the Statement Interface - +The following must be considered when using the Statement interface: + + You can use a Statement instance as many times as you want. You could @@ -276,14 +280,16 @@ as it covers some important points. - -Some notes about using the ResultSet interface: + +Using the ResultSet Interface - +The following must be considered when using the ResultSet interface: + + -Before reading any values, you must call next(). This returns true if +Before reading any values, you must call next(). This returns true if there is a result, but more importantly, it prepares the row for processing. @@ -291,58 +297,60 @@ there is a result, but more importantly, it prepares the row for processing. Under the JDBC spec, you should access a field only once. It's safest to stick to this rule, although at the current time, the Postgres driver will allow you to access a field as many times as you want. + -You must close() a ResultSet once you have finished with it. +You must close a ResultSet by calling close() once you have finished with it. + Once you request another query with the Statement used to create a -ResultSet, the currently open instance is closed(). +ResultSet, the currently open instance is closed. + +An example is as follows: + + Statement st = db.createStatement(); ResultSet rs = st.executeQuery(select * from mytable); while(rs.next()) { - - - - -System.out.print(Column 1 returned ); - - -System.out.println(rs.getString(1)); + System.out.print(Column 1 returned ); + System.out.println(rs.getString(1)); } rs.close(); st.close(); - + -Performing updates +Performing Updates To perform an update (or any other SQL statement that does not return a result), you simply use the executeUpdate() method: - - st.executeUpdate(create table basic (a int2, b int2)); - + +st.executeUpdate(create table basic (a int2, b int2)); + + -Closing the connection +Closing the Connection To close the database connection, simply call the close() method to the Connection: - + db.close(); - + Using Large Objects -In Postgres, large objects (also known as BLOBS) are used to hold data in +In Postgres, +large objects (also known as blobs) are used to hold data in the database that cannot be stored in a normal SQL table. They are stored as a Table/Index pair, and are refered to from your own tables, by an OID value. @@ -357,118 +365,83 @@ In JDBC, the standard way to access them is using the getBina method in ResultSet, and setBinaryStream() method in PreparedStatement. These methods make the large object appear as a Java stream, allowing you to use the java.io package, and others, to manipulate the object. + -Example: - -You have a table containing the file name of an image, and a large object +For example, suppose +you have a table containing the file name of an image, and a large object containing that image: - - create table images (imgname name,imgoid oid); + + +create table images (imgname name,imgoid oid); + + To insert an image, you would use: - - - - - + + File file = new File(myimage.gif); - - FileInputStream fis = new FileInputStream(file); - - -PreparedStatement ps = conn.prepareStatement(insert into images -values (?,?)); - - +PreparedStatement ps = conn.prepareStatement(insert into images values (?,?)); ps.setString(1,file.getName()); - - ps.setBinaryStream(2,fis,file.length()); - - ps.executeUpdate(); - - ps.close(); - - fis.close(); - + + Now in this example, setBinaryStream transfers a set number of bytes from a stream into a large object, and stores the OID into the field holding a reference to it. + Retrieving an image is even easier (I'm using PreparedStatement here, but Statement can equally be used): - - - - - -PreparedStatement ps = con.prepareStatement(select oid from -images where name=?); - - + + +PreparedStatement ps = con.prepareStatement(select oid from images where name=?); ps.setString(1,myimage.gif); - - ResultSet rs = ps.executeQuery(); - - if(rs!=null) { - - while(rs.next()) { - - - InputStream is = rs.getBinaryInputStream(1); - - - // use the stream in some way here - - - is.close(); - - + InputStream is = rs.getBinaryInputStream(1); + // use the stream in some way here + is.close(); } - - rs.close(); - - } - - ps.close(); - + + Now here you can see where the Large Object is retrieved as an InputStream. You'll also notice that we close the stream before processing the next row in the result. This is part of the JDBC Specification, which states that any InputStream returned is closed when ResultSet.next() or ResultSet.close() is called. - <application>Postgres</application> Extensions to the <acronym>JDBC</acronym> <acronym>API</acronym> -Postgres is an extensible database system. You can add your own functions +Postgres is an extensible database system. +You can add your own functions to the backend, which can then be called from queries, or even add your own data types. Now, as these are facilities unique to us, we support them from Java, with -a set of extension API's. Some features within the core of the standard driver +a set of extension API's. Some features within +the core of the standard driver actually use these extensions to implement Large Objects, etc. - +************************************************************ +Nothing marked up from here on. It looks like it will be tricky: +what do we want to do with the class inheritance diagrams? +- thomas 1998-10-23 +************************************************************ +--> + Accessing the extensions @@ -2548,10 +2521,10 @@ If you have not yet read it, I'd advise you read the JDBC Documentation (supplied with Sun's JDK), and the JDBC Specification. Both are available on -JavaSoft's web site. -My own web site contains updated information not included in this document, and also includes precompiled drivers for v6.4, and earlier. diff --git a/doc/src/sgml/libpgtcl.sgml b/doc/src/sgml/libpgtcl.sgml index f917fb5b64..798dcebccd 100644 --- a/doc/src/sgml/libpgtcl.sgml +++ b/doc/src/sgml/libpgtcl.sgml @@ -2,8 +2,9 @@ pgtcl -pgtcl is a tcl package for front-end programs to interface with Postgres -backends. It makes most of the functionality of libpq available to +pgtcl is a tcl package for front-end programs +to interface with Postgres +backends. It makes most of the functionality of libpq available to tcl scripts. @@ -16,7 +17,7 @@ This package was originally written by Jolly Chen.
-PGTCL Commands +<literal>pgtcl</literal> Commands diff --git a/doc/src/sgml/libpq.sgml b/doc/src/sgml/libpq.sgml index 57097a1c5a..7657ac2319 100644 --- a/doc/src/sgml/libpq.sgml +++ b/doc/src/sgml/libpq.sgml @@ -1,5 +1,5 @@ -<FileName>libpq</FileName> +libpq diff --git a/doc/src/sgml/odbc.sgml b/doc/src/sgml/odbc.sgml index 069b9ab41a..46033e9210 100644 --- a/doc/src/sgml/odbc.sgml +++ b/doc/src/sgml/odbc.sgml @@ -577,8 +577,7 @@ be able to access the Postgres Enabling ApplixWare Database Access -Note that -these instructions are for the 4.4.1 release of +These instructions are for the 4.4.1 release of ApplixWare on Linux. Refer to the Linux Sys Admin on-line book for more detailed information. diff --git a/doc/src/sgml/page.sgml b/doc/src/sgml/page.sgml index 024554b6f8..8c468ca3b1 100644 --- a/doc/src/sgml/page.sgml +++ b/doc/src/sgml/page.sgml @@ -34,8 +34,10 @@ classes (e.g., a B-tree index) are structured. +Item +Description diff --git a/doc/src/sgml/ports.sgml b/doc/src/sgml/ports.sgml index 4cd3afaf5e..ca8218e3b1 100644 --- a/doc/src/sgml/ports.sgml +++ b/doc/src/sgml/ports.sgml @@ -1,14 +1,19 @@ Ports - -Currently Supported Platforms - This manual describes version 6.4 of Postgres. The Postgres developer community has -compiled and tested Postgres on the following -platforms: +compiled and tested Postgres on a +number of platforms. Check +the web site +for the latest information. + + +Currently Supported Platforms + + +At the time of publication, the following platforms have been tested:
Supported Platforms @@ -24,13 +29,11 @@ platforms: - AIX 4.1.x-4.2 + AIX 4.2.1 RS6000 - v6.3 - 1998-03-01 - 4.1.4.0,4.2 (Darren King), - 4.1.5 (Andreas Zeugswetter); - 3.2.5 confirmed on v6.2.1 (Frank Dana) + v6.4 + 1998-10-27 + (Andreas Zeugswetter) BSDI @@ -42,45 +45,25 @@ platforms: FreeBSD 2.2.x-3.x x86 - v6.3 - 1998-03-01 + v6.4 + 1998-10-26 (Tatsuo Ishii, Marc Fournier) - - NetBSD 1.3.2 - x86 - v6.4 - 1998-10-25 - (Brook Milligan) - - - NetBSD 1.3 - NS32532 - v6.3 - 1998-07-20 - (Phil Nelson) - - - NetBSD 1.3 - Sparc - v6.3 - 1998-03-01 - (Tom I Helbekkmo) - - - NetBSD 1.3 - VAX - v6.3 - 1998-03-01 - (Tom I Helbekkmo) - DGUX 5.4R4.11 m88k v6.3 1998-03-01 - (Brian E Gallew) + v6.4 probably OK. Needs new maintainer. (Brian E Gallew) + + + Digital Unix 4.0 + Alpha + v6.4 + 1998-10-29 + Minor patchable problems + (Pedro J. Lobo) HPUX @@ -99,30 +82,20 @@ platforms: 5.x is different (Andrew Martin) - - Digital 4.0 - Alpha - v6.3.2 - 1998-04-16 - reported working for DUnix/v3.2g - (Pedro J. Lobo) - linux 2.0.x Alpha v6.3.2 1998-04-16 - mostly successful - (Ryan Kirkpatrick, - Jeff Sturm ) + Mostly successful. Needs work for v6.4. + (Ryan Kirkpatrick) linux 2.0.x x86 v6.4 - 1998-10-09 - (Thomas Lockhart, - Tatsuo Ishii) + 1998-10-27 + (Thomas Lockhart) linux 2.0.x/glibc2 @@ -140,33 +113,76 @@ platforms: (Tom Szybist) - mklinux + linuxPPC 2.1.24 + PPC603e + v6.4 + 1998-10-26 + Powerbook 2400c(Tatsuo Ishii) + + + mklinux DR3 PPC750 v6.4 1998-09-16 - (Tatsuo Ishii) + PowerMac 7600 (Tatsuo Ishii) - SCO + NetBSD/i386 1.3.2 x86 + v6.4 + 1998-10-25 + (Brook Milligan) + + + NetBSD-current + NS32532 + v6.4 + 1998-10-27 + (small problems in date/time math (Jon Buller) + + + NetBSD/sparc 1.3H + Sparc + v6.4 + 1998-10-27 + (Tom I Helbekkmo) + + + NetBSD 1.3 + VAX v6.3 1998-03-01 - partial success - (Billy G. Allie) + (Tom I Helbekkmo) - Solaris + SCO UnixWare 2.x x86 v6.3 1998-03-01 + aka UNIVEL + (Billy G. Allie) + + + SCO UnixWare 7 + x86 + v6.4 + 1998-10-04 + (Billy G. Allie) + + + Solaris + x86 + v6.4 + 1998-10-28 (Marc Fournier) - Solaris 2.5.1-2.6 + Solaris 2.6-2.7 Sparc v6.4 - 1998-10-25 - (Tom Szybist) + 1998-10-28 + (Tom Szybist, + Frank Ridderbusch) SunOS 4.1.4 @@ -180,7 +196,7 @@ platforms: SVR4 MIPS v6.4 - 1998-10-08 + 1998-10-28 no 64-bit int support (Frank Ridderbusch) @@ -192,14 +208,6 @@ platforms: confirmed with patching (Doug Winterburn) - - Unixware - x86 - v6.4 - 1998-10-04 - aka UNIVEL - (Billy G. Allie) - Windows NT x86 diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index 0aee12b828..6c5f7b3850 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,11 +1,16 @@ -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. +PostgreSQL is copyright (C) 1998 +by the Postgres Global Development Group. diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index 060066dc3b..fd21d57e33 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,11 +1,16 @@ @@ -81,7 +86,7 @@ $log$ PostgreSQL Programmer's Guide - Covering v6.3 for general release + Covering v6.4 for general release The PostgreSQL Development Team @@ -104,7 +109,7 @@ $log$ TGL --> - (last updated 1998-02-24) + (last updated 1998-10-27) @@ -129,7 +134,7 @@ Your name here... --> - + Summary @@ -153,13 +158,19 @@ It provides SQL92/SQL3 language support, &xaggr; &rules; &xindex; -&xplang; &gist; +&xplang; &dfunc; + + &trigger; &spi; &lobj; @@ -176,7 +187,7 @@ It provides SQL92/SQL3 language support, The arch-dev chapter is current almost identical to the arch-pg chapter appearing earlier in the Programmer's Guide. If the Developer's Guide is -split into a separate document the start using this +split into a separate document then start using this again. - thomas 1998-10-23 &arch-dev; @@ -198,7 +209,8 @@ again. &biblio; diff --git a/doc/src/sgml/reference.sgml b/doc/src/sgml/reference.sgml index a7324a68ec..ecb45c91a2 100644 --- a/doc/src/sgml/reference.sgml +++ b/doc/src/sgml/reference.sgml @@ -1,9 +1,18 @@ + +$Log: reference.sgml,v $ +Revision 1.4 1998/10/30 19:37:12 thomas +Minor editing and markup changes as a result of preparing the Postscript + documentation for v6.4. +Bigger updates to the installation instructions (install and config). + + +--> @@ -61,7 +70,8 @@ -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. +PostgreSQL is copyright (C) 1998 +by the Postgres Global Development Group. @@ -101,11 +111,16 @@ It provides SQL92/SQL3 language support, &commands; + + &biblio; + diff --git a/doc/src/sgml/spi.sgml b/doc/src/sgml/spi.sgml index c184ff2846..eb6b1d6679 100644 --- a/doc/src/sgml/spi.sgml +++ b/doc/src/sgml/spi.sgml @@ -12,47 +12,49 @@ Server Programming Interface - The Server Programming Interface (SPI) is an attempt to give users the -ability to run SQL queries inside user-defined C functions. -Given the lack -of a proper Procedural Language (PL) in the current version of -Postgres, -SPI is the only way to write server-stored procedures and triggers. In the future -SPI will be used as the "workhorse" for a PL. +The Server Programming Interface +(SPI) gives users the +ability to run SQL queries inside user-defined +C functions. +The available Procedural Languages (PL) give an alternate +means to access these capabilities. - In fact, SPI is just a set of native interface functions to simplify -access to the Parser, Planner, Optimizer and Executor. SPI also does some -memory management. +In fact, SPI is just a set of native interface functions +to simplify access to the Parser, Planner, Optimizer and Executor. +SPI also does some memory management. - To avoid misunderstanding we'll use function to mean SPI interface -functions and procedure for user-defined C-functions using SPI. +To avoid misunderstanding we'll use function +to mean SPI interface functions and +procedure for user-defined C-functions +using SPI. - SPI procedures are always called by some (upper) Executor and the SPI +SPI procedures are always called by some (upper) +Executor and the SPI manager uses the Executor to run your queries. Other procedures may be called by the Executor running queries from your procedure. - Note, that if during execution of a query from a procedure the transaction +Note, that if during execution of a query from a procedure the transaction is aborted then control will not be returned to your procedure. Rather, all work will be rolled back and the server will wait for the next command from the client. This will be changed in future versions. - Other restrictions are the inability to execute BEGIN, END and ABORT +Other restrictions are the inability to execute BEGIN, END and ABORT (transaction control statements) and cursor operations. This will also be changed in the future. - If successful, SPI functions return a non-negative result (either via +If successful, SPI functions return a non-negative result (either via a returned integer value or in SPI_result global variable, as described below). On error, a negative or NULL result will be returned. @@ -892,7 +894,7 @@ TBD SPI_execp - Executes a plan prepared or returned by SPI_saveplan +Executes a plan from SPI_saveplan SPIconnecting SPI_execp diff --git a/doc/src/sgml/trigger.sgml b/doc/src/sgml/trigger.sgml index f612f65168..4d18a042da 100644 --- a/doc/src/sgml/trigger.sgml +++ b/doc/src/sgml/trigger.sgml @@ -2,9 +2,10 @@ Triggers - While the current version of Postgres has various client interfaces -such as Perl, Tcl, Python and C, it lacks an actual Procedural Language -(PL). We hope to have a proper PL one day. In the meantime it is possible +Postgres has various client interfaces +such as Perl, Tcl, Python and C, as well as two +Procedural Languages +(PL). It is also possible to call C functions as trigger actions. Note that STATEMENT-level trigger events are not supported in the current version. You can currently specify BEFORE or AFTER on INSERT, DELETE or UPDATE of a tuple as a trigger event. diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 38bd7d942d..713235cb3e 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,11 +1,16 @@ + @@ -87,7 +90,8 @@ Include new chapters. -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. +PostgreSQL is copyright (C) 1998 +by the Postgres Global Development Group. @@ -141,10 +145,13 @@ It provides SQL92/SQL3 language support, + &biblio; + diff --git a/doc/src/sgml/xaggr.sgml b/doc/src/sgml/xaggr.sgml index b4d9aa4402..b0a5a48b28 100644 --- a/doc/src/sgml/xaggr.sgml +++ b/doc/src/sgml/xaggr.sgml @@ -2,31 +2,36 @@ Extending <Acronym>SQL</Acronym>: Aggregates - Aggregates in Postgres are expressed in terms of state + Aggregates in Postgres +are expressed in terms of state transition functions. That is, an aggregate can be defined in terms of state that is modified whenever an instance is processed. Some state functions look at a particular value in the instance when computing the new - state (sfunc1 in the create aggregate syntax) while + state (sfunc1 in the +create aggregate syntax) while others only keep track of their own internal state (sfunc2). - If we define an aggregate that uses only sfunc1, we + If we define an aggregate that uses only +sfunc1, we define an aggregate that computes a running function of the attribute values from each instance. "Sum" is an example of this kind of aggregate. "Sum" starts at zero and always adds the current instance's value to - its running total. We will use the int4pl that is - built into Postgres to perform this addition. + its running total. We will use the +int4pl that is + built into Postgres +to perform this addition. - CREATE AGGREGATE complex_sum ( - sfunc1 = complex_add, - basetype = complex, - stype1 = complex, - initcond1 = '(0,0)' - ); +CREATE AGGREGATE complex_sum ( + sfunc1 = complex_add, + basetype = complex, + stype1 = complex, + initcond1 = '(0,0)' +); - SELECT complex_sum(a) FROM test_complex; +SELECT complex_sum(a) FROM test_complex; +------------+ |complex_sum | @@ -37,22 +42,27 @@ - If we define only sfunc2, we are specifying an aggregate + If we define only sfunc2, we are +specifying an aggregate that computes a running function that is independent of the attribute values from each instance. "Count" is the most common example of this kind of aggregate. "Count" starts at zero and adds one to its running total for each instance, ignoring the instance - value. Here, we use the built-in int4inc routine to do + value. Here, we use the built-in +int4inc routine to do the work for us. This routine increments (adds one to) its argument. - CREATE AGGREGATE my_count (sfunc2 = int4inc, -- add one - basetype = int4, stype2 = int4, - initcond2 = '0') +CREATE AGGREGATE my_count ( + sfunc2 = int4inc, -- add one + basetype = int4, + stype2 = int4, + initcond2 = '0' +); - SELECT my_count(*) as emp_count from EMP; +SELECT my_count(*) as emp_count from EMP; +----------+ |emp_count | @@ -74,16 +84,18 @@ the count. - CREATE AGGREGATE my_average (sfunc1 = int4pl, -- sum - basetype = int4, - stype1 = int4, - sfunc2 = int4inc, -- count - stype2 = int4, - finalfunc = int4div, -- division - initcond1 = '0', - initcond2 = '0') +CREATE AGGREGATE my_average ( + sfunc1 = int4pl, -- sum + basetype = int4, + stype1 = int4, + sfunc2 = int4inc, -- count + stype2 = int4, + finalfunc = int4div, -- division + initcond1 = '0', + initcond2 = '0' +); - SELECT my_average(salary) as emp_average FROM EMP; +SELECT my_average(salary) as emp_average FROM EMP; +------------+ |emp_average | diff --git a/doc/src/sgml/xplang.sgml b/doc/src/sgml/xplang.sgml index 742d6a3ba6..feb1cc88a2 100644 --- a/doc/src/sgml/xplang.sgml +++ b/doc/src/sgml/xplang.sgml @@ -1,5 +1,5 @@ -Extending <Acronym>SQL</Acronym>: Procedural languages +Procedural Languages