diff options
| -rw-r--r-- | doc/src/sgml/Makefile | 4 | ||||
| -rw-r--r-- | doc/src/sgml/about.sgml | 18 | ||||
| -rw-r--r-- | doc/src/sgml/admin.sgml | 32 | ||||
| -rw-r--r-- | doc/src/sgml/biblio.sgml | 184 | ||||
| -rw-r--r-- | doc/src/sgml/config.sgml | 270 | ||||
| -rw-r--r-- | doc/src/sgml/ecpg.sgml | 12 | ||||
| -rw-r--r-- | doc/src/sgml/history.sgml | 217 | ||||
| -rw-r--r-- | doc/src/sgml/info.sgml | 146 | ||||
| -rw-r--r-- | doc/src/sgml/intro-ag.sgml | 24 | ||||
| -rw-r--r-- | doc/src/sgml/intro-pg.sgml | 56 | ||||
| -rw-r--r-- | doc/src/sgml/intro.sgml | 419 | ||||
| -rw-r--r-- | doc/src/sgml/legal.sgml | 40 | ||||
| -rw-r--r-- | doc/src/sgml/notation.sgml | 73 | ||||
| -rw-r--r-- | doc/src/sgml/odbc.sgml | 2 | ||||
| -rw-r--r-- | doc/src/sgml/oper.sgml | 194 | ||||
| -rw-r--r-- | doc/src/sgml/postgres.sgml | 20 | ||||
| -rw-r--r-- | doc/src/sgml/programmer.sgml | 31 | ||||
| -rw-r--r-- | doc/src/sgml/query-ug.sgml | 29 | ||||
| -rw-r--r-- | doc/src/sgml/runtime.sgml | 90 | ||||
| -rw-r--r-- | doc/src/sgml/security.sgml | 155 | ||||
| -rw-r--r-- | doc/src/sgml/start-ag.sgml | 234 | ||||
| -rw-r--r-- | doc/src/sgml/syntax.sgml | 265 | ||||
| -rw-r--r-- | doc/src/sgml/user.sgml | 22 |
23 files changed, 1811 insertions, 726 deletions
diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 99bc4dab1dd..83f14df581d 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.5 1998/09/25 13:41:25 thomas Exp $ +# $Header: /cvsroot/pgsql/doc/src/sgml/Makefile,v 1.6 1998/09/30 05:41:39 thomas Exp $ # #---------------------------------------------------------------------------- @@ -67,7 +67,7 @@ install:: all:: clean:: - (rm -rf *.html *.htm) + (rm -rf HTML.manifest *.html *.htm) distclean:: $(MAKE) clean diff --git a/doc/src/sgml/about.sgml b/doc/src/sgml/about.sgml new file mode 100644 index 00000000000..ebdb1258097 --- /dev/null +++ b/doc/src/sgml/about.sgml @@ -0,0 +1,18 @@ +<Sect1> +<Title>About This Release</Title> + +<Para> + <ProductName>PostgreSQL</ProductName> is available without cost. This manual + describes version 6.4 of <ProductName>PostgreSQL</ProductName>. + +<Para> + We will use <ProductName>Postgres</ProductName> +to mean the version distributed as <ProductName>PostgreSQL</ProductName>. + +<Para> +Check the Administrator's Guide for a list of currently supported machines. +In general, +<ProductName>Postgres</ProductName> is portable to any Unix/Posix-compatible system +with full libc library support. + +</Sect1> diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index c7bbe53220e..ed53c2cfaf4 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,23 +1,34 @@ -<!-- admin.sgml -- -- Postgres administrator's guide. -- Derived from postgres.sgml. -- thomas 1998-02-27 -- -- --> +<!-- +$header$ + +Postgres Administrator's Guide. +Derived from postgres.sgml. +thomas 1998-02-27 + +$log$ + +--> + <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity intro SYSTEM "intro.sgml"> +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> + +<!entity intro-ag SYSTEM "intro-ag.sgml"> <!entity install SYSTEM "install.sgml"> <!entity ports SYSTEM "ports.sgml"> <!entity recovery SYSTEM "recovery.sgml"> <!entity regress SYSTEM "regress.sgml"> <!entity release SYSTEM "release.sgml"> +<!entity runtime SYSTEM "runtime.sgml"> <!entity start-ag SYSTEM "start-ag.sgml"> <!entity biblio SYSTEM "biblio.sgml"> ]> -<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc --> + <Book Id="admin"> <!-- Title information --> @@ -86,10 +97,11 @@ It provides SQL92/SQL3 language support, </Para> </Preface> -&intro; +&intro-ag; &ports; &install; +&runtime; &start-ag; &recovery; ®ress; diff --git a/doc/src/sgml/biblio.sgml b/doc/src/sgml/biblio.sgml index 0aa35528608..d7afdf60ded 100644 --- a/doc/src/sgml/biblio.sgml +++ b/doc/src/sgml/biblio.sgml @@ -9,14 +9,21 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos <TITLE><Acronym>SQL</Acronym> Reference Books</TITLE> <PARA>Reference texts for <Acronym>SQL</Acronym> features.</PARA> -<BIBLIOENTRY ID="BOWMAN93"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="BOWMAN93"> --> -<TITLE>The Practical <Acronym>SQL</Acronym> Handbook</TITLE> -<SUBTITLE>Using Structured Query Language</SUBTITLE> +<TITLE ID="BOWMAN93-full"> +The Practical <Acronym>SQL</Acronym> Handbook +</TITLE> +<TITLEABBREV ID="BOWMAN93"> +Bowman et al, 1993 +</TITLEABBREV> +<SUBTITLE> +Using Structured Query Language +</SUBTITLE> <EDITION>3</EDITION> <AUTHORGROUP> <AUTHOR> @@ -46,15 +53,21 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="DATE97"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="DATE97"> --> -<TITLE>A Guide to The <Acronym>SQL</Acronym> Standard</TITLE> -<TITLEABBREV>The <Acronym>SQL</Acronym> Standard</TITLEABBREV> -<SUBTITLE>A user's guide to the standard database language <Acronym>SQL</Acronym></SUBTITLE> +<TITLE id="DATE97-full"> +A Guide to the <Acronym>SQL</Acronym> Standard +</TITLE> +<TITLEABBREV id="DATE97"> +Date and Darwen, 1997 +</TITLEABBREV> +<SUBTITLE> +A user's guide to the standard database language <Acronym>SQL</Acronym> +</SUBTITLE> <EDITION>4</EDITION> <AUTHORGROUP> <AUTHOR> @@ -80,13 +93,18 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="MELT93"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="MELT93"> --> -<TITLE>Understanding the New <Acronym>SQL</Acronym></TITLE> +<TITLE ID="MELT93-full"> +Understanding the New <Acronym>SQL</Acronym> +</TITLE> +<TITLEABBREV ID="MELT93"> +Melton and Simon, 1993 +</TITLEABBREV> <SUBTITLE>A complete guide</SUBTITLE> <AUTHORGROUP> <AUTHOR> @@ -121,19 +139,24 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos <TITLE>PostgreSQL-Specific Documentation</TITLE> <PARA>This section is for related documentation.</PARA> -<BIBLIOENTRY ID="ADMIN-GUIDE"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="ADMINISTRATORS-GUIDE"> --> -<TITLE>The <ProductName>PostgreSQL</ProductName> Administrator's Guide</TITLE> +<TITLE ID="admin-guide-full"> +The <ProductName>PostgreSQL</ProductName> Administrator's Guide +</TITLE> +<TITLEABBREV ID="admin-guide"> +The Administrator's Guide +</TITLEABBREV> <Editor> <FIRSTNAME>Thomas</FIRSTNAME> <SURNAME>Lockhart</SURNAME> </Editor> -<PUBDATE>1998-03-01</PUBDATE> +<PUBDATE>1998-10-01</PUBDATE> <PUBLISHER> <PUBLISHERNAME>The PostgreSQL Global Development Group</PUBLISHERNAME> </PUBLISHER> @@ -142,19 +165,24 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="DEVELOPERS-GUIDE"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="POSTGRES-REFERENCE"> --> -<TITLE>The <ProductName>PostgreSQL</ProductName> Developer's Guide</TITLE> +<TITLE ID="dev-guide-full"> +The <ProductName>PostgreSQL</ProductName> Developer's Guide +</TITLE> +<TITLEABBREV ID="dev-guide"> +The Developer's Guide +</TITLEABBREV> <Editor> <FIRSTNAME>Thomas</FIRSTNAME> <SURNAME>Lockhart</SURNAME> </Editor> -<PUBDATE>1998-03-01</PUBDATE> +<PUBDATE>1998-10-01</PUBDATE> <PUBLISHER> <PUBLISHERNAME>The PostgreSQL Global Development Group</PUBLISHERNAME> </PUBLISHER> @@ -163,19 +191,24 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="PROGRAMMERS-GUIDE"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="PROGRAMMERS-GUIDE"> --> -<TITLE>The <ProductName>PostgreSQL</ProductName> Programmer's Guide</TITLE> +<TITLE ID="pro-guide-full"> +The <ProductName>PostgreSQL</ProductName> Programmer's Guide +</TITLE> +<TITLEABBREV ID="pro-guide"> +The Programmer's Guide +</TITLEABBREV> <Editor> <FIRSTNAME>Thomas</FIRSTNAME> <SURNAME>Lockhart</SURNAME> </Editor> -<PUBDATE>1998-03-01</PUBDATE> +<PUBDATE>1998-10-01</PUBDATE> <PUBLISHER> <PUBLISHERNAME>The PostgreSQL Global Development Group</PUBLISHERNAME> </PUBLISHER> @@ -184,19 +217,24 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="TUTORIAL-GUIDE"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="TUTORIAL"> --> -<TITLE>The <ProductName>PostgreSQL</ProductName> Tutorial Introduction</TITLE> +<TITLE ID="tutorial-guide-full"> +The <ProductName>PostgreSQL</ProductName> Tutorial Introduction +</TITLE> +<TITLEABBREV ID="tutorial-guide"> +The Tutorial +</TITLEABBREV> <Editor> <FIRSTNAME>Thomas</FIRSTNAME> <SURNAME>Lockhart</SURNAME> </Editor> -<PUBDATE>1998-03-01</PUBDATE> +<PUBDATE>1998-10-01</PUBDATE> <PUBLISHER> <PUBLISHERNAME>The PostgreSQL Global Development Group</PUBLISHERNAME> </PUBLISHER> @@ -205,19 +243,24 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="POSTGRES-USERS"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="USERS-GUIDE"> --> -<TITLE>The <ProductName>PostgreSQL</ProductName> User's Guide</TITLE> +<TITLE ID="users-guide-full"> +The <ProductName>PostgreSQL</ProductName> User's Guide +</TITLE> +<TITLEABBREV ID="users-guide"> +The User's Guide +</TITLEABBREV> <Editor> <FIRSTNAME>Thomas</FIRSTNAME> <SURNAME>Lockhart</SURNAME> </Editor> -<PUBDATE>1998-03-01</PUBDATE> +<PUBDATE>1998-10-01</PUBDATE> <PUBLISHER> <PUBLISHERNAME>The PostgreSQL Global Development Group</PUBLISHERNAME> </PUBLISHER> @@ -226,14 +269,18 @@ Selected references and readings for <Acronym>SQL</Acronym> and <ProductName>Pos --> </BIBLIOENTRY> -<BIBLIOENTRY ID="YU95"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="YU95"> --> -<TITLE>The <ProductName>Postgres95</ProductName> User Manual</TITLE> -<TITLEABBREV>YU95</TITLEABBREV> +<TITLE ID="YU95-full"> +The <ProductName>Postgres95</ProductName> User Manual +</TITLE> +<TITLEABBREV ID="YU95"> +Yu and Chen, 1995 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>A.</FIRSTNAME> @@ -266,14 +313,18 @@ The POSTGRES Group <TITLE>Proceedings and Articles</TITLE> <PARA>This section is for articles and newsletters.</PARA> -<BIBLIOENTRY ID="ONG90"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="ONG90"> --> -<TITLE>A Unified Framework for Version Modeling Using Production Rules in a Database System</TITLE> -<TITLEABBREV>ONG90</TITLEABBREV> +<TITLE ID="ONG90-full"> +A Unified Framework for Version Modeling Using Production Rules in a Database System +</TITLE> +<TITLEABBREV ID="ONG90"> +Ong and Goh, 1990 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>L.</FIRSTNAME> @@ -294,14 +345,18 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="ROWE87"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="ROWE87"> --> -<TITLE>The <ProductName>Postgres</ProductName> Data Model</TITLE> -<TITLEABBREV>ROWE87</TITLEABBREV> +<TITLE ID="ROWE87-full"> +The <ProductName>Postgres</ProductName> Data Model +</TITLE> +<TITLEABBREV ID="ROWE87"> +Rowe and Stonebraker, 1987 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>L.</FIRSTNAME> @@ -322,14 +377,19 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON86"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON86"> --> -<TITLE>The Design of <ProductName>Postgres</ProductName></TITLE> -<TITLEABBREV>STON86</TITLEABBREV> +<TITLE ID="STON86-full"> +The Design of <ProductName>Postgres</ProductName> +</TITLE> +<TITLEABBREV ID="STON86"> +Stonebraker and Rowe, 1986 +STON86 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> @@ -351,14 +411,17 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON87a"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON87a"> --> -<TITLE>The Design of the <ProductName>Postgres</ProductName> Rules System</TITLE> -<TITLEABBREV>STON87a</TITLEABBREV> +<TITLE ID="STON87a-full"> +The Design of the <ProductName>Postgres</ProductName> Rules System</TITLE> +<TITLEABBREV ID="STON87a"> +Stonebraker, Hanson, Hong, 1987 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> @@ -384,14 +447,18 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON87b"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON87b"> --> -<TITLE>The <ProductName>Postgres</ProductName> Storage System</TITLE> -<TITLEABBREV>STON87b</TITLEABBREV> +<TITLE ID="STON87b-full"> +The <ProductName>Postgres</ProductName> Storage System +</TITLE> +<TITLEABBREV ID="STON87b"> +Stonebraker, 1987 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> @@ -408,14 +475,17 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON89"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON89"> --> -<TITLE>A Commentary on the <ProductName>Postgres</ProductName> Rules System</TITLE> -<TITLEABBREV>STON89</TITLEABBREV> +<TITLE ID="STON89-full"> +A Commentary on the <ProductName>Postgres</ProductName> Rules System +</TITLE> +<TITLEABBREV ID="STON89"> +Stonebraker et al, 1989</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> @@ -434,21 +504,25 @@ The POSTGRES Group <CONFDATES>Sept. 1989</CONFDATES> <CONFTITLE>Record 18(3)</CONFTITLE> <CONFSPONSOR>SIGMOD</CONFSPONSOR> -<CONFNUM>1987</CONFNUM> +<CONFNUM>1989</CONFNUM> </CONFGROUP> <!-- </BOOKBIBLIO> --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON90a"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON90a"> --> -<TITLE>The Implementation of <ProductName>Postgres</ProductName></TITLE> -<TITLEABBREV>STON90a</TITLEABBREV> +<TITLE ID="STON90a-full"> +The Implementation of <ProductName>Postgres</ProductName> +</TITLE> +<TITLEABBREV ID="STON90a"> +Stonebraker, Rowe, Hirohama, 1990 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> @@ -473,21 +547,25 @@ The POSTGRES Group --> </BIBLIOENTRY> -<BIBLIOENTRY ID="STON90b"> +<BIBLIOENTRY> <!-- <BIBLIOMISC>‐</BIBLIOMISC> <BOOKBIBLIO ID="STON90b"> --> -<TITLE>On Rules, Procedures, Caching and Views in Database Systems</TITLE> -<TITLEABBREV>STON90b</TITLEABBREV> +<TITLE ID="STON90b-full"> +On Rules, Procedures, Caching and Views in Database Systems +</TITLE> +<TITLEABBREV ID="STON90b"> +Stonebraker et al, ACM, 1990 +</TITLEABBREV> <AUTHORGROUP> <AUTHOR> <FIRSTNAME>M.</FIRSTNAME> <SURNAME>Stonebraker</SURNAME> </AUTHOR> <AUTHOR> -<SURNAME>et. al.</SURNAME> +<SURNAME>et al</SURNAME> </AUTHOR> </AUTHORGROUP> <CONFGROUP> diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml new file mode 100644 index 00000000000..bdb881203f1 --- /dev/null +++ b/doc/src/sgml/config.sgml @@ -0,0 +1,270 @@ +<chapter id="config"> +<title>Configuration Options</title> + +<Sect1> +<Title>Locale Support</Title> + +<Para> +<Note> +<Para> +Written by Oleg Bartunov. +See <ULink url="http://www.sai.msu.su/~megera/postgres/">Oleg's web page</ULink> + for additional information on locale and Russian language support. + +</Para> +</Note> +While doing a project for a company in Moscow, Russia, +I encountered the problem that postgresql had no +support of national alphabets. After looking for possible workarounds +I decided to develop support of locale myself. +I'm not a C-programer but already had some experience with locale programming +when I work with perl +(debugging) and glimpse. After several days of digging through + the <ProductName>Postgres</ProductName> source tree I made very minor corections to +src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed! +I did support only for +LC_CTYPE and LC_COLLATE, but later LC_MONETARY was added by others. I got many +messages from people about this patch so I decided to send it to developers +and (to my surprise) it was +incorporated into postgresql distribution. + +<Para> + People often complain that locale doesn't work for them. +There are several common mistakes: + +<ItemizedList> +<ListItem> +<Para> + Didn't properly configure postgresql before compilation. + You must run configure with --enable-locale option to enable locale support. + Didn't setup environment correctly when starting postmaster. + You must define environment variables $LC_CTYPE and $LC_COLLATE +before running postmaster + because backend gets information about locale from environment. +I use following shell script + (runpostgres): + +<ProgramListing> + #!/bin/sh + + export LC_CTYPE=koi8-r + export LC_COLLATE=koi8-r + postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' +</ProgramListing> + + and run it from rc.local as + +<ProgramListing> + /bin/su - postgres -c "/home/postgres/runpostgres" +</ProgramListing> + +</Para> +</ListItem> +<ListItem> +<Para> + Broken locale support in OS (for example, locale support in libc +under Linux several times has changed + and this caused a lot of problems). Latest perl has also support of +locale and if locale is broken <command>perl -v</command> will + complain something like: + +<programlisting> + 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist + 8:18[mira]:~/WWW/postgres>perl -v + perl: warning: Setting locale failed. + perl: warning: Please check that your locale settings: + LC_ALL = (unset), + LC_CTYPE = "not_exist", + LANG = (unset) + are supported and installed on your system. + perl: warning: Falling back to the standard locale ("C"). +</programlisting> + +</Para> +</ListItem> +<ListItem> +<Para> + Wrong location of locale files! + + Possible locations include: +<filename>/usr/lib/locale</filename> +(Linux, Solaris), <filename>/usr/share/locale</filename> (Linux), +<filename>/usr/lib/nls/loc</filename> (DUX 4.0). + + Check <command>man locale</command> to find the correct location. +Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and + <filename>/usr/share/locale</filename> to be sure that +the next libc will not break my locale. +</Para> +</ListItem> +</ItemizedList> + +<Sect2> +<Title>What are the Benefits?</Title> + +<Para> +You can use ~* and order by operators for strings contain characters +from national alphabets. Non-english users +definitely need that. If you won't use locale stuff just undefine +the USE_LOCALE variable. + +<Sect2> +<Title>What are the Drawbacks?</Title> + +<Para> +There is one evident drawback of using locale - it's speed! +So, use locale only if you really need it. + +<Sect1> +<Title>Kerberos Authentication</Title> + +<Para> +<productname>Kerberos</productname> is an industry-standard secure authentication +system suitable for distributed computing over a public network. + +<sect2> +<title>Availability</title> + +<para> +The +<productname>Kerberos</productname> +authentication system is not distributed with <Productname>Postgres</Productname>. Versions of +<productname>Kerberos</productname> +are typically available as optional software from operating system +vendors. In addition, a source code distribution may be obtained through +<ulink url="ftp://athena-dist.mit.edu">MIT Project Athena</ulink>. + +<note> +<para> +You may wish to obtain the MIT version even if your +vendor provides a version, since some vendor ports have been +deliberately crippled or rendered non-interoperable with the MIT +version. +</note> +Users located outside the United States of America and +Canada are warned that distribution of the actual encryption code in +<productname>Kerberos</productname> +is restricted by U. S. Government export regulations. + +<para> +Inquiries regarding your <productname>Kerberos</productname> +should be directed to your vendor or +<ulink url="info-kerberos@athena.mit.edu">MIT Project Athena</ulink>. +Note that <acronym>FAQL</acronym>s +(Frequently-Asked Questions Lists) are periodically posted to the +<ulink url="mailto:kerberos@ATHENA.MIT.EDU"><productname>Kerberos</productname> mailing list</ulink> +(send +<ulink url="mailto:kerberos-request@ATHENA.MIT.EDU">mail to subscribe</ulink>), +and +<ulink url="news:comp.protocols.kerberos">USENET news group</ulink>. + +<sect2> +<title>Installation</title> + +<para> +Installation of +<productname>Kerberos</productname> +itself is covered in detail in the +<citetitle>Kerberos Installation Notes</citetitle> . +Make sure that the server key file (the <filename>srvtab</filename> +or <filename>keytab</filename>) +is somehow readable by the <productname>Postgres</productname> account. + +<para> +<Productname>Postgres</Productname> and its clients can be compiled to use +either Version 4 or Version 5 of the MIT +<productname>Kerberos</productname> +protocols by setting the +<envar>KRBVERS</envar> +variable in the file <filename>src/Makefile.global</filename> to the +appropriate value. You can also change the location where + <Productname>Postgres</Productname> +expects to find the associated libraries, header files and its own +server key file. + +<para> +After compilation is complete, <Productname>Postgres</Productname> + must be registered as a <productname>Kerberos</productname> +service. See the +<citetitle>Kerberos Operations Notes</citetitle> +and related manual pages for more details on registering services. + +<sect2> +<title>Operation</title> + +<para> +After initial installation, <Productname>Postgres</Productname> +should operate in all ways as a normal +<productname>Kerberos</productname> +service. For details on the use of authentication, see the +<citetitle>PostgreSQL User's Guide</citetitle> reference sections +for <application>postmaster</application> +and <application>psql</application>. + +<para> +In the +<productname>Kerberos</productname> +Version 5 hooks, the following assumptions are made about user +and service naming: + +<itemizedlist> +<listitem> +<para> +User principal names (anames) are assumed to +contain the actual Unix/<Productname>Postgres</Productname> user name + in the first component. + +<listitem> +<para> +The <Productname>Postgres</Productname> service is assumed to be have two components, + the service name and a hostname, canonicalized as in Version 4 (i.e., with all domain +suffixes removed). + +</itemizedlist> + +<para> +<table tocentry="1"> +<title>Kerberos Parameter Examples</title> +<titleabbrev>Kerberos</titleabbrev> + +<tgroup cols="2"> +<thead> +<row> +<entry> +Parameter +</entry> +<entry> +Example +</entry> + +<tbody> +<row> +<entry> +user +</entry> +<entry> +frew@S2K.ORG +</entry> + +<row> +<entry> +user +</entry> +<entry> +aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG +</entry> + +<row> +<entry> +host +</entry> +<entry> +postgres_dbms/ucbvax@S2K.ORG +</entry> +</tbody> +</tgroup> +</table> + +<para> +Support for Version 4 will disappear sometime after the production +release of Version 5 by MIT. diff --git a/doc/src/sgml/ecpg.sgml b/doc/src/sgml/ecpg.sgml index 98f12979e65..e460ae7e6b0 100644 --- a/doc/src/sgml/ecpg.sgml +++ b/doc/src/sgml/ecpg.sgml @@ -476,21 +476,33 @@ The following statements are not implemented thus far: <VariableList> <VarListEntry> <Term> exec sql type</Term> +<ListItem> +<Para> </VarListEntry> <VarListEntry> <Term> exec sql prepare</Term> +<ListItem> +<Para> </VarListEntry> <VarListEntry> <Term> exec sql allocate</Term> +<ListItem> +<Para> </VarListEntry> <VarListEntry> <Term> exec sql free</Term> +<ListItem> +<Para> </VarListEntry> <VarListEntry> <Term> exec sql whenever sqlwarning</Term> +<ListItem> +<Para> </VarListEntry> <VarListEntry> <Term> SQLSTATE</Term> +<ListItem> +<Para> </VarListEntry> </VariableList> </Para> diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml new file mode 100644 index 00000000000..c12ef7d6b61 --- /dev/null +++ b/doc/src/sgml/history.sgml @@ -0,0 +1,217 @@ +<Sect1> +<Title>A Short History of <ProductName>Postgres</ProductName></Title> + +<Sect2> +<Title>The Berkeley <ProductName>Postgres</ProductName> Project</Title> + +<Para> + Implementation of the <ProductName>Postgres</ProductName> +<Acronym>DBMS</Acronym> began in 1986. The + initial concepts for the system were presented in +<XRef LinkEnd="STON86" endterm="STON86-full"> + and the definition of the initial data model + appeared in +<XRef LinkEnd="ROWE87" endterm="ROWE87-full">. +The design of the rule system at + that time was described in +<XRef LinkEnd="STON87a" endterm="STON87a-full">. +The rationale + and architecture of the storage manager were detailed in +<XRef LinkEnd="STON87b" endterm="STON87b-full">. +</Para> + +<Para> +<ProductName>Postgres</ProductName> has undergone several major releases since + then. The first "demoware" system became operational + in 1987 and was shown at the 1988 <Acronym>ACM-SIGMOD</Acronym> + Conference. We released Version 1, described in +<XRef LinkEnd="STON90a" endterm="STON90a-full">, + to a few external users in June 1989. In response to a + critique of the first rule system +(<XRef LinkEnd="STON89" endterm="STON89-full">), +the rule + system was redesigned +(<XRef LinkEnd="STON90b" endterm="STON90b-full">) +and Version 2 was + released in June 1990 with the new rule system. + Version 3 appeared in 1991 and added support for multiple + storage managers, an improved query executor, and a + rewritten rewrite rule system. For the most part, + releases since then have focused on portability and + reliability. +</Para> + +<Para> +<ProductName>Postgres</ProductName> has been used to implement many different + research and production applications. These include: a + financial data analysis system, a jet engine + performance monitoring package, an asteroid tracking + database, a medical information database, and several + geographic information systems. +<ProductName>Postgres</ProductName> has also been + used as an educational tool at several universities. + Finally, +<Ulink url="http://www.illustra.com/">Illustra Information Technologies</Ulink> +(since merged into +<Ulink url="http://www.informix.com/">Informix</Ulink>) + + picked up + the code and commercialized it. + <ProductName>Postgres</ProductName> became the primary data manager + for the +<Ulink url="http://www.sdsc.edu/0/Parts_Collabs/S2K/s2k_home.html">Sequoia 2000</Ulink> + scientific computing project in late 1992. + Furthermore, the size of the external user community + nearly doubled during 1993. It became increasingly + obvious that maintenance of the prototype code and + support was taking up large amounts of time that should + have been devoted to database research. In an effort + to reduce this support burden, the project officially + ended with Version 4.2. +</Para> +</Sect2> + +<Sect2> +<Title><ProductName>Postgres95</ProductName></Title> + +<Para> +In 1994, +<ULink url="mailto:ayu@informix.com">Andrew Yu</ULink> +and +<ULink url="http://http.cs.berkeley.edu/~jolly/">Jolly Chen</ULink> +added a SQL language interpreter to <ProductName>Postgres</ProductName>, +and the code was subsequently released to +the Web to find its own way in the world. +<ProductName>Postgres95</ProductName> was a public-domain, open source descendant +of this original Berkeley code. +</Para> + +<Para> +<ProductName>Postgres95</ProductName> is a derivative of the last official release +of <ProductName>Postgres</ProductName> (version 4.2). The code is now completely + ANSI C and the code size has been trimmed by 25%. There + are a lot of internal changes that improve performance +and code maintainability. +<ProductName>Postgres95</ProductName> v1.0.x runs about 30-50% + faster on the Wisconsin Benchmark compared to v4.2. + Apart from bug fixes, these are the major enhancements: + +<ItemizedList> +<ListItem> +<Para> + The query language <ProductName>Postquel</ProductName> has been replaced with + <Acronym>SQL</Acronym> (implemented in the server). We do not yet support + subqueries (which can be imitated with user defined + <Acronym>SQL</Acronym> functions). Aggregates have been + re-implemented. We also added support for ``GROUP BY''. + The <FileName>libpq</FileName> interface is still available for <Acronym>C</Acronym> + programs. +</Para> +</ListItem> +<ListItem> +<Para> + In addition to the monitor program, we provide a new + program (<Application>psql</Application>) which supports <Acronym>GNU</Acronym> <FileName>readline</FileName>. +</Para> +</ListItem> +<ListItem> +<Para> + We added a new front-end library, <FileName>libpgtcl</FileName>, that + supports <Acronym>Tcl</Acronym>-based clients. A sample shell, + pgtclsh, provides new Tcl commands to interface <Application>tcl</Application> + programs with the <ProductName>Postgres95</ProductName> backend. +</Para> +</ListItem> +<ListItem> +<Para> + The large object interface has been overhauled. We + kept Inversion large objects as the only mechanism + for storing large objects. (This is not to be + confused with the Inversion file system which has been + removed.) +</Para> +</ListItem> +<ListItem> +<Para> + The instance-level rule system has been removed. + Rules are still available as rewrite rules. +</Para> +</ListItem> +<ListItem> +<Para> + A short tutorial introducing regular <Acronym>SQL</Acronym> features as + well as those of ours is distributed with the source + code. +</Para> +</ListItem> +<ListItem> +<Para> + <Acronym>GNU</Acronym> make (instead of <Acronym>BSD</Acronym> make) is used for the + build. Also, <ProductName>Postgres95</ProductName> can be compiled with an + unpatched <ProductName>gcc</ProductName> (data alignment of doubles has been + fixed). +</Para> +</ListItem> +</ItemizedList> +</Para> +</Sect2> + +<Sect2> +<Title><ProductName>PostgreSQL</ProductName></Title> + +<Para> +By 1996, it became clear that the name <Quote>Postgres95</Quote> would not stand +the test of time. A new name, <ProductName>PostgreSQL</ProductName>, +was chosen to reflect the +relationship between original <ProductName>Postgres</ProductName> +and the more recent +versions with <Acronym>SQL</Acronym> capability. +At the same time, the version numbering +was reset to start at 6.0, +putting the numbers back into the sequence originally begun by +the <ProductName>Postgres</ProductName> Project. + +<Para> +The emphasis on development for the v1.0.x releases of +<ProductName>Postgres95</ProductName> +was on stabilizing the backend code. +With the v6.x series of <ProductName>PostgreSQL</ProductName>, +the emphasis has shifted from +identifying and understanding existing problems in the backend +to augmenting features and capabilities, although +work continues in all areas. + +<Para> +Major enhancements include: + +<ItemizedList> +<ListItem> +<Para> +Important backend features, including subselects, defaults, +constraints, and triggers, have been implemented. +</Para> +</ListItem> +<ListItem> +<Para> +Additional <Acronym>SQL92</Acronym>-compliant language features have been added, + including primary keys, quoted identifiers, literal string type coersion, +type casting, and binary and hexadecimal integer input. +</Para> +</ListItem> +<ListItem> +<Para> +Built-in types have been improved, including new wide-range date/time types +and additional geometric type support. +</Para> +</ListItem> +<ListItem> +<Para> +Overall backend code speed has been increased by approximately 20-40%, +and backend startup time has decreased 80% since v6.0 was released. +</Para> +</ListItem> +</ItemizedList> +</Para> +</Sect2> + +</sect1>
\ No newline at end of file diff --git a/doc/src/sgml/info.sgml b/doc/src/sgml/info.sgml new file mode 100644 index 00000000000..444ed9d35b0 --- /dev/null +++ b/doc/src/sgml/info.sgml @@ -0,0 +1,146 @@ +<Sect1> +<Title>Resources</Title> + +<Para> +This manual set is organized into several parts: + +<VariableList> +<VarListEntry> +<Term>Tutorial</Term> +<ListItem> +<Para> +An introduction for new users. Does not cover advanced features. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>User's Guide</Term> +<ListItem> +<Para> +General information for users, including available commands and data types. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Programmer's Guide</Term> +<ListItem> +<Para> +Advanced information for application programmers. Topics include +type and function extensibility, library interfaces, and application design issues. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Administrator's Guide</Term> +<ListItem> +<Para> +Installation and management information. List of supported machines. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Developer's Guide</Term> +<ListItem> +<Para> +Information for <ProductName>Postgres</ProductName> developers. This is intended +for those who are contributing to the <ProductName>Postgres</ProductName> +project; application development information should appear in the Programmer's Guide. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Reference Manual</Term> +<ListItem> +<Para> +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. +</Para> +</ListItem> +</VarListEntry> +</VariableList> + +<Para> +In addition to this manual set, there are other resources to help you with +<ProductName>Postgres</ProductName> installation and use: + +<VariableList> +<VarListEntry> +<Term>man pages</Term> +<ListItem> +<Para> +The man pages have general information on command syntax. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>FAQs</Term> +<ListItem> +<Para> +The Frequently Asked Questions (FAQ) documents address both general issues +and some platform-specific issues. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>READMEs</Term> +<ListItem> +<Para> +README files are available for some contributed packages. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Web Site</Term> +<ListItem> +<Para> +The <ULink url="postgresql.org"><ProductName>Postgres</ProductName></ULink> web site has some information +not appearing in the distribution. There is a <ProductName>mhonarc</ProductName> catalog of mailing list traffic +which is a rich resource for many topics. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Mailing Lists</Term> +<ListItem> +<Para> +The <ULink url="mailto:questions@postgresql.org"><ProductName>Postgres</ProductName> Questions</ULink> +mailing list is a good place to have user questions answered. Other mailing lists are available; consult +the web page for details. +</Para> +</ListItem> +</VarListEntry> + +<VarListEntry> +<Term>Yourself!</Term> +<ListItem> +<Para> +<ProductName>Postgres</ProductName> is an open source product. +As such, it depends on the user community for +ongoing support. As you begin to use <ProductName>Postgres</ProductName>, +you will rely on others +for help, either through the documentation or through the mailing lists. +Consider contributing your +knowledge back. If you learn something which is not in the documentation, +write it up and contribute it. +If you add features to the code, contribute it. +Even those without a lot of experience can provide +corrections and minor changes in the documentation, and that is a good way to start. +The +<ULink url="mailto:docs@postgresql.org"><ProductName>Postgres</ProductName> Documentation</ULink> +mailing list is the place to get going. +</Para> +</ListItem> +</VarListEntry> +</VariableList> + +</Sect1> diff --git a/doc/src/sgml/intro-ag.sgml b/doc/src/sgml/intro-ag.sgml new file mode 100644 index 00000000000..d54187b72bb --- /dev/null +++ b/doc/src/sgml/intro-ag.sgml @@ -0,0 +1,24 @@ +<Chapter Id="intro-ag"> +<TITLE>Introduction</TITLE> + +<Para> + This document is the Administrator's Manual for the + <Ulink url="http://postgresql.org/"><ProductName>PostgreSQL</ProductName></Ulink> + database management system, originally developed at the University + of California at Berkeley. + +<ProductName>PostgreSQL</ProductName> is based on + <Ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html"> + <ProductName>Postgres release 4.2</ProductName></Ulink>. +The <ProductName>Postgres</ProductName> project, + led by Professor Michael Stonebraker, was sponsored by the + Defense Advanced Research Projects Agency (<Acronym>DARPA</Acronym>), the + Army Research Office (<Acronym>ARO</Acronym>), the National Science + Foundation (<Acronym>NSF</Acronym>), and ESL, Inc. +</Para> + +¬ation; + +&legal; + +</Chapter> diff --git a/doc/src/sgml/intro-pg.sgml b/doc/src/sgml/intro-pg.sgml index 78cf9823902..cd9b98073f9 100644 --- a/doc/src/sgml/intro-pg.sgml +++ b/doc/src/sgml/intro-pg.sgml @@ -5,7 +5,9 @@ This document is the programmer's manual for the <Ulink url="http://postgresql.org/"><ProductName>PostgreSQL</ProductName></Ulink> database management system, originally developed at the University - of California at Berkeley. <ProductName>PostgreSQL</ProductName> is based on + of California at Berkeley. + +<ProductName>PostgreSQL</ProductName> is based on <Ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html"> <ProductName>Postgres release 4.2</ProductName></Ulink>. The <ProductName>Postgres</ProductName> project, @@ -17,14 +19,17 @@ The <ProductName>Postgres</ProductName> project, <Para> The first part of this manual - explains the - <ProductName>Postgres</ProductName> approach to extensibility and describe how - users can extend <ProductName>Postgres</ProductName> by adding user-defined types, - operators, aggregates, and both query language and programming language functions. + explains the <ProductName>Postgres</ProductName> +approach to extensibility and describe how + users can extend <ProductName>Postgres</ProductName> +by adding user-defined types, + operators, aggregates, and both query language and programming +language functions. After an extremely brief overview of the <ProductName>Postgres</ProductName> rule system, we discuss the trigger and SPI interfaces. - The manual concludes with a detailed description of the programming interfaces and + The manual concludes with a detailed description of +the programming interfaces and support libraries for various languages. </Para> @@ -32,43 +37,8 @@ The <ProductName>Postgres</ProductName> project, We assume proficiency with UNIX and C programming. </Para> -<Sect1> -<Title>Copyrights and Trademarks</Title> - -<Para> -<ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8 by the PostgreSQL Global Development Group, -and is distributed under the terms of the Berkeley license. - -<Para> -<ProductName>Postgres95</ProductName> is copyright (C) 1994-5 by the Regents of the University of California. -Permission to use, copy, modify, and distribute this software and its documentation -for any purpose, without fee, and without a written agreement is hereby granted, -provided that the above copyright notice and this paragraph and the following two -paragraphs appear in all copies. -</Para> -<Para> -In no event shall the University of California be liable to -any party for direct, indirect, special, incidental, or consequential -damages, including lost profits, arising out of the use of this -software and its documentation, even if the University of California -has been advised of the possibility of such damage. -</Para> -<Para> -The University of California specifically disclaims any -warranties, including, but not limited to, the implied warranties -of merchantability and fitness for a particular purpose. -The software provided hereunder is on an "as-is" basis, and -the University of California has no obligations to provide -maintainance, support, updates, enhancements, or modifications. -</Para> +¬ation; -<Para> -<Acronym>UNIX</Acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS -and Solaris are trademarks of Sun Microsystems, Inc. DEC, -DECstation, Alpha AXP and ULTRIX are trademarks of Digital -Equipment Corp. PA-RISC and HP-UX are trademarks of -Hewlett-Packard Co. OSF/1 is a trademark of the Open -Software Foundation. -</Para> +&legal; </Chapter> diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index 45b42e43cca..b777099bcf3 100644 --- a/doc/src/sgml/intro.sgml +++ b/doc/src/sgml/intro.sgml @@ -5,11 +5,13 @@ This document is the user manual for the <Ulink url="http://postgresql.org/"><ProductName>PostgreSQL</ProductName></Ulink> database management system, originally developed at the University - of California at Berkeley. <ProductName>PostgreSQL</ProductName> is based on + of California at Berkeley. + +<ProductName>PostgreSQL</ProductName> is based on <Ulink url="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html"> <ProductName>Postgres release 4.2</ProductName></Ulink>. The <ProductName>Postgres</ProductName> project, - led by Professor Michael Stonebraker, has been sponsored by the + led by Professor Michael Stonebraker, was sponsored by the Defense Advanced Research Projects Agency (<Acronym>DARPA</Acronym>), the Army Research Office (<Acronym>ARO</Acronym>), the National Science Foundation (<Acronym>NSF</Acronym>), and ESL, Inc. @@ -65,418 +67,13 @@ it is firmly in the relational database world. In fact, some commercial database have recently incorporated features pioneered by <ProductName>Postgres</ProductName>. </Sect1> - -<Sect1> -<Title>A Short History of <ProductName>Postgres</ProductName></Title> - -<Sect2> -<Title>The Berkeley <ProductName>Postgres</ProductName> Project</Title> - -<Para> - Implementation of the <ProductName>Postgres</ProductName> <Acronym>DBMS</Acronym> began in 1986. The - initial concepts for the system were presented in -<!-- -<XRef LinkEnd="STON86"> ---> -<Citation>[STON86]</Citation> - and the definition of the initial data model - appeared in -<!-- -<XRef LinkEnd="ROWE87">. ---> -<Citation>[ROWE87]</Citation>. -The design of the rule system at - that time was described in -<!-- -<XRef LinkEnd="STON87a">. ---> -<Citation>[STON87a]</Citation>. -The rationale - and architecture of the storage manager were detailed in -<!-- -<XRef LinkEnd="STON87b">. ---> -<Citation>[STON87b]</Citation>. -</Para> - -<Para> - <ProductName>Postgres</ProductName> has undergone several major releases since - then. The first "demoware" system became operational - in 1987 and was shown at the 1988 <Acronym>ACM-SIGMOD</Acronym> - Conference. We released Version 1, described in -<!-- -<XRef LinkEnd="STON90a">, ---> -<Citation>[STON90a]</Citation>, - to a few external users in June 1989. In response to a - critique of the first rule system -<!-- -(<XRef LinkEnd="STON89">), ---> -(<Citation>[STON89]</Citation>), -the rule - system was redesigned -<!-- -(<XRef LinkEnd="STON90b">) ---> -(<Citation>[STON90b]</Citation>) -and Version 2 was - released in June 1990 with the new rule system. - Version 3 appeared in 1991 and added support for multiple - storage managers, an improved query executor, and a - rewritten rewrite rule system. For the most part, - releases since then have focused on portability and - reliability. -</Para> - -<Para> - <ProductName>Postgres</ProductName> has been used to implement many different - research and production applications. These include: a - financial data analysis system, a jet engine - performance monitoring package, an asteroid tracking - database, a medical information database, and several - geographic information systems. <ProductName>Postgres</ProductName> has also been - used as an educational tool at several universities. - Finally, <Ulink url="http://www.illustra.com/">Illustra Information Technologies</Ulink> picked up - the code and commercialized it. - <ProductName>Postgres</ProductName> became the primary data manager for the - <Ulink url="http://www.sdsc.edu/0/Parts_Collabs/S2K/s2k_home.html">Sequoia 2000</Ulink> - scientific computing project in late 1992. - Furthermore, the size of the external user community - nearly doubled during 1993. It became increasingly - obvious that maintenance of the prototype code and - support was taking up large amounts of time that should - have been devoted to database research. In an effort - to reduce this support burden, the project officially - ended with Version 4.2. -</Para> -</Sect2> - -<Sect2> -<Title><ProductName>Postgres95</ProductName></Title> - -<Para> -In 1994, -<ULink url="mailto:ayu@informix.com">Andrew Yu</ULink> -and -<ULink url="http://http.cs.berkeley.edu/~jolly/">Jolly Chen</ULink> -added a SQL language interpreter to <ProductName>Postgres</ProductName>, and the code was subsequently released to -the Web to find its own way in the world. <ProductName>Postgres95</ProductName> was a public-domain, open source descendant -of this original Berkeley code. -</Para> - -<Para> - <ProductName>Postgres95</ProductName> is a derivative of the last official release - of <ProductName>Postgres</ProductName> (version 4.2). The code is now completely - ANSI C and the code size has been trimmed by 25%. There - are a lot of internal changes that improve performance - and code maintainability. <ProductName>Postgres95</ProductName> v1.0.x runs about 30-50% - faster on the Wisconsin Benchmark compared to v4.2. - Apart from bug fixes, these are the major enhancements: - -<ItemizedList> -<ListItem> -<Para> - The query language <ProductName>Postquel</ProductName> has been replaced with - <Acronym>SQL</Acronym> (implemented in the server). We do not yet support - subqueries (which can be imitated with user defined - <Acronym>SQL</Acronym> functions). Aggregates have been - re-implemented. We also added support for ``GROUP BY''. - The <FileName>libpq</FileName> interface is still available for <Acronym>C</Acronym> - programs. -</Para> -</ListItem> -<ListItem> -<Para> - In addition to the monitor program, we provide a new - program (<Application>psql</Application>) which supports <Acronym>GNU</Acronym> <FileName>readline</FileName>. -</Para> -</ListItem> -<ListItem> -<Para> - We added a new front-end library, <FileName>libpgtcl</FileName>, that - supports <Acronym>Tcl</Acronym>-based clients. A sample shell, - pgtclsh, provides new Tcl commands to interface <Application>tcl</Application> - programs with the <ProductName>Postgres95</ProductName> backend. -</Para> -</ListItem> -<ListItem> -<Para> - The large object interface has been overhauled. We - kept Inversion large objects as the only mechanism - for storing large objects. (This is not to be - confused with the Inversion file system which has been - removed.) -</Para> -</ListItem> -<ListItem> -<Para> - The instance-level rule system has been removed. - Rules are still available as rewrite rules. -</Para> -</ListItem> -<ListItem> -<Para> - A short tutorial introducing regular <Acronym>SQL</Acronym> features as - well as those of ours is distributed with the source - code. -</Para> -</ListItem> -<ListItem> -<Para> - <Acronym>GNU</Acronym> make (instead of <Acronym>BSD</Acronym> make) is used for the - build. Also, <ProductName>Postgres95</ProductName> can be compiled with an - unpatched <ProductName>gcc</ProductName> (data alignment of doubles has been - fixed). -</Para> -</ListItem> -</ItemizedList> -</Para> -</Sect2> - -<Sect2> -<Title><ProductName>PostgreSQL</ProductName></Title> - -<Para> -By 1996, it became clear that the name <Quote>Postgres95</Quote> would not stand -the test of time. A new name, <ProductName>PostgreSQL</ProductName>, was chosen to reflect the -relationship between original <ProductName>Postgres</ProductName> and the more recent -versions with <Acronym>SQL</Acronym> capability. At the same time, the version numbering -was reset to start at 6.0, putting the numbers back into the sequence originally begun by -the <ProductName>Postgres</ProductName> Project. - -<Para> -The emphasis on development for the v1.0.x releases of <ProductName>Postgres95</ProductName> -was on stabilizing the backend code. -With the v6.x series of <ProductName>PostgreSQL</ProductName>, the emphasis has shifted from -identifying and understanding existing problems in the backend to augmenting features and capabilities, although -work continues in all areas. - -<Para> -Major enhancements include: - -<ItemizedList> -<ListItem> -<Para> -Important backend features, including subselects, defaults, constraints, and triggers, have been implemented. -</Para> -</ListItem> -<ListItem> -<Para> -Additional <Acronym>SQL92</Acronym>-compliant language features have been added, - including primary keys, quoted identifiers, literal string type coersion, type casting, - and binary and hexadecimal integer input. -</Para> -</ListItem> -<ListItem> -<Para> -Built-in types have been improved, including new wide-range date/time types and additional geometric type support. -</Para> -</ListItem> -<ListItem> -<Para> -Overall backend code speed has been increased by approximately 20%, and backend startup time has decreased 80%. -</Para> -</ListItem> -</ItemizedList> -</Para> -</Sect2> - -<Sect1> -<Title>About This Release</Title> - -<Para> - From now on, We will use <ProductName>Postgres</ProductName> to mean <ProductName>PostgreSQL</ProductName>. - -<Para> - <ProductName>PostgreSQL</ProductName> is available without cost. This manual - describes version 6.3 of <ProductName>PostgreSQL</ProductName>. - -<Para> -Check the Administrator's Guide for a list of currently supported machines. In general, -<ProductName>PostgreSQL</ProductName> is portable to any Unix/Posix-compatible system -with full libc library support. - -</Sect1> -<Sect1> -<Title>Resources</Title> +&history; -<Para> -This manual set is organized into several parts: +&about; -<VariableList> -<VarListEntry> -<Term>Tutorial</Term> -<ListItem> -<Para> -An introduction for new users. Does not cover advanced features. -</Para> -</ListItem> -</VarListEntry> +&info; -<VarListEntry> -<Term>User's Guide</Term> -<ListItem> -<Para> -General information for users, including available commands and data types. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Programmer's Guide</Term> -<ListItem> -<Para> -Advanced information for application programmers. Topics include -type and function extensibility, library interfaces, and application design issues. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Administrator's Guide</Term> -<ListItem> -<Para> -Installation and management information. List of supported machines. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Developer's Guide</Term> -<ListItem> -<Para> -Information for <ProductName>Postgres</ProductName> developers. This is intended -for those who are contributing to the <ProductName>Postgres</ProductName> -project; application development information should appear in the Programmer's Guide. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Reference Manual</Term> -<ListItem> -<Para> -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. -</Para> -</ListItem> -</VarListEntry> -</VariableList> - -<Para> -In addition to this manual set, there are other resources to help you with -<ProductName>Postgres</ProductName> installation and use: - -<VariableList> -<VarListEntry> -<Term>man pages</Term> -<ListItem> -<Para> -The man pages have general information on command syntax. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>FAQs</Term> -<ListItem> -<Para> -The Frequently Asked Questions (FAQ) documents address both general issues -and some platform-specific issues. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>READMEs</Term> -<ListItem> -<Para> -README files are available for some contributed packages. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Web Site</Term> -<ListItem> -<Para> -The <ULink url="postgresql.org"><ProductName>Postgres</ProductName></ULink> web site has some information -not appearing in the distribution. There is a <ProductName>mhonarc</ProductName> catalog of mailing list traffic -which is a rich resource for many topics. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Mailing Lists</Term> -<ListItem> -<Para> -The <ULink url="mailto:questions@postgresql.org"><ProductName>Postgres</ProductName> Questions</ULink> -mailing list is a good place to have user questions answered. Other mailing lists are available; consult -the web page for details. -</Para> -</ListItem> -</VarListEntry> - -<VarListEntry> -<Term>Yourself!</Term> -<ListItem> -<Para> -<ProductName>Postgres</ProductName> is an open source product. As such, it depends on the user community for -ongoing support. As you begin to use <ProductName>Postgres</ProductName>, you will rely on others -for help, either through the documentation or through the mailing lists. Consider contributing your -knowledge back. If you learn something which is not in the documentation, write it up and contribute it. -If you add features to the code, contribute it. Even those without a lot of experience can provide -corrections and minor changes in the documentation, and that is a good way to start. -The <ULink url="mailto:docs@postgresql.org"><ProductName>Postgres</ProductName> Documentation</ULink> -mailing list is the place to get going. -</Para> -</ListItem> -</VarListEntry> -</VariableList> - -</Sect1> - -<Sect1> -<Title>Copyrights and Trademarks</Title> - -<Para> -<ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8 by the PostgreSQL Global Development Group, -and is distributed under the terms of the Berkeley license. - -<Para> -<ProductName>Postgres95</ProductName> is copyright (C) 1994-5 by the Regents of the University of California. -Permission to use, copy, modify, and distribute this software and its documentation -for any purpose, without fee, and without a written agreement is hereby granted, -provided that the above copyright notice and this paragraph and the following two -paragraphs appear in all copies. -</Para> -<Para> -In no event shall the University of California be liable to -any party for direct, indirect, special, incidental, or consequential -damages, including lost profits, arising out of the use of this -software and its documentation, even if the University of California -has been advised of the possibility of such damage. -</Para> -<Para> -The University of California specifically disclaims any -warranties, including, but not limited to, the implied warranties -of merchantability and fitness for a particular purpose. -The software provided hereunder is on an "as-is" basis, and -the University of California has no obligations to provide -maintainance, support, updates, enhancements, or modifications. -</Para> - -<Para> -<Acronym>UNIX</Acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS -and Solaris are trademarks of Sun Microsystems, Inc. DEC, -DECstation, Alpha AXP and ULTRIX are trademarks of Digital -Equipment Corp. PA-RISC and HP-UX are trademarks of -Hewlett-Packard Co. OSF/1 is a trademark of the Open -Software Foundation. -</Para> +&legal; </Chapter> diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml new file mode 100644 index 00000000000..bf347ca90ca --- /dev/null +++ b/doc/src/sgml/legal.sgml @@ -0,0 +1,40 @@ +<Sect1> +<Title>Copyrights and Trademarks</Title> + +<Para> +<ProductName>PostgreSQL</ProductName> is copyright (C) 1996-8 +by the PostgreSQL Global Development Group, +and is distributed under the terms of the Berkeley license. + +<Para> +<ProductName>Postgres95</ProductName> is copyright (C) 1994-5 +by the Regents of the University of California. +Permission to use, copy, modify, and distribute this software and its documentation +for any purpose, without fee, and without a written agreement is hereby granted, +provided that the above copyright notice and this paragraph and the following two +paragraphs appear in all copies. +</Para> +<Para> +In no event shall the University of California be liable to +any party for direct, indirect, special, incidental, or consequential +damages, including lost profits, arising out of the use of this +software and its documentation, even if the University of California +has been advised of the possibility of such damage. +</Para> +<Para> +The University of California specifically disclaims any +warranties, including, but not limited to, the implied warranties +of merchantability and fitness for a particular purpose. +The software provided hereunder is on an "as-is" basis, and +the University of California has no obligations to provide +maintainance, support, updates, enhancements, or modifications. +</Para> + +<Para> +<Acronym>UNIX</Acronym> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS +and Solaris are trademarks of Sun Microsystems, Inc. DEC, +DECstation, Alpha AXP and ULTRIX are trademarks of Digital +Equipment Corp. PA-RISC and HP-UX are trademarks of +Hewlett-Packard Co. OSF/1 is a trademark of the Open +Software Foundation. +</Para> diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml new file mode 100644 index 00000000000..f31a9c08583 --- /dev/null +++ b/doc/src/sgml/notation.sgml @@ -0,0 +1,73 @@ +<sect1> +<title>Terminology</title> + +<para> +In the following documentation, +<firstterm>site</firstterm> +may be interpreted as the host machine on which +<Productname>Postgres</Productname> is installed. +Since it is possible to install more than one set of +<Productname>Postgres</Productname> +databases on a single host, this term more precisely denotes any +particular set of installed +<Productname>Postgres</Productname> binaries and databases. + +<para> +The +<Productname>Postgres</Productname> <firstterm>super-user</firstterm> +is the user named <replaceable>postgres</replaceable> + who owns the <Productname>Postgres</Productname> +binaries and database files. As the database super-user, all +protection mechanisms may be bypassed and any data accessed +arbitrarily. +In addition, the <Productname>Postgres</Productname> super-user is allowed to execute +some support programs which are generally not available to all users. +Note that the <Productname>Postgres</Productname> super-user is +<emphasis>not</emphasis> +the same as the Unix super-user (<literal>root</literal>), +and should have a non-zero userid for security reasons. + +<para> +The +<firstterm>database base administrator</firstterm> +or <acronym>DBA</acronym>, is the person who is responsible for installing +<Productname>Postgres</Productname> with mechanisms to +enforce a security policy for a site. The DBA can add new users by +the method described below +and maintain a set of template databases for use by +<application>createdb</application>. + +<para> +The <application>postmaster</application> +is the process that acts as a clearing-house for requests +to the <Productname>Postgres</Productname> system. +Frontend applications connect to the <application>postmaster</application>, +which keeps tracks of any system errors and communication between the +backend processes. The <application>postmaster</application> +can take several command-line arguments to tune its behavior. +However, supplying arguments is necessary only if you intend to run multiple +sites or a non-default site. + +<para> +The <Productname>Postgres</Productname> backend +(the actual executable program <application>postgres</application>) may be executed +directly from the user shell by the +<Productname>Postgres</Productname> super-user +(with the database name as an argument). However, +doing this bypasses the shared buffer pool and lock table associated +with a postmaster/site, therefore this is not recommended in a multiuser +site. + +<sect1> +<title>Notation</title> + +<para> +<quote>...</quote> at the front of a file name is used to represent the +path to the <Productname>Postgres</Productname> super-user's home directory. +Anything in brackets +<quote>[</quote> and <quote>]</quote>) is optional. Anything in braces +(<quote>{</quote> and <quote>}</quote>) can be repeated 0 or more times. +Parentheses (<quote>(</quote> and <quote>)</quote>) are used to group boolean +expressions. <quote>|</quote> is the boolean operator OR. + +</sect1>
\ No newline at end of file diff --git a/doc/src/sgml/odbc.sgml b/doc/src/sgml/odbc.sgml index 2767b00fbce..4ecc1d40f63 100644 --- a/doc/src/sgml/odbc.sgml +++ b/doc/src/sgml/odbc.sgml @@ -13,7 +13,7 @@ <Date>1998-08-25</Date> </DocInfo> -<Title><acronym>ODBC</acronym> Interface</Title> +<Title>ODBC Interface</Title> <Para> <Note> diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml index 663d65e6b02..1cff4ca9044 100644 --- a/doc/src/sgml/oper.sgml +++ b/doc/src/sgml/oper.sgml @@ -30,6 +30,200 @@ oprleft|oprright|oprresult|oprcode </Para> <sect1> +<title>Lexical Precedence</title> + +<para> +Operators have a precedence which is currently hardcoded into the parser. +Most operators have the same precedence and are non-associative. This may lead +to non-intuitive behavior; for example the boolean operators "<" and ">" +have a different precedence that the boolean operators "<=" and ">=". + +<table tocentry="1"> +<title> +Operator Ordering (decreasing precedence) +</title> + +<tgroup cols="2"> +<thead> +<row> +<entry> +Element +<entry> +Precedence +<entry> +Description +</thead> + +<tbody> +<row> +<entry> +UNION +<entry> +left +<entry> +SQL select construct +<row> +<entry> +:: +<entry> +<entry> +<productname>Postgres</productname> typecasting + +<row> +<entry> +[ ] +<entry> +left +<entry> +array delimiters + +<row> +<entry> +. +<entry> +left +<entry> +table/column delimiter + +<row> +<entry> +- +<entry> +right +<entry> +unary minus + +<row> +<entry> +; +<entry> +left +<entry> +statement termination, logarithm + +<row> +<entry> +: +<entry> +right +<entry> +exponentiation + +<row> +<entry> +| +<entry> +left +<entry> +start of interval + +<row> +<entry> +* / +<entry> +left +<entry> +multiplication, division + +<row> +<entry> ++ - +<entry> +left +<entry> +addition, subtraction + +<row> +<entry> +IS +<entry> +<entry> +test for TRUE, FALSE, NULL +<row> +<entry> +ISNULL +<entry> +<entry> +test for NULL + +<row> +<entry> +NOTNULL +<entry> +<entry> +test for NOT NULL + +<row> +<entry> +(all other operators) +<entry> +<entry> +native and user-defined + +<row> +<entry> +IN +<entry> +<entry> +set membership + +<row> +<entry> +BETWEEN +<entry> +<entry> +containment + +<row> +<entry> +LIKE +<entry> +<entry> +string pattern matching + +<row> +<entry> +< > +<entry> +<entry> +boolean inequality + +<row> +<entry> += +<entry> +right +<entry> +equality + +<row> +<entry> +NOT +<entry> +right +<entry> +negation + +<row> +<entry> +AND +<entry> +left +<entry> +logical intersection + +<row> +<entry> +OR +<entry> +left +<entry> +logical union + +</tbody> +</table> + +<sect1> <title>General Operators</title> <para> diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index a1a847c8768..4a7a6cc086e 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,10 +1,19 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.8 1998/08/17 16:20:33 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.9 1998/09/30 05:41:49 thomas Exp $ + Postgres integrated documentation. Other subset docs should be copied and shrunk from here. thomas 1998-02-23 $Log: postgres.sgml,v $ +Revision 1.9 1998/09/30 05:41:49 thomas +Clean up pages. Add information for operator precedence. +Split introduction sections into separate files to allow the legal notice + and notation sections appear in all documents without having the history + show up everplace too. +Add full list of reserved and non-reserved key words in syntax.sgml. +Add a separate chapter to the admin guide on security. + Revision 1.8 1998/08/17 16:20:33 thomas Move SQL reference pages up into the User's Guide. @@ -15,6 +24,12 @@ Include new chapters. <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> + <!-- tutorial --> <!entity intro SYSTEM "intro.sgml"> <!entity arch SYSTEM "arch.sgml"> @@ -42,8 +57,10 @@ Include new chapters. %allfiles; <!-- administrator's guide --> +<!entity intro-ag SYSTEM "intro-ag.sgml"> <!entity start-ag SYSTEM "start-ag.sgml"> <!entity install SYSTEM "install.sgml"> +<!entity runtime SYSTEM "runtime.sgml"> <!entity recovery SYSTEM "recovery.sgml"> <!entity regress SYSTEM "regress.sgml"> <!entity ports SYSTEM "ports.sgml"> @@ -195,6 +212,7 @@ Information for users. Installation and maintenance information. </Para> </PartIntro> +&intro-ag; &ports; &install; &start-ag; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index 5403a95d636..2a5b1c782a5 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,12 +1,22 @@ -<!-- programmer.sgml -- -- Postgres programmer's guide. -- Derived from postgres.sgml. -- thomas 1998-02-24 -- -- --> +<!-- +$header$ + +Postgres programmer's guide. +Derived from postgres.sgml. +thomas 1998-02-24 + +$log$ + +--> + <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ -<!entity intro SYSTEM "intro.sgml"> + +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> + <!entity arch SYSTEM "arch.sgml"> <!entity start SYSTEM "start.sgml"> <!entity query SYSTEM "query.sgml"> @@ -60,7 +70,7 @@ <!entity biblio SYSTEM "biblio.sgml"> <!entity contacts SYSTEM "contacts.sgml"> ]> -<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc --> + <Book Id="programmer"> <!-- Title information --> @@ -95,7 +105,8 @@ <LegalNotice> <Para> -<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 by the Postgres Global Development Group. +<ProductName>PostgreSQL</ProductName> is copyright (C) 1998 +by the Postgres Global Development Group. </Para> </LegalNotice> diff --git a/doc/src/sgml/query-ug.sgml b/doc/src/sgml/query-ug.sgml index 6d4112ce2bd..2b3a3c56217 100644 --- a/doc/src/sgml/query-ug.sgml +++ b/doc/src/sgml/query-ug.sgml @@ -4,7 +4,8 @@ <Para> <Note> <Para> -This chapter must go into depth on each area of the query language. Currently a copy of the tutorial. +This chapter must go into depth on each area of the query language. +Currently a copy of the tutorial. - thomas 1998-01-12 </Para> </Note> @@ -15,32 +16,38 @@ This chapter must go into depth on each area of the query language. Currently a <Acronym>SQL3</Acronym>. It has many extensions such as an extensible type system, inheritance, functions and production rules. Those are - features carried over from the original <ProductName>Postgres</ProductName> query - language, <ProductName>PostQuel</ProductName>. This section provides an overview - of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> to perform simple operations. + features carried over from the original <ProductName>Postgres</ProductName> +query + language, <ProductName>PostQuel</ProductName>. +This section provides an overview + of how to use <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> + to perform simple operations. This manual is only intended to give you an idea of our flavor of <Acronym>SQL</Acronym> and is in no way a complete tutorial on <Acronym>SQL</Acronym>. Numerous books have been written on <Acronym>SQL</Acronym>. For - instance, consult <Ulink url="refs.html#MELT93">[MELT93]</ULink> or - <Ulink url="refs.html#DATE93">[DATE93]</ULink>. You should also - be aware that some features are not part of the <Acronym>ANSI</Acronym> - standard. + instance, consult <xref linkend="MELT93" endterm="MELT93-full"> or + <xref linkend="DATE97" endterm="DATE97-full">. You should also + be aware that some features of <ProductName>Postgres</ProductName> +are not part of the <Acronym>ANSI</Acronym> standard. </Para> <Sect1> <Title>Concepts</Title> <Para> - The fundamental notion in <ProductName>Postgres</ProductName> is that of a class, + The fundamental notion in <ProductName>Postgres</ProductName> +is that of a class, which is a named collection of object instances. Each instance has the same collection of named attributes, and each attribute is of a specific type. Furthermore, - each instance has a permanent <FirstTerm>object identifier</FirstTerm> (<Acronym>OID</Acronym>) + each instance has a permanent <FirstTerm>object +identifier</FirstTerm> (<Acronym>OID</Acronym>) that is unique throughout the installation. Because <Acronym>SQL</Acronym> syntax refers to tables, we will use the terms <FirstTerm>table</FirstTerm> and <FirstTerm>class</FirstTerm> interchangeably. Likewise, an <Acronym>SQL</Acronym> <FirstTerm>row</FirstTerm> is an - <FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> <FirstTerm>columns</FirstTerm> + <FirstTerm>instance</FirstTerm> and <Acronym>SQL</Acronym> +<FirstTerm>columns</FirstTerm> are <FirstTerm>attributes</FirstTerm>. As previously discussed, classes are grouped into databases, and a collection of databases managed by a diff --git a/doc/src/sgml/runtime.sgml b/doc/src/sgml/runtime.sgml new file mode 100644 index 00000000000..f699088119c --- /dev/null +++ b/doc/src/sgml/runtime.sgml @@ -0,0 +1,90 @@ +<Chapter Id="runtime"> +<Title>Runtime Environment</Title> + +<Para> +This chapter outlines the interaction between <Productname>Postgres</Productname> and +the operating system. + +<sect1> +<title>Using <Productname>Postgres</Productname> from Unix</title> + +<para> +All <Productname>Postgres</Productname> commands that are executed +directly from a Unix shell are +found in the directory <quote>.../bin</quote>. Including this directory in +your search path will make executing the commands easier. + +<para> +A collection of system catalogs exist at each site. These include a +class (<literal>pg_user</literal>) that contains an instance for each valid +<Productname>Postgres</Productname> user. The instance specifies a set of + <Productname>Postgres</Productname> privileges, such as +the ability to act as <Productname>Postgres</Productname> super-user, + the ability to create/destroy +databases, and the ability to update the system catalogs. A Unix +user cannot do anything with <Productname>Postgres</Productname> +until an appropriate instance is +installed in this class. Further information on the system catalogs +is available by running queries on the appropriate classes. + +<chapter id="layout"> +<Title>System Layout</Title> + +<Para> +<Figure Id="ADMIN-LAYOUT"> +<Title><ProductName>Postgres</ProductName> file layout</Title> +<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic> +</Figure> + +<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT"> +shows how the <ProductName>Postgres</ProductName> distribution is laid + out when installed in the default way. For simplicity, + we will assume that <ProductName>Postgres</ProductName> + has been installed in the + directory <filename>/usr/local/pgsql</filename>. Therefore, wherever + you see the directory <filename>/usr/local/pgsql</filename> you should + substitute the name of the directory where + <ProductName>Postgres</ProductName> is + actually installed. + All <ProductName>Postgres</ProductName> commands are installed + in the directory + <filename>/usr/local/pgsql/bin</filename>. Therefore, you should add + this directory to your shell command path. If you use + a variant of the Berkeley C shell, such as csh or tcsh, + you would add +<ProgramListing> +set path = ( /usr/local/pgsql/bin path ) +</ProgramListing> + in the .login file in your home directory. If you use + a variant of the Bourne shell, such as sh, ksh, or + bash, then you would add +<ProgramListing> +PATH=/usr/local/pgsql/bin PATH +export PATH +</ProgramListing> + to the .profile file in your home directory. + From now on, we will assume that you have added the + <ProductName>Postgres</ProductName> bin directory to your path. + In addition, we + will make frequent reference to "setting a shell + variable" or "setting an environment variable" throughout + this document. If you did not fully understand the + last paragraph on modifying your search path, you + should consult the UNIX manual pages that describe your + shell before going any further. +</Para> + +<Para> +If you have not set things up in the +default way, you may have some more work to do. +For example, if the database server machine is a remote machine, you +will need to set the <envar>PGHOST</envar> environment variable to the name +of the database server machine. The environment variable +<envar>PGPORT</envar> may also have to be set. The bottom line is this: if +you try to start an application program and it complains +that it cannot connect to the <Application>postmaster</Application>, +you must go back and make sure that your +environment is properly set up. +</Para> + +</Chapter> diff --git a/doc/src/sgml/security.sgml b/doc/src/sgml/security.sgml new file mode 100644 index 00000000000..39a4abdf607 --- /dev/null +++ b/doc/src/sgml/security.sgml @@ -0,0 +1,155 @@ +<chapter id="security"> +<Title>Security</Title> + +<Para> + +<Sect1> +<Title>User Authentication</Title> + +<Para> +<firstterm>Authentication</firstterm> +is the process by which the backend server and +<application>postmaster</application> +ensure that the user requesting access to data is in fact who he/she +claims to be. +All users who invoke <Productname>Postgres</Productname> are checked against the +contents of the <literal>pg_user</literal> class to ensure that they are +authorized to do so. However, verification of the user's actual +identity is performed in a variety of ways: + +<variablelist> +<varlistentry> +<term> +From the user shell +</term> +<listitem> +<para> +A backend server started from a user shell notes the user's (effective) +user-id before performing a +<function>setuid</function> +to the user-id of user <replaceable>postgres</replaceable>. +The effective user-id is used +as the basis for access control checks. No other authentication is +conducted. + +<varlistentry> +<term> +From the network +</term> +<listitem> +<para> +If the <Productname>Postgres</Productname> system is built as distributed, + access to the Internet TCP port of the +<application>postmaster</application> +process is available to anyone. The DBA configures the pg_hba.conf file +in the PGDATA directory to specify what authentication system is to be used +according to the host making the connection and which database it is +connecting to. See <citetitle>pg_hba.conf(5)</citetitle> + for a description of the authentication +systems available. Of course, host-based authentication is not fool-proof in +Unix, either. It is possible for determined intruders to also +masquerade the origination host. Those security issues are beyond the +scope of <Productname>Postgres</Productname>. + +</variablelist> + + +<Sect1> +<Title>Access Control</Title> + +<Para> +<Productname>Postgres</Productname> provides mechanisms to allow users +to limit the access to their data that is provided to other users. + +<variablelist> +<varlistentry> +<term> +Database superusers +</term> +<listitem> +<para> +Database super-users (i.e., users who have <literal>pg_user.usesuper</literal> +set) silently bypass all of the access controls described below with +two exceptions: manual system catalog updates are not permitted if the +user does not have <literal>pg_user.usecatupd</literal> set, and destruction of +system catalogs (or modification of their schemas) is never allowed. + +<varlistentry> +<term> +Access Privilege +</term> +<listitem> +<para> +The use of access privilege to limit reading, writing and setting +of rules on classes is covered in +<citetitle>grant/revoke(l)</citetitle>. + +<varlistentry> +<term> +Class removal and schema modification +</term> +<listitem> +<para> +Commands that destroy or modify the structure of an existing class, +such as <command>alter</command>, +<command>drop table</command>, +and +<command>drop index</command>, +only operate for the owner of the class. As mentioned above, these +operations are <emphasis>never</emphasis> +permitted on system catalogs. + +</variablelist> + +<Sect1> +<Title>Functions and Rules</Title> + +<Para> +Functions and rules allow users to insert code into the backend server +that other users may execute without knowing it. Hence, both +mechanisms permit users to <firstterm>trojan horse</firstterm> +others with relative impunity. The only real protection is tight +control over who can define functions (e.g., write to relations with +SQL fields) and rules. Audit trails and alerters on +<literal>pg_class</literal>, <literal>pg_user</literal> + and <literal>pg_group</literal> are also recommended. + +<Sect2> +<Title>Functions</Title> + +<Para> +Functions written in any language except SQL +run inside the backend server +process with the permissions of the user <replaceable>postgres</replaceable> (the +backend server runs with its real and effective user-id set to +<replaceable>postgres</replaceable>. It is possible for users to change the server's +internal data structures from inside of trusted functions. Hence, +among many other things, such functions can circumvent any system +access controls. This is an inherent problem with user-defined C functions. + +<Sect2> +<Title>Rules</Title> + +<Para> +Like SQL functions, rules always run with the identity and +permissions of the user who invoked the backend server. + +<sect2> +<title> +Caveats +</title> + +<para> +There are no plans to explicitly support encrypted data inside of +<Productname>Postgres</Productname> +(though there is nothing to prevent users from encrypting +data within user-defined functions). There are no plans to explicitly +support encrypted network connections, either, pending a total rewrite +of the frontend/backend protocol. +<para> +User names, group names and associated system identifiers (e.g., the +contents of <literal>pg_user.usesysid</literal>) are assumed to be unique +throughout a database. Unpredictable results may occur if they are +not. + +</chapter>
\ No newline at end of file diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index da97428bbe6..49c37a3a8cc 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -4,167 +4,17 @@ - - thomas 1998-02-24 --> -<Chapter Id="start-ag"> -<Title>Runtime Environment</Title> - -<Para> -<Figure Id="ADMIN-LAYOUT"> -<Title><ProductName>Postgres</ProductName> file layout</Title> -<Graphic Align="center" FileRef="layout.gif" Format="GIF"></Graphic> -</Figure> - -<XRef LinkEnd="ADMIN-LAYOUT" EndTerm="ADMIN-LAYOUT"> -shows how the <ProductName>Postgres</ProductName> distribution is laid - out when installed in the default way. For simplicity, - we will assume that <ProductName>Postgres</ProductName> has been installed in the - directory <filename>/usr/local/pgsql</filename>. Therefore, wherever - you see the directory <filename>/usr/local/pgsql</filename> you should - substitute the name of the directory where <ProductName>Postgres</ProductName> is - actually installed. - All <ProductName>Postgres</ProductName> commands are installed in the directory - <filename>/usr/local/pgsql/bin</filename>. Therefore, you should add - this directory to your shell command path. If you use - a variant of the Berkeley C shell, such as csh or tcsh, - you would add -<ProgramListing> -set path = ( /usr/local/pgsql/bin path ) -</ProgramListing> - in the .login file in your home directory. If you use - a variant of the Bourne shell, such as sh, ksh, or - bash, then you would add -<ProgramListing> -PATH=/usr/local/pgsql/bin PATH -export PATH -</ProgramListing> - to the .profile file in your home directory. - From now on, we will assume that you have added the - <ProductName>Postgres</ProductName> bin directory to your path. In addition, we - will make frequent reference to "setting a shell - variable" or "setting an environment variable" throughout - this document. If you did not fully understand the - last paragraph on modifying your search path, you - should consult the UNIX manual pages that describe your - shell before going any further. -</Para> - -<Para> -If your site administrator has not set things up in the -default way, you may have some more work to do. For example, if the database server machine is a remote machine, you -will need to set the <Acronym>PGHOST</Acronym> environment variable to the name -of the database server machine. The environment variable -<Acronym>PGPORT</Acronym> may also have to be set. The bottom line is this: if -you try to start an application program and it complains -that it cannot connect to the <Application>postmaster</Application>, you should immediately consult your site administrator to make sure that your -environment is properly set up. -</Para> - -<Sect1> -<Title>Locale Support</Title> - -<Para> -<Note> -<Para> -Written by Oleg Bartunov. -See <ULink url="http://www.sai.msu.su/~megera/postgres/">Oleg's web page</ULink> - for additional information on locale and Russian language support. - -</Para> -</Note> -While doing a project for a company in Moscow, Russia, I encountered the problem that postgresql had no -support of national alphabets. After looking for possible workarounds I decided to develop support of locale myself. -I'm not a C-programer but already had some experience with locale programming when I work with perl -(debugging) and glimpse. After several days of digging through - the <ProductName>Postgres</ProductName> source tree I made very minor corections to -src/backend/utils/adt/varlena.c and src/backend/main/main.c and got what I needed! I did support only for -LC_CTYPE and LC_COLLATE, but later LC_MONETARY was added by others. I got many -messages from people about this patch so I decided to send it to developers and (to my surprise) it was -incorporated into postgresql distribution. - -<Para> - People often complain that locale doesn't work for them. There are several common mistakes: - -<ItemizedList> -<ListItem> -<Para> - Didn't properly configure postgresql before compilation. - You must run configure with --enable-locale option to enable locale support. - Didn't setup environment correctly when starting postmaster. - You must define environment variables $LC_CTYPE and $LC_COLLATE before running postmaster - because backend gets information about locale from environment. I use following shell script - (runpostgres): - -<ProgramListing> - #!/bin/sh - - export LC_CTYPE=koi8-r - export LC_COLLATE=koi8-r - postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' -</ProgramListing> - - and run it from rc.local as - -<ProgramListing> - /bin/su - postgres -c "/home/postgres/runpostgres" -</ProgramListing> - -</Para> -</ListItem> -<ListItem> -<Para> - Broken locale support in OS (for example, locale support in libc under Linux several times has changed - and this caused a lot of problems). Latest perl has also support of locale and if locale is broken perl -v will - complain something like: - -<programlisting> - 8:17[mira]:~/WWW/postgres>setenv LC_CTYPE not_exist - 8:18[mira]:~/WWW/postgres>perl -v - perl: warning: Setting locale failed. - perl: warning: Please check that your locale settings: - LC_ALL = (unset), - LC_CTYPE = "not_exist", - LANG = (unset) - are supported and installed on your system. - perl: warning: Falling back to the standard locale ("C"). -</programlisting> - -</Para> -</ListItem> -<ListItem> -<Para> - Wrong location of locale files! - - Possible locations include: <filename>/usr/lib/locale</filename> (Linux, Solaris), <filename>/usr/share/locale</filename> (Linux), <filename>/usr/lib/nls/loc</filename> (DUX 4.0) - Check <command>man locale</command> to find the correct location. -Under Linux I did a symbolic link between <filename>/usr/lib/locale</filename> and - <filename>/usr/share/locale</filename> to be sure that the next libc will not break my locale. -</Para> -</ListItem> -</ItemizedList> - -<Sect2> -<Title>What are the Benefits?</Title> - -<Para> -You can use ~* and order by operators for strings contain characters from national alphabets. Non-english users -definitely need that. If you won't use locale stuff just undefine the USE_LOCALE variable. - -<Sect2> -<Title>What are the Drawbacks?</Title> - -<Para> -There is one evident drawback of using locale - it's speed! So, use locale only if you really need it. - -</Chapter> - <Chapter Id="postmaster"> <Title>Starting <Application>postmaster</Application></Title> <Para> - Nothing can happen to a database unless the <Application>postmaster</Application> + Nothing can happen to a database unless the + <Application>postmaster</Application> process is running. As the site administrator, there are a number of things you should remember before - starting the <Application>postmaster</Application>. These are discussed in the - section of this manual titled, "Administering Postgres." + starting the <Application>postmaster</Application>. +These are discussed in the installation and configuration sections +of this manual. However, if <ProductName>Postgres</ProductName> has been installed by following the installation instructions exactly as written, the following simple command is all you should @@ -172,9 +22,11 @@ There is one evident drawback of using locale - it's speed! So, use locale only <ProgramListing> % postmaster </ProgramListing> - The <Application>postmaster</Application> occasionally prints out messages which + The <Application>postmaster</Application> occasionally prints out +messages which are often helpful during troubleshooting. If you wish - to view debugging messages from the <Application>postmaster</Application>, you can + to view debugging messages from the <Application>postmaster</Application>, +you can start it with the -d option and redirect the output to the log file: <ProgramListing> @@ -184,7 +36,8 @@ There is one evident drawback of using locale - it's speed! So, use locale only <ProgramListing> % postmaster -S </ProgramListing> - and the <Application>postmaster</Application> will be "S"ilent. Notice that there + and the <Application>postmaster</Application> will be "S"ilent. +Notice that there is no ampersand ("&") at the end of the last example. </Para> </Chapter> @@ -194,9 +47,12 @@ There is one evident drawback of using locale - it's speed! So, use locale only <Para> <Application>createuser</Application> enables specific users to access - <ProductName>Postgres</ProductName>. <Application>destroyuser</Application> removes users and - prevents them from accessing <ProductName>Postgres</ProductName>. Note that these - commands only affect users with respect to <ProductName>Postgres</ProductName>; + <ProductName>Postgres</ProductName>. +<Application>destroyuser</Application> removes users and + prevents them from accessing <ProductName>Postgres</ProductName>. +Note that these + commands only affect users with respect to +<ProductName>Postgres</ProductName>; they have no effect on users other privileges or status with regards to the underlying operating system. @@ -242,7 +98,8 @@ PGDATA2 pointing to <filename>/home/postgres/data</filename>, type </ProgramListing> <Para> -Usually, you will want to define this variable in the <ProductName>Postgres</ProductName> superuser's +Usually, you will want to define this variable in the +<ProductName>Postgres</ProductName> superuser's <filename>.profile</filename> or <filename>.cshrc</filename> @@ -274,7 +131,8 @@ To test the new location, create a database <Database>test</Database> by typing <Para> Assuming that your site administrator has properly - started the <Application>postmaster</Application> process and authorized you to + started the <Application>postmaster</Application> process +and authorized you to use the database, you (as a user) may begin to start up applications. As previously mentioned, you should add <filename>/usr/local/pgsql/bin</filename> to your shell search path. @@ -282,10 +140,12 @@ To test the new location, create a database <Database>test</Database> by typing terms of preparation. <Para> - If you get the following error message from a <ProductName>Postgres</ProductName> - command (such as <Application>psql</Application> or <Application>createdb</Application>): + If you get the following error message from a +<ProductName>Postgres</ProductName> + command (such as <Application>psql</Application> or +<Application>createdb</Application>): <ProgramListing> -connectDB() failed: Is the postmaster running at 'localhost' on port '4322'? +connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? </ProgramListing> it is usually because either the <Application>postmaster</Application> is not running, or you are attempting to connect to the wrong server host. @@ -303,8 +163,8 @@ FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) <Title>Managing a Database</Title> <Para> - Now that <ProductName>Postgres</ProductName> is up and running we can create some - databases to experiment with. Here, we describe the + Now that <ProductName>Postgres</ProductName> is up and running we can create + some databases to experiment with. Here, we describe the basic commands for managing a database. </Para> @@ -318,12 +178,15 @@ FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) % createdb mydb </ProgramListing> - <ProductName>Postgres</ProductName> allows you to create any number of databases + <ProductName>Postgres</ProductName> allows you to create +any number of databases at a given site and you automatically become the - database administrator of the database you just created. Database names must have an alphabetic first + database administrator of the database you just created. +Database names must have an alphabetic first character and are limited to 16 characters in length. Not every user has authorization to become a database - administrator. If <ProductName>Postgres</ProductName> refuses to create databases + administrator. If <ProductName>Postgres</ProductName> +refuses to create databases for you, then the site administrator needs to grant you permission to create databases. Consult your site administrator if this occurs. @@ -340,23 +203,24 @@ FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) <ItemizedList Mark="bullet" Spacing="compact"> <ListItem> <Para> -running the <ProductName>Postgres</ProductName> terminal monitor programs ( - monitor or <Application>psql</Application>) which allows you to interactively +running the <ProductName>Postgres</ProductName> terminal monitor program +(<Application>psql</Application>) which allows you to interactively enter, edit, and execute <Acronym>SQL</Acronym> commands. </Para> </ListItem> <ListItem> <Para> - writing a C program using the LIBPQ subroutine + writing a C program using the <literal>libpq</literal> subroutine library. This allows you to submit <Acronym>SQL</Acronym> commands from C and get answers and status messages back to your program. This interface is discussed further - in section ??. + in the <citetitle>PostgreSQL Programmer's Guide</citetitle>. </Para> </ListItem> </ItemizedList> - You might want to start up <Application>psql</Application>, to try out the examples in this manual. It can be activated for the mydb + You might want to start up <Application>psql</Application>, +to try out the examples in this manual. It can be activated for the mydb database by typing the command: <ProgramListing> % psql mydb @@ -376,11 +240,14 @@ mydb=> </Para> <Para> -This prompt indicates that the terminal monitor is listening to you and that you can type <Acronym>SQL</Acronym> queries into a +This prompt indicates that the terminal monitor is listening +to you and that you can type <Acronym>SQL</Acronym> queries into a workspace maintained by the terminal monitor. - The <Application>psql</Application> program responds to escape codes that begin + The <Application>psql</Application> program responds to escape + codes that begin with the backslash character, "\". For example, you - can get help on the syntax of various <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing: + can get help on the syntax of various +<ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> commands by typing: <ProgramListing> mydb=> \h </ProgramListing> @@ -394,7 +261,8 @@ mydb=> \g This tells the server to process the query. If you terminate your query with a semicolon, the backslash-g is not - necessary. <Application>psql</Application> will automatically process semicolon terminated queries. + necessary. <Application>psql</Application> will automatically +process semicolon terminated queries. To read queries from a file, say myFile, instead of entering them interactively, type: <ProgramListing> @@ -406,11 +274,13 @@ mydb=> \i fileName mydb=> \q </ProgramListing> - and <Application>psql</Application> will quit and return you to your command + and <Application>psql</Application> will quit and return +you to your command shell. (For more escape codes, type backslash-h at the monitor prompt.) White space (i.e., spaces, tabs and newlines) may be - used freely in <Acronym>SQL</Acronym> queries. Single-line comments are denoted by + used freely in <Acronym>SQL</Acronym> queries. +Single-line comments are denoted by <Quote>--</Quote>. Everything after the dashes up to the end of the line is ignored. Multiple-line comments, and comments within a line, are denoted by <Quote>/* ... */</Quote> diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml new file mode 100644 index 00000000000..3922b89b161 --- /dev/null +++ b/doc/src/sgml/syntax.sgml @@ -0,0 +1,265 @@ +<chapter id="syntax"> +<title>SQL Syntax</title> + +<sect1> +<title>Key Words</title> + +<para> +<acronym>SQL92</acronym> defines <firstterm>key words</firstterm> for the language +which have specific meaning. Some key words are +<firstterm>reserved</firstterm>, which indicates that they are +restricted to appear in only certain contexts. Other key words are +<firstterm>not restricted</firstterm>, which indicates that in certain contexts they +have a specific meaning but are not otherwise constrained. + +<para> +<productname>Postgres</productname> implements an extended subset of the +<acronym>SQL92</acronym> and <acronym>SQL3</acronym> languages. Some language +elements are not as restricted in this implementation as is +called for in the language standards, in part due +to the extensibility features of <productname>Postgres</productname>. + +<para> +Information on <acronym>SQL92</acronym> and <acronym>SQL3</acronym> key words +is derived from <xref linkend="DATE97" endterm="DATE97-full">. + +<Sect2> +<Title>Reserved Key Words</Title> + +<Para> +<acronym>SQL92</acronym> and <acronym>SQL3</acronym> have +<firstterm>reserved key words</firstterm> which are not allowed +as identifiers and not allowed in any usage other than as fundamental +tokens in <acronym>SQL</acronym> statements. +<productname>Postgres</productname> has additional key words +which have similar restrictions. In particular, these key words +are not allowed as column or table names, though in some cases +they are allowed to be column labels (i.e. in AS clauses). + +<tip> +<para> +Any string can be specified as an identifier if surrounded by +double quotes (<quote>like this!</quote>). Some care is required since +such an identifier will be case sensitive +and will retain embedded whitespace. +</tip> + +<para> +The following are <productname>Postgres</productname> +reserved words which are neither <acronym>SQL92</acronym> +nor <acronym>SQL3</acronym> reserved words. These are allowed +to be present as column labels, but not as identifiers: + +<programlisting> +ABORT ANALYZE +BINARY +CLUSTER CONSTRAINT COPY +DO +EXPLAIN EXTEND +LISTEN LOAD LOCK +MOVE +NEW NONE NOTIFY +RESET +SETOF SHOW +UNLISTEN UNTIL +VACUUM VERBOSE +</programlisting> + +The following are <productname>Postgres</productname> +reserved words which are also <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> reserved words, and which +are allowed to be present as column labels, but not as identifiers: + +<programlisting> +CROSS CURRENT +FALSE FOREIGN +GROUP +ORDER +POSITION PRECISION +TABLE TRANSACTION TRUE +</programlisting> + +The following are <productname>Postgres</productname> +reserved words which are also <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> reserved words: + +<programlisting> +ADD ALL ALTER AND ANY AS ASC +BEGIN BETWEEN BOTH BY +CASCADE CAST CHAR CHARACTER CHECK CLOSE COLLATE COLUMN COMMIT +CONSTRAINT CREATE CURRENT_DATE CURRENT_TIME +CURRENT_TIMESTAMP CURRENT_USER CURSOR +DECIMAL DECLARE DEFAULT DELETE DESC DISTINCT DROP +END EXECUTE EXISTS EXTRACT +FETCH FLOAT FOR FROM FULL +GRANT +HAVING +IN INNER INSERT INTERVAL INTO IS +JOIN +LEADING LEFT LIKE LOCAL +NAMES NATIONAL NATURAL NCHAR NO NOT NULL NUMERIC +ON OR OUTER +PARTIAL PRIMARY PRIVILEGES PROCEDURE PUBLIC +REFERENCES REVOKE RIGHT ROLLBACK +SELECT SET SUBSTRING +TIMESTAMP TO TRAILING TRIM +UNION UNIQUE UPDATE USER USING +VALUES VARCHAR VARYING VIEW +WHERE WITH WORK +</programlisting> + +The following are <acronym>SQL92</acronym> reserved key words which +are not <productname>Postgres</productname> reserved key words, but which +if used as function names are always translated into the function +<function>length</function>: + +<programlisting> +CHAR_LENGTH CHARACTER_LENGTH +</programlisting> + +The following are <acronym>SQL92</acronym> or <acronym>SQL3</acronym> +reserved key words which +are not <productname>Postgres</productname> reserved key words, but +if used as type names which are always translated into an alternate, native type: + +<programlisting> +BOOLEAN DOUBLE FLOAT INT INTEGER INTERVAL REAL SMALLINT +</programlisting> + +<para> +The following are either <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> reserved key words +which are not key words in <productname>Postgres</productname>. +These have no proscribed usage in <productname>Postgres</productname> +at the time of writing (v6.4) but may become reserved key words in the +future: + +<note> +<para> +Some of these key words represent functions in <acronym>SQL92</acronym>. +These functions are defined in <productname>Postgres</productname>, +but the parser does not consider the names to be key words and they are allowed +in other contexts. +</note> + +<programlisting> +ALLOCATE ARE ASSERTION AT AUTHORIZATION AVG +BIT BIT_LENGTH +CASCADED CASE CATALOG COALESCE COLLATION +CONNECT CONNECTION CONSTRAINTS CONTINUE CONVERT CORRESPONDING COUNT +DATE DEALLOCATE DEC DESCRIBE DESCRIPTOR DIAGNOSTICS DISCONNECT DOMAIN +ELSE END-EXEC ESCAPE EXCEPT EXCEPTION EXEC EXTERNAL +FIRST FOUND +GET GLOBAL GO GOTO +IDENTITY IMMEDIATE INDICATOR INITIALLY INPUT INTERSECT ISOLATION +LAST LEVEL LOWER +MAX MIN MODULE +NULLIF +OCTET_LENGTH OPEN OUTPUT OVERLAPS +PREPARE PRESERVE +RESTRICT ROWS +SCHEMA SECTION SESSION SESSION_USER SIZE SOME +SQL SQLCODE SQLERROR SQLSTATE SUM SYSTEM_USER +TEMPORARY THEN TRANSLATE TRANSLATION +UNKNOWN UPPER USAGE +VALUE +WHEN WHENEVER WRITE +</programlisting> + +<Sect2> +<Title>Non-reserved Keywords</Title> + +<Para> +<acronym>SQL92</acronym> and <acronym>SQL3</acronym> have +<firstterm>non-reserved keywords</firstterm> which have +a proscribed meaning in the language but which are also allowed +as identifiers. +<productname>Postgres</productname> has additional keywords +which allow similar unrestricted usage. +In particular, these keywords +are allowed as column or table names. + +<para> +The following are <productname>Postgres</productname> +non-reserved key words which are neither <acronym>SQL92</acronym> +nor <acronym>SQL3</acronym> non-reserved key words: + +<programlisting> +AFTER AGGREGATE +BACKWARD BEFORE +CACHE CREATEDB CREATEUSER CYCLE +DATABASE DELIMITERS +EACH ENCODING +FORWARD FUNCTION +HANDLER +INCREMENT INDEX INHERITS INSENSITIVE INSTEAD ISNULL +LANCOMPILER LOCATION +MAXVALUE MINVALUE +NOCREATEDB NOCREATEUSER NOTHING NOTNULL +OIDS OPERATOR +PASSWORD PROCEDURAL +RECIPE RENAME RETURNS ROW RULE +SEQUENCE SERIAL START STATEMENT STDIN STDOUT +TRUSTED +VALID VERSION +</programlisting> + +<para> +The following are <productname>Postgres</productname> +non-reserved key words which are <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> reserved key words: + +<programlisting> +ABSOLUTE ACTION +DAY +HOUR +INSENSITIVE +KEY +LANGUAGE +MATCH MINUTE MONTH +NEXT +OF ONLY OPTION +PRIOR PRIVILEGES +READ RELATIVE +SCROLL SECOND +TIME TIMEZONE_HOUR TIMEZONE_MINUTE TRIGGER +YEAR +ZONE +</programlisting> + +<para> +The following are <productname>Postgres</productname> +non-reserved key words which are also either <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> non-reserved key words: + +<programlisting> +TYPE +</programlisting> + +<para> +The following are either <acronym>SQL92</acronym> +or <acronym>SQL3</acronym> non-reserved key words which are not +key words of any kind in <productname>Postgres</productname>: + +<programlisting> +ADA +C CATALOG_NAME CHARACTER_SET_CATALOG CHARACTER_SET_NAME +CHARACTER_SET_SCHEMA CLASS_ORIGIN COBOL COLLATION_CATALOG +COLLATION_NAME COLLATION_SCHEMA COLUMN_NAME +COMMAND_FUNCTION COMMITTED CONDITION_NUMBER +CONNECTION_NAME CONSTRAINT_CATALOG CONSTRAINT_NAME +CONSTRAINT_SCHEMA CURSOR_NAME +DATA DATE_TIME_INTERVAL_CODE DATE_TIME_INTERVAL_PRECISION +DYNAMIC_FUNCTION +FORTRAN +LENGTH +MESSAGE_LENGTH MESSAGE_OCTET_LENGTH MORE MUMPS +NAME NULLABLE NUMBER +PAD PASCAL PLI +REPEATABLE RETURNED_LENGTH RETURNED_OCTET_LENGTH +RETURNED_SQLSTATE ROW_COUNT +SCALE SCHEMA_NAME SERIALIZABLE SERVER_NAME SPACE +SUBCLASS_ORIGIN +TABLE_NAME +UNCOMMITTED UNNAMED +</programlisting> diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 8bfc7789351..38bd7d942db 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,10 +1,19 @@ <!-- -$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.5 1998/08/17 16:20:32 thomas Exp $ +$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.6 1998/09/30 05:41:54 thomas Exp $ + Postgres User's Manual. Derived from postgres.sgml. thomas 1998-02-24 $Log: user.sgml,v $ +Revision 1.6 1998/09/30 05:41:54 thomas +Clean up pages. Add information for operator precedence. +Split introduction sections into separate files to allow the legal notice + and notation sections appear in all documents without having the history + show up everplace too. +Add full list of reserved and non-reserved key words in syntax.sgml. +Add a separate chapter to the admin guide on security. + Revision 1.5 1998/08/17 16:20:32 thomas Move SQL reference pages up into the User's Guide. @@ -14,6 +23,13 @@ Include new chapters. --> <!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [ + +<!entity about SYSTEM "about.sgml"> +<!entity history SYSTEM "history.sgml"> +<!entity info SYSTEM "info.sgml"> +<!entity legal SYSTEM "legal.sgml"> +<!entity notation SYSTEM "notation.sgml"> + <!entity intro SYSTEM "intro.sgml"> <!entity advanced SYSTEM "advanced.sgml"> <!entity environ SYSTEM "environ.sgml"> @@ -30,12 +46,13 @@ Include new chapters. <!entity psql SYSTEM "psql.sgml"> <!entity pgaccess SYSTEM "pgaccess.sgml"> <!entity biblio SYSTEM "biblio.sgml"> +<!entity syntax SYSTEM "syntax.sgml"> <!-- reference pages --> <!entity % allfiles SYSTEM "allfiles.sgml"> %allfiles; ]> -<!-- entity manpages SYSTEM "man/manpages.sgml" subdoc --> + <Book Id="user"> <!-- Title information --> @@ -107,6 +124,7 @@ It provides SQL92/SQL3 language support, &intro; &environ; &manage; +&syntax; &datatype; &oper; &func; |