diff --git a/doc/src/sgml/Makefile b/doc/src/sgml/Makefile index 99bc4dab1d..83f14df581 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 0000000000..ebdb125809 --- /dev/null +++ b/doc/src/sgml/about.sgml @@ -0,0 +1,18 @@ + +About This Release + + + PostgreSQL is available without cost. This manual + describes version 6.4 of PostgreSQL. + + + We will use Postgres +to mean the version distributed as PostgreSQL. + + +Check the Administrator's Guide for a list of currently supported machines. +In general, +Postgres is portable to any Unix/Posix-compatible system +with full libc library support. + + diff --git a/doc/src/sgml/admin.sgml b/doc/src/sgml/admin.sgml index c7bbe53220..ed53c2cfaf 100644 --- a/doc/src/sgml/admin.sgml +++ b/doc/src/sgml/admin.sgml @@ -1,23 +1,34 @@ - - + + + + + + + + + + ]> - + @@ -86,10 +97,11 @@ It provides SQL92/SQL3 language support, -&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 0aa3552860..d7afdf60de 100644 --- a/doc/src/sgml/biblio.sgml +++ b/doc/src/sgml/biblio.sgml @@ -9,14 +9,21 @@ Selected references and readings for SQL and Pos <Acronym>SQL</Acronym> Reference Books Reference texts for SQL features. - + -The Practical <Acronym>SQL</Acronym> Handbook -Using Structured Query Language + +The Practical <Acronym>SQL</Acronym> Handbook + + +Bowman et al, 1993 + + +Using Structured Query Language + 3 @@ -46,15 +53,21 @@ Selected references and readings for SQL and Pos --> - + -A Guide to The <Acronym>SQL</Acronym> Standard -The SQL Standard -A user's guide to the standard database language SQL + +A Guide to the <Acronym>SQL</Acronym> Standard + + +Date and Darwen, 1997 + + +A user's guide to the standard database language SQL + 4 @@ -80,13 +93,18 @@ Selected references and readings for SQL and Pos --> - + -Understanding the New <Acronym>SQL</Acronym> + +Understanding the New <Acronym>SQL</Acronym> + + +Melton and Simon, 1993 + A complete guide @@ -121,19 +139,24 @@ Selected references and readings for SQL and Pos PostgreSQL-Specific Documentation This section is for related documentation. - + -The <ProductName>PostgreSQL</ProductName> Administrator's Guide + +The <ProductName>PostgreSQL</ProductName> Administrator's Guide + + +The Administrator's Guide + Thomas Lockhart -1998-03-01 +1998-10-01 The PostgreSQL Global Development Group @@ -142,19 +165,24 @@ Selected references and readings for SQL and Pos --> - + -The <ProductName>PostgreSQL</ProductName> Developer's Guide + +The <ProductName>PostgreSQL</ProductName> Developer's Guide + + +The Developer's Guide + Thomas Lockhart -1998-03-01 +1998-10-01 The PostgreSQL Global Development Group @@ -163,19 +191,24 @@ Selected references and readings for SQL and Pos --> - + -The <ProductName>PostgreSQL</ProductName> Programmer's Guide + +The <ProductName>PostgreSQL</ProductName> Programmer's Guide + + +The Programmer's Guide + Thomas Lockhart -1998-03-01 +1998-10-01 The PostgreSQL Global Development Group @@ -184,19 +217,24 @@ Selected references and readings for SQL and Pos --> - + -The <ProductName>PostgreSQL</ProductName> Tutorial Introduction + +The <ProductName>PostgreSQL</ProductName> Tutorial Introduction + + +The Tutorial + Thomas Lockhart -1998-03-01 +1998-10-01 The PostgreSQL Global Development Group @@ -205,19 +243,24 @@ Selected references and readings for SQL and Pos --> - + -The <ProductName>PostgreSQL</ProductName> User's Guide + +The <ProductName>PostgreSQL</ProductName> User's Guide + + +The User's Guide + Thomas Lockhart -1998-03-01 +1998-10-01 The PostgreSQL Global Development Group @@ -226,14 +269,18 @@ Selected references and readings for SQL and Pos --> - + -The <ProductName>Postgres95</ProductName> User Manual -YU95 + +The <ProductName>Postgres95</ProductName> User Manual + + +Yu and Chen, 1995 + A. @@ -266,14 +313,18 @@ The POSTGRES Group Proceedings and Articles This section is for articles and newsletters. - + -A Unified Framework for Version Modeling Using Production Rules in a Database System -ONG90 + +A Unified Framework for Version Modeling Using Production Rules in a Database System + + +Ong and Goh, 1990 + L. @@ -294,14 +345,18 @@ The POSTGRES Group --> - + -The <ProductName>Postgres</ProductName> Data Model -ROWE87 + +The <ProductName>Postgres</ProductName> Data Model + + +Rowe and Stonebraker, 1987 + L. @@ -322,14 +377,19 @@ The POSTGRES Group --> - + -The Design of <ProductName>Postgres</ProductName> -STON86 + +The Design of <ProductName>Postgres</ProductName> + + +Stonebraker and Rowe, 1986 +STON86 + M. @@ -351,14 +411,17 @@ The POSTGRES Group --> - + -The Design of the <ProductName>Postgres</ProductName> Rules System -STON87a + +The Design of the <ProductName>Postgres</ProductName> Rules System + +Stonebraker, Hanson, Hong, 1987 + M. @@ -384,14 +447,18 @@ The POSTGRES Group --> - + -The <ProductName>Postgres</ProductName> Storage System -STON87b + +The <ProductName>Postgres</ProductName> Storage System + + +Stonebraker, 1987 + M. @@ -408,14 +475,17 @@ The POSTGRES Group --> - + -A Commentary on the <ProductName>Postgres</ProductName> Rules System -STON89 + +A Commentary on the <ProductName>Postgres</ProductName> Rules System + + +Stonebraker et al, 1989 M. @@ -434,21 +504,25 @@ The POSTGRES Group Sept. 1989 Record 18(3) SIGMOD -1987 +1989 - + -The Implementation of <ProductName>Postgres</ProductName> -STON90a + +The Implementation of <ProductName>Postgres</ProductName> + + +Stonebraker, Rowe, Hirohama, 1990 + M. @@ -473,21 +547,25 @@ The POSTGRES Group --> - + -On Rules, Procedures, Caching and Views in Database Systems -STON90b + +On Rules, Procedures, Caching and Views in Database Systems + + +Stonebraker et al, ACM, 1990 + M. Stonebraker -et. al. +et al diff --git a/doc/src/sgml/config.sgml b/doc/src/sgml/config.sgml new file mode 100644 index 0000000000..bdb881203f --- /dev/null +++ b/doc/src/sgml/config.sgml @@ -0,0 +1,270 @@ + +Configuration Options + + +Locale Support + + + + +Written by Oleg Bartunov. +See Oleg's web page + for additional information on locale and Russian language support. + + + +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 Postgres 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. + + + People often complain that locale doesn't work for them. +There are several common mistakes: + + + + + 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): + + + #!/bin/sh + + export LC_CTYPE=koi8-r + export LC_COLLATE=koi8-r + postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' + + + and run it from rc.local as + + + /bin/su - postgres -c "/home/postgres/runpostgres" + + + + + + + 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: + + + 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"). + + + + + + + Wrong location of locale files! + + Possible locations include: +/usr/lib/locale +(Linux, Solaris), /usr/share/locale (Linux), +/usr/lib/nls/loc (DUX 4.0). + + Check man locale to find the correct location. +Under Linux I did a symbolic link between /usr/lib/locale and + /usr/share/locale to be sure that +the next libc will not break my locale. + + + + + +What are the Benefits? + + +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. + + +What are the Drawbacks? + + +There is one evident drawback of using locale - it's speed! +So, use locale only if you really need it. + + +Kerberos Authentication + + +Kerberos is an industry-standard secure authentication +system suitable for distributed computing over a public network. + + +Availability + + +The +Kerberos +authentication system is not distributed with Postgres. Versions of +Kerberos +are typically available as optional software from operating system +vendors. In addition, a source code distribution may be obtained through +MIT Project Athena. + + + +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. + +Users located outside the United States of America and +Canada are warned that distribution of the actual encryption code in +Kerberos +is restricted by U. S. Government export regulations. + + +Inquiries regarding your Kerberos +should be directed to your vendor or +MIT Project Athena. +Note that FAQLs +(Frequently-Asked Questions Lists) are periodically posted to the +Kerberos mailing list +(send +mail to subscribe), +and +USENET news group. + + +Installation + + +Installation of +Kerberos +itself is covered in detail in the +Kerberos Installation Notes . +Make sure that the server key file (the srvtab +or keytab) +is somehow readable by the Postgres account. + + +Postgres and its clients can be compiled to use +either Version 4 or Version 5 of the MIT +Kerberos +protocols by setting the +KRBVERS +variable in the file src/Makefile.global to the +appropriate value. You can also change the location where + Postgres +expects to find the associated libraries, header files and its own +server key file. + + +After compilation is complete, Postgres + must be registered as a Kerberos +service. See the +Kerberos Operations Notes +and related manual pages for more details on registering services. + + +Operation + + +After initial installation, Postgres +should operate in all ways as a normal +Kerberos +service. For details on the use of authentication, see the +PostgreSQL User's Guide reference sections +for postmaster +and psql. + + +In the +Kerberos +Version 5 hooks, the following assumptions are made about user +and service naming: + + + + +User principal names (anames) are assumed to +contain the actual Unix/Postgres user name + in the first component. + + + +The Postgres 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). + + + + + +Kerberos Parameter Examples +Kerberos + + + + + +Parameter + + +Example + + + + + +user + + +frew@S2K.ORG + + + + +user + + +aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG + + + + +host + + +postgres_dbms/ucbvax@S2K.ORG + + + +
+ + +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 98f12979e6..e460ae7e6b 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: exec sql type + + exec sql prepare + + exec sql allocate + + exec sql free + + exec sql whenever sqlwarning + + SQLSTATE + + diff --git a/doc/src/sgml/history.sgml b/doc/src/sgml/history.sgml new file mode 100644 index 0000000000..c12ef7d6b6 --- /dev/null +++ b/doc/src/sgml/history.sgml @@ -0,0 +1,217 @@ + +A Short History of <ProductName>Postgres</ProductName> + + +The Berkeley <ProductName>Postgres</ProductName> Project + + + Implementation of the Postgres +DBMS began in 1986. The + initial concepts for the system were presented in + + and the definition of the initial data model + appeared in +. +The design of the rule system at + that time was described in +. +The rationale + and architecture of the storage manager were detailed in +. + + + +Postgres has undergone several major releases since + then. The first "demoware" system became operational + in 1987 and was shown at the 1988 ACM-SIGMOD + Conference. We released Version 1, described in +, + to a few external users in June 1989. In response to a + critique of the first rule system +(), +the rule + system was redesigned +() +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. + + + +Postgres 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. +Postgres has also been + used as an educational tool at several universities. + Finally, +Illustra Information Technologies +(since merged into +Informix) + + picked up + the code and commercialized it. + Postgres became the primary data manager + for the +Sequoia 2000 + 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. + + + + +<ProductName>Postgres95</ProductName> + + +In 1994, +Andrew Yu +and +Jolly Chen +added a SQL language interpreter to Postgres, +and the code was subsequently released to +the Web to find its own way in the world. +Postgres95 was a public-domain, open source descendant +of this original Berkeley code. + + + +Postgres95 is a derivative of the last official release +of Postgres (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. +Postgres95 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: + + + + + The query language Postquel has been replaced with + SQL (implemented in the server). We do not yet support + subqueries (which can be imitated with user defined + SQL functions). Aggregates have been + re-implemented. We also added support for ``GROUP BY''. + The libpq interface is still available for C + programs. + + + + + In addition to the monitor program, we provide a new + program (psql) which supports GNU readline. + + + + + We added a new front-end library, libpgtcl, that + supports Tcl-based clients. A sample shell, + pgtclsh, provides new Tcl commands to interface tcl + programs with the Postgres95 backend. + + + + + 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.) + + + + + The instance-level rule system has been removed. + Rules are still available as rewrite rules. + + + + + A short tutorial introducing regular SQL features as + well as those of ours is distributed with the source + code. + + + + + GNU make (instead of BSD make) is used for the + build. Also, Postgres95 can be compiled with an + unpatched gcc (data alignment of doubles has been + fixed). + + + + + + + +<ProductName>PostgreSQL</ProductName> + + +By 1996, it became clear that the name Postgres95 would not stand +the test of time. A new name, PostgreSQL, +was chosen to reflect the +relationship between original Postgres +and the more recent +versions with SQL 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 Postgres Project. + + +The emphasis on development for the v1.0.x releases of +Postgres95 +was on stabilizing the backend code. +With the v6.x series of PostgreSQL, +the emphasis has shifted from +identifying and understanding existing problems in the backend +to augmenting features and capabilities, although +work continues in all areas. + + +Major enhancements include: + + + + +Important backend features, including subselects, defaults, +constraints, and triggers, have been implemented. + + + + +Additional SQL92-compliant language features have been added, + including primary keys, quoted identifiers, literal string type coersion, +type casting, and binary and hexadecimal integer input. + + + + +Built-in types have been improved, including new wide-range date/time types +and additional geometric type support. + + + + +Overall backend code speed has been increased by approximately 20-40%, +and backend startup time has decreased 80% since v6.0 was released. + + + + + + + \ 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 0000000000..444ed9d35b --- /dev/null +++ b/doc/src/sgml/info.sgml @@ -0,0 +1,146 @@ + +Resources + + +This manual set is organized into several parts: + + + +Tutorial + + +An introduction for new users. Does not cover advanced features. + + + + + +User's Guide + + +General information for users, including available commands and data types. + + + + + +Programmer's Guide + + +Advanced information for application programmers. Topics include +type and function extensibility, library interfaces, and application design issues. + + + + + +Administrator's Guide + + +Installation and management information. List of supported machines. + + + + + +Developer's Guide + + +Information for Postgres developers. This is intended +for those who are contributing to the Postgres +project; application development information should appear in the Programmer's Guide. + + + + + +Reference Manual + + +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. + + + + + + +In addition to this manual set, there are other resources to help you with +Postgres installation and use: + + + +man pages + + +The man pages have general information on command syntax. + + + + + +FAQs + + +The Frequently Asked Questions (FAQ) documents address both general issues +and some platform-specific issues. + + + + + +READMEs + + +README files are available for some contributed packages. + + + + + +Web Site + + +The Postgres web site has some information +not appearing in the distribution. There is a mhonarc catalog of mailing list traffic +which is a rich resource for many topics. + + + + + +Mailing Lists + + +The Postgres Questions +mailing list is a good place to have user questions answered. Other mailing lists are available; consult +the web page for details. + + + + + +Yourself! + + +Postgres is an open source product. +As such, it depends on the user community for +ongoing support. As you begin to use Postgres, +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 +Postgres Documentation +mailing list is the place to get going. + + + + + + diff --git a/doc/src/sgml/intro-ag.sgml b/doc/src/sgml/intro-ag.sgml new file mode 100644 index 0000000000..d54187b72b --- /dev/null +++ b/doc/src/sgml/intro-ag.sgml @@ -0,0 +1,24 @@ + +Introduction + + + This document is the Administrator's Manual for the + PostgreSQL + database management system, originally developed at the University + of California at Berkeley. + +PostgreSQL is based on + + Postgres release 4.2. +The Postgres project, + led by Professor Michael Stonebraker, was sponsored by the + Defense Advanced Research Projects Agency (DARPA), the + Army Research Office (ARO), the National Science + Foundation (NSF), and ESL, Inc. + + +¬ation; + +&legal; + + diff --git a/doc/src/sgml/intro-pg.sgml b/doc/src/sgml/intro-pg.sgml index 78cf982390..cd9b98073f 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 PostgreSQL database management system, originally developed at the University - of California at Berkeley. PostgreSQL is based on + of California at Berkeley. + +PostgreSQL is based on Postgres release 4.2. The Postgres project, @@ -17,14 +19,17 @@ The Postgres project, The first part of this manual - explains the - Postgres approach to extensibility and describe how - users can extend Postgres by adding user-defined types, - operators, aggregates, and both query language and programming language functions. + explains the Postgres +approach to extensibility and describe how + users can extend Postgres +by adding user-defined types, + operators, aggregates, and both query language and programming +language functions. After an extremely brief overview of the Postgres 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. @@ -32,43 +37,8 @@ The Postgres project, We assume proficiency with UNIX and C programming. - -Copyrights and Trademarks +¬ation; - -PostgreSQL is copyright (C) 1996-8 by the PostgreSQL Global Development Group, -and is distributed under the terms of the Berkeley license. - - -Postgres95 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. - - -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. - - -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. - - - -UNIX 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. - +&legal; diff --git a/doc/src/sgml/intro.sgml b/doc/src/sgml/intro.sgml index 45b42e43cc..b777099bcf 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 PostgreSQL database management system, originally developed at the University - of California at Berkeley. PostgreSQL is based on + of California at Berkeley. + +PostgreSQL is based on Postgres release 4.2. The Postgres 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 (DARPA), the Army Research Office (ARO), the National Science Foundation (NSF), 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 Postgres. - - -A Short History of <ProductName>Postgres</ProductName> - -The Berkeley <ProductName>Postgres</ProductName> Project +&history; - - Implementation of the Postgres DBMS began in 1986. The - initial concepts for the system were presented in - -[STON86] - and the definition of the initial data model - appeared in - -[ROWE87]. -The design of the rule system at - that time was described in - -[STON87a]. -The rationale - and architecture of the storage manager were detailed in - -[STON87b]. - +&about; - - Postgres has undergone several major releases since - then. The first "demoware" system became operational - in 1987 and was shown at the 1988 ACM-SIGMOD - Conference. We released Version 1, described in - -[STON90a], - to a few external users in June 1989. In response to a - critique of the first rule system - -([STON89]), -the rule - system was redesigned - -([STON90b]) -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. - +&info; - - Postgres 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. Postgres has also been - used as an educational tool at several universities. - Finally, Illustra Information Technologies picked up - the code and commercialized it. - Postgres became the primary data manager for the - Sequoia 2000 - 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. - - - - -<ProductName>Postgres95</ProductName> - - -In 1994, -Andrew Yu -and -Jolly Chen -added a SQL language interpreter to Postgres, and the code was subsequently released to -the Web to find its own way in the world. Postgres95 was a public-domain, open source descendant -of this original Berkeley code. - - - - Postgres95 is a derivative of the last official release - of Postgres (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. Postgres95 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: - - - - - The query language Postquel has been replaced with - SQL (implemented in the server). We do not yet support - subqueries (which can be imitated with user defined - SQL functions). Aggregates have been - re-implemented. We also added support for ``GROUP BY''. - The libpq interface is still available for C - programs. - - - - - In addition to the monitor program, we provide a new - program (psql) which supports GNU readline. - - - - - We added a new front-end library, libpgtcl, that - supports Tcl-based clients. A sample shell, - pgtclsh, provides new Tcl commands to interface tcl - programs with the Postgres95 backend. - - - - - 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.) - - - - - The instance-level rule system has been removed. - Rules are still available as rewrite rules. - - - - - A short tutorial introducing regular SQL features as - well as those of ours is distributed with the source - code. - - - - - GNU make (instead of BSD make) is used for the - build. Also, Postgres95 can be compiled with an - unpatched gcc (data alignment of doubles has been - fixed). - - - - - - - -<ProductName>PostgreSQL</ProductName> - - -By 1996, it became clear that the name Postgres95 would not stand -the test of time. A new name, PostgreSQL, was chosen to reflect the -relationship between original Postgres and the more recent -versions with SQL 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 Postgres Project. - - -The emphasis on development for the v1.0.x releases of Postgres95 -was on stabilizing the backend code. -With the v6.x series of PostgreSQL, the emphasis has shifted from -identifying and understanding existing problems in the backend to augmenting features and capabilities, although -work continues in all areas. - - -Major enhancements include: - - - - -Important backend features, including subselects, defaults, constraints, and triggers, have been implemented. - - - - -Additional SQL92-compliant language features have been added, - including primary keys, quoted identifiers, literal string type coersion, type casting, - and binary and hexadecimal integer input. - - - - -Built-in types have been improved, including new wide-range date/time types and additional geometric type support. - - - - -Overall backend code speed has been increased by approximately 20%, and backend startup time has decreased 80%. - - - - - - - -About This Release - - - From now on, We will use Postgres to mean PostgreSQL. - - - PostgreSQL is available without cost. This manual - describes version 6.3 of PostgreSQL. - - -Check the Administrator's Guide for a list of currently supported machines. In general, -PostgreSQL is portable to any Unix/Posix-compatible system -with full libc library support. - - - - -Resources - - -This manual set is organized into several parts: - - - -Tutorial - - -An introduction for new users. Does not cover advanced features. - - - - - -User's Guide - - -General information for users, including available commands and data types. - - - - - -Programmer's Guide - - -Advanced information for application programmers. Topics include -type and function extensibility, library interfaces, and application design issues. - - - - - -Administrator's Guide - - -Installation and management information. List of supported machines. - - - - - -Developer's Guide - - -Information for Postgres developers. This is intended -for those who are contributing to the Postgres -project; application development information should appear in the Programmer's Guide. - - - - - -Reference Manual - - -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. - - - - - - -In addition to this manual set, there are other resources to help you with -Postgres installation and use: - - - -man pages - - -The man pages have general information on command syntax. - - - - - -FAQs - - -The Frequently Asked Questions (FAQ) documents address both general issues -and some platform-specific issues. - - - - - -READMEs - - -README files are available for some contributed packages. - - - - - -Web Site - - -The Postgres web site has some information -not appearing in the distribution. There is a mhonarc catalog of mailing list traffic -which is a rich resource for many topics. - - - - - -Mailing Lists - - -The Postgres Questions -mailing list is a good place to have user questions answered. Other mailing lists are available; consult -the web page for details. - - - - - -Yourself! - - -Postgres is an open source product. As such, it depends on the user community for -ongoing support. As you begin to use Postgres, 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 Postgres Documentation -mailing list is the place to get going. - - - - - - - - -Copyrights and Trademarks - - -PostgreSQL is copyright (C) 1996-8 by the PostgreSQL Global Development Group, -and is distributed under the terms of the Berkeley license. - - -Postgres95 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. - - -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. - - -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. - - - -UNIX 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. - +&legal; diff --git a/doc/src/sgml/legal.sgml b/doc/src/sgml/legal.sgml new file mode 100644 index 0000000000..bf347ca90c --- /dev/null +++ b/doc/src/sgml/legal.sgml @@ -0,0 +1,40 @@ + +Copyrights and Trademarks + + +PostgreSQL is copyright (C) 1996-8 +by the PostgreSQL Global Development Group, +and is distributed under the terms of the Berkeley license. + + +Postgres95 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. + + +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. + + +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. + + + +UNIX 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. + diff --git a/doc/src/sgml/notation.sgml b/doc/src/sgml/notation.sgml new file mode 100644 index 0000000000..f31a9c0858 --- /dev/null +++ b/doc/src/sgml/notation.sgml @@ -0,0 +1,73 @@ + +Terminology + + +In the following documentation, +site +may be interpreted as the host machine on which +Postgres is installed. +Since it is possible to install more than one set of +Postgres +databases on a single host, this term more precisely denotes any +particular set of installed +Postgres binaries and databases. + + +The +Postgres super-user +is the user named postgres + who owns the Postgres +binaries and database files. As the database super-user, all +protection mechanisms may be bypassed and any data accessed +arbitrarily. +In addition, the Postgres super-user is allowed to execute +some support programs which are generally not available to all users. +Note that the Postgres super-user is +not +the same as the Unix super-user (root), +and should have a non-zero userid for security reasons. + + +The +database base administrator +or DBA, is the person who is responsible for installing +Postgres 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 +createdb. + + +The postmaster +is the process that acts as a clearing-house for requests +to the Postgres system. +Frontend applications connect to the postmaster, +which keeps tracks of any system errors and communication between the +backend processes. The postmaster +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. + + +The Postgres backend +(the actual executable program postgres) may be executed +directly from the user shell by the +Postgres 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. + + +Notation + + +... at the front of a file name is used to represent the +path to the Postgres super-user's home directory. +Anything in brackets +[ and ]) is optional. Anything in braces +({ and }) can be repeated 0 or more times. +Parentheses (( and )) are used to group boolean +expressions. | is the boolean operator OR. + + \ No newline at end of file diff --git a/doc/src/sgml/odbc.sgml b/doc/src/sgml/odbc.sgml index 2767b00fbc..4ecc1d40f6 100644 --- a/doc/src/sgml/odbc.sgml +++ b/doc/src/sgml/odbc.sgml @@ -13,7 +13,7 @@ 1998-08-25 -<acronym>ODBC</acronym> Interface +ODBC Interface diff --git a/doc/src/sgml/oper.sgml b/doc/src/sgml/oper.sgml index 663d65e6b0..1cff4ca904 100644 --- a/doc/src/sgml/oper.sgml +++ b/doc/src/sgml/oper.sgml @@ -29,6 +29,200 @@ oprleft|oprright|oprresult|oprcode + +Lexical Precedence + + +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 ">=". + + + +Operator Ordering (decreasing precedence) + + + + + + +Element + +Precedence + +Description + + + + + +UNION + +left + +SQL select construct + + +:: + + +Postgres typecasting + + + +[ ] + +left + +array delimiters + + + +. + +left + +table/column delimiter + + + +- + +right + +unary minus + + + +; + +left + +statement termination, logarithm + + + +: + +right + +exponentiation + + + +| + +left + +start of interval + + + +* / + +left + +multiplication, division + + + ++ - + +left + +addition, subtraction + + + +IS + + +test for TRUE, FALSE, NULL + + +ISNULL + + +test for NULL + + + +NOTNULL + + +test for NOT NULL + + + +(all other operators) + + +native and user-defined + + + +IN + + +set membership + + + +BETWEEN + + +containment + + + +LIKE + + +string pattern matching + + + +< > + + +boolean inequality + + + += + +right + +equality + + + +NOT + +right + +negation + + + +AND + +left + +logical intersection + + + +OR + +left + +logical union + + +
+ General Operators diff --git a/doc/src/sgml/postgres.sgml b/doc/src/sgml/postgres.sgml index a1a847c876..4a7a6cc086 100644 --- a/doc/src/sgml/postgres.sgml +++ b/doc/src/sgml/postgres.sgml @@ -1,10 +1,19 @@ @@ -42,8 +57,10 @@ Include new chapters. %allfiles; + + @@ -195,6 +212,7 @@ Information for users. Installation and maintenance information. +&intro-ag; &ports; &install; &start-ag; diff --git a/doc/src/sgml/programmer.sgml b/doc/src/sgml/programmer.sgml index 5403a95d63..2a5b1c782a 100644 --- a/doc/src/sgml/programmer.sgml +++ b/doc/src/sgml/programmer.sgml @@ -1,12 +1,22 @@ - + + + + + + + + + @@ -60,7 +70,7 @@ ]> - + @@ -95,7 +105,8 @@ -PostgreSQL is copyright (C) 1998 by the Postgres Global Development Group. +PostgreSQL is copyright (C) 1998 +by the Postgres Global Development Group. diff --git a/doc/src/sgml/query-ug.sgml b/doc/src/sgml/query-ug.sgml index 6d4112ce2b..2b3a3c5621 100644 --- a/doc/src/sgml/query-ug.sgml +++ b/doc/src/sgml/query-ug.sgml @@ -4,7 +4,8 @@ -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 @@ -15,32 +16,38 @@ This chapter must go into depth on each area of the query language. Currently a SQL3. It has many extensions such as an extensible type system, inheritance, functions and production rules. Those are - features carried over from the original Postgres query - language, PostQuel. This section provides an overview - of how to use Postgres SQL to perform simple operations. + features carried over from the original Postgres +query + language, PostQuel. +This section provides an overview + of how to use Postgres SQL + to perform simple operations. This manual is only intended to give you an idea of our flavor of SQL and is in no way a complete tutorial on SQL. Numerous books have been written on SQL. For - instance, consult [MELT93] or - [DATE93]. You should also - be aware that some features are not part of the ANSI - standard. + instance, consult or + . You should also + be aware that some features of Postgres +are not part of the ANSI standard. Concepts - The fundamental notion in Postgres is that of a class, + The fundamental notion in Postgres +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 object identifier (OID) + each instance has a permanent object +identifier (OID) that is unique throughout the installation. Because SQL syntax refers to tables, we will use the terms table and class interchangeably. Likewise, an SQL row is an - instance and SQL columns + instance and SQL +columns are attributes. 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 0000000000..f699088119 --- /dev/null +++ b/doc/src/sgml/runtime.sgml @@ -0,0 +1,90 @@ + +Runtime Environment + + +This chapter outlines the interaction between Postgres and +the operating system. + + +Using <Productname>Postgres</Productname> from Unix + + +All Postgres commands that are executed +directly from a Unix shell are +found in the directory .../bin. Including this directory in +your search path will make executing the commands easier. + + +A collection of system catalogs exist at each site. These include a +class (pg_user) that contains an instance for each valid +Postgres user. The instance specifies a set of + Postgres privileges, such as +the ability to act as Postgres super-user, + the ability to create/destroy +databases, and the ability to update the system catalogs. A Unix +user cannot do anything with Postgres +until an appropriate instance is +installed in this class. Further information on the system catalogs +is available by running queries on the appropriate classes. + + +System Layout + + +
+<ProductName>Postgres</ProductName> file layout + +
+ + +shows how the Postgres distribution is laid + out when installed in the default way. For simplicity, + we will assume that Postgres + has been installed in the + directory /usr/local/pgsql. Therefore, wherever + you see the directory /usr/local/pgsql you should + substitute the name of the directory where + Postgres is + actually installed. + All Postgres commands are installed + in the directory + /usr/local/pgsql/bin. 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 + +set path = ( /usr/local/pgsql/bin path ) + + 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 + +PATH=/usr/local/pgsql/bin PATH +export PATH + + to the .profile file in your home directory. + From now on, we will assume that you have added the + Postgres 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. + + + +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 PGHOST environment variable to the name +of the database server machine. The environment variable +PGPORT 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 postmaster, +you must go back and make sure that your +environment is properly set up. + + + diff --git a/doc/src/sgml/security.sgml b/doc/src/sgml/security.sgml new file mode 100644 index 0000000000..39a4abdf60 --- /dev/null +++ b/doc/src/sgml/security.sgml @@ -0,0 +1,155 @@ + +Security + + + + +User Authentication + + +Authentication +is the process by which the backend server and +postmaster +ensure that the user requesting access to data is in fact who he/she +claims to be. +All users who invoke Postgres are checked against the +contents of the pg_user 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: + + + + +From the user shell + + + +A backend server started from a user shell notes the user's (effective) +user-id before performing a +setuid +to the user-id of user postgres. +The effective user-id is used +as the basis for access control checks. No other authentication is +conducted. + + + +From the network + + + +If the Postgres system is built as distributed, + access to the Internet TCP port of the +postmaster +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 pg_hba.conf(5) + 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 Postgres. + + + + + +Access Control + + +Postgres provides mechanisms to allow users +to limit the access to their data that is provided to other users. + + + + +Database superusers + + + +Database super-users (i.e., users who have pg_user.usesuper +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 pg_user.usecatupd set, and destruction of +system catalogs (or modification of their schemas) is never allowed. + + + +Access Privilege + + + +The use of access privilege to limit reading, writing and setting +of rules on classes is covered in +grant/revoke(l). + + + +Class removal and schema modification + + + +Commands that destroy or modify the structure of an existing class, +such as alter, +drop table, +and +drop index, +only operate for the owner of the class. As mentioned above, these +operations are never +permitted on system catalogs. + + + + +Functions and Rules + + +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 trojan horse +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 +pg_class, pg_user + and pg_group are also recommended. + + +Functions + + +Functions written in any language except SQL +run inside the backend server +process with the permissions of the user postgres (the +backend server runs with its real and effective user-id set to +postgres. 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. + + +Rules + + +Like SQL functions, rules always run with the identity and +permissions of the user who invoked the backend server. + + + +Caveats + + + +There are no plans to explicitly support encrypted data inside of +Postgres +(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. + +User names, group names and associated system identifiers (e.g., the +contents of pg_user.usesysid) are assumed to be unique +throughout a database. Unpredictable results may occur if they are +not. + + \ No newline at end of file diff --git a/doc/src/sgml/start-ag.sgml b/doc/src/sgml/start-ag.sgml index da97428bbe..49c37a3a8c 100644 --- a/doc/src/sgml/start-ag.sgml +++ b/doc/src/sgml/start-ag.sgml @@ -4,167 +4,17 @@ - - thomas 1998-02-24 --> - -Runtime Environment - - -
-<ProductName>Postgres</ProductName> file layout - -
- - -shows how the Postgres distribution is laid - out when installed in the default way. For simplicity, - we will assume that Postgres has been installed in the - directory /usr/local/pgsql. Therefore, wherever - you see the directory /usr/local/pgsql you should - substitute the name of the directory where Postgres is - actually installed. - All Postgres commands are installed in the directory - /usr/local/pgsql/bin. 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 - -set path = ( /usr/local/pgsql/bin path ) - - 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 - -PATH=/usr/local/pgsql/bin PATH -export PATH - - to the .profile file in your home directory. - From now on, we will assume that you have added the - Postgres 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. - - - -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 PGHOST environment variable to the name -of the database server machine. The environment variable -PGPORT 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 postmaster, you should immediately consult your site administrator to make sure that your -environment is properly set up. - - - -Locale Support - - - - -Written by Oleg Bartunov. -See Oleg's web page - for additional information on locale and Russian language support. - - - -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 Postgres 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. - - - People often complain that locale doesn't work for them. There are several common mistakes: - - - - - 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): - - - #!/bin/sh - - export LC_CTYPE=koi8-r - export LC_COLLATE=koi8-r - postmaster -B 1024 -S -D/usr/local/pgsql/data/ -o '-Fe' - - - and run it from rc.local as - - - /bin/su - postgres -c "/home/postgres/runpostgres" - - - - - - - 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: - - - 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"). - - - - - - - Wrong location of locale files! - - Possible locations include: /usr/lib/locale (Linux, Solaris), /usr/share/locale (Linux), /usr/lib/nls/loc (DUX 4.0) - Check man locale to find the correct location. -Under Linux I did a symbolic link between /usr/lib/locale and - /usr/share/locale to be sure that the next libc will not break my locale. - - - - - -What are the Benefits? - - -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. - - -What are the Drawbacks? - - -There is one evident drawback of using locale - it's speed! So, use locale only if you really need it. - - - Starting <Application>postmaster</Application> - Nothing can happen to a database unless the postmaster + Nothing can happen to a database unless the + postmaster process is running. As the site administrator, there are a number of things you should remember before - starting the postmaster. These are discussed in the - section of this manual titled, "Administering Postgres." + starting the postmaster. +These are discussed in the installation and configuration sections +of this manual. However, if Postgres 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 % postmaster - The postmaster occasionally prints out messages which + The postmaster occasionally prints out +messages which are often helpful during troubleshooting. If you wish - to view debugging messages from the postmaster, you can + to view debugging messages from the postmaster, +you can start it with the -d option and redirect the output to the log file: @@ -184,7 +36,8 @@ There is one evident drawback of using locale - it's speed! So, use locale only % postmaster -S - and the postmaster will be "S"ilent. Notice that there + and the postmaster will be "S"ilent. +Notice that there is no ampersand ("&") at the end of the last example. @@ -194,9 +47,12 @@ There is one evident drawback of using locale - it's speed! So, use locale only createuser enables specific users to access - Postgres. destroyuser removes users and - prevents them from accessing Postgres. Note that these - commands only affect users with respect to Postgres; + Postgres. +destroyuser removes users and + prevents them from accessing Postgres. +Note that these + commands only affect users with respect to +Postgres; they have no effect on users other privileges or status with regards to the underlying operating system. @@ -242,7 +98,8 @@ PGDATA2 pointing to /home/postgres/data, type -Usually, you will want to define this variable in the Postgres superuser's +Usually, you will want to define this variable in the +Postgres superuser's .profile or .cshrc @@ -274,7 +131,8 @@ To test the new location, create a database test by typing Assuming that your site administrator has properly - started the postmaster process and authorized you to + started the postmaster process +and authorized you to use the database, you (as a user) may begin to start up applications. As previously mentioned, you should add /usr/local/pgsql/bin to your shell search path. @@ -282,10 +140,12 @@ To test the new location, create a database test by typing terms of preparation. - If you get the following error message from a Postgres - command (such as psql or createdb): + If you get the following error message from a +Postgres + command (such as psql or +createdb): -connectDB() failed: Is the postmaster running at 'localhost' on port '4322'? +connectDB() failed: Is the postmaster running at 'localhost' on port '5432'? it is usually because either the postmaster 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) Managing a Database - Now that Postgres is up and running we can create some - databases to experiment with. Here, we describe the + Now that Postgres is up and running we can create + some databases to experiment with. Here, we describe the basic commands for managing a database. @@ -318,12 +178,15 @@ FATAL 1:Feb 17 23:19:55:process userid (2360) != database owner (268) % createdb mydb - Postgres allows you to create any number of databases + Postgres 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 Postgres refuses to create databases + administrator. If Postgres +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) -running the Postgres terminal monitor programs ( - monitor or psql) which allows you to interactively +running the Postgres terminal monitor program +(psql) which allows you to interactively enter, edit, and execute SQL commands. - writing a C program using the LIBPQ subroutine + writing a C program using the libpq subroutine library. This allows you to submit SQL commands from C and get answers and status messages back to your program. This interface is discussed further - in section ??. + in the PostgreSQL Programmer's Guide. - You might want to start up psql, to try out the examples in this manual. It can be activated for the mydb + You might want to start up psql, +to try out the examples in this manual. It can be activated for the mydb database by typing the command: % psql mydb @@ -376,11 +240,14 @@ mydb=> -This prompt indicates that the terminal monitor is listening to you and that you can type SQL queries into a +This prompt indicates that the terminal monitor is listening +to you and that you can type SQL queries into a workspace maintained by the terminal monitor. - The psql program responds to escape codes that begin + The psql program responds to escape + codes that begin with the backslash character, "\". For example, you - can get help on the syntax of various Postgres SQL commands by typing: + can get help on the syntax of various +Postgres SQL commands by typing: mydb=> \h @@ -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. psql will automatically process semicolon terminated queries. + necessary. psql will automatically +process semicolon terminated queries. To read queries from a file, say myFile, instead of entering them interactively, type: @@ -406,11 +274,13 @@ mydb=> \i fileName mydb=> \q - and psql will quit and return you to your command + and psql 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 SQL queries. Single-line comments are denoted by + used freely in SQL queries. +Single-line comments are denoted by --. Everything after the dashes up to the end of the line is ignored. Multiple-line comments, and comments within a line, are denoted by /* ... */ diff --git a/doc/src/sgml/syntax.sgml b/doc/src/sgml/syntax.sgml new file mode 100644 index 0000000000..3922b89b16 --- /dev/null +++ b/doc/src/sgml/syntax.sgml @@ -0,0 +1,265 @@ + +SQL Syntax + + +Key Words + + +SQL92 defines key words for the language +which have specific meaning. Some key words are +reserved, which indicates that they are +restricted to appear in only certain contexts. Other key words are +not restricted, which indicates that in certain contexts they +have a specific meaning but are not otherwise constrained. + + +Postgres implements an extended subset of the +SQL92 and SQL3 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 Postgres. + + +Information on SQL92 and SQL3 key words +is derived from . + + +Reserved Key Words + + +SQL92 and SQL3 have +reserved key words which are not allowed +as identifiers and not allowed in any usage other than as fundamental +tokens in SQL statements. +Postgres 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). + + + +Any string can be specified as an identifier if surrounded by +double quotes (like this!). Some care is required since +such an identifier will be case sensitive +and will retain embedded whitespace. + + + +The following are Postgres +reserved words which are neither SQL92 +nor SQL3 reserved words. These are allowed +to be present as column labels, but not as identifiers: + + +ABORT ANALYZE +BINARY +CLUSTER CONSTRAINT COPY +DO +EXPLAIN EXTEND +LISTEN LOAD LOCK +MOVE +NEW NONE NOTIFY +RESET +SETOF SHOW +UNLISTEN UNTIL +VACUUM VERBOSE + + +The following are Postgres +reserved words which are also SQL92 +or SQL3 reserved words, and which +are allowed to be present as column labels, but not as identifiers: + + +CROSS CURRENT +FALSE FOREIGN +GROUP +ORDER +POSITION PRECISION +TABLE TRANSACTION TRUE + + +The following are Postgres +reserved words which are also SQL92 +or SQL3 reserved words: + + +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 + + +The following are SQL92 reserved key words which +are not Postgres reserved key words, but which +if used as function names are always translated into the function +length: + + +CHAR_LENGTH CHARACTER_LENGTH + + +The following are SQL92 or SQL3 +reserved key words which +are not Postgres reserved key words, but +if used as type names which are always translated into an alternate, native type: + + +BOOLEAN DOUBLE FLOAT INT INTEGER INTERVAL REAL SMALLINT + + + +The following are either SQL92 +or SQL3 reserved key words +which are not key words in Postgres. +These have no proscribed usage in Postgres +at the time of writing (v6.4) but may become reserved key words in the +future: + + + +Some of these key words represent functions in SQL92. +These functions are defined in Postgres, +but the parser does not consider the names to be key words and they are allowed +in other contexts. + + + +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 + + + +Non-reserved Keywords + + +SQL92 and SQL3 have +non-reserved keywords which have +a proscribed meaning in the language but which are also allowed +as identifiers. +Postgres has additional keywords +which allow similar unrestricted usage. +In particular, these keywords +are allowed as column or table names. + + +The following are Postgres +non-reserved key words which are neither SQL92 +nor SQL3 non-reserved key words: + + +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 + + + +The following are Postgres +non-reserved key words which are SQL92 +or SQL3 reserved key words: + + +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 + + + +The following are Postgres +non-reserved key words which are also either SQL92 +or SQL3 non-reserved key words: + + +TYPE + + + +The following are either SQL92 +or SQL3 non-reserved key words which are not +key words of any kind in Postgres: + + +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 + diff --git a/doc/src/sgml/user.sgml b/doc/src/sgml/user.sgml index 8bfc778935..38bd7d942d 100644 --- a/doc/src/sgml/user.sgml +++ b/doc/src/sgml/user.sgml @@ -1,10 +1,19 @@ + + + + + @@ -30,12 +46,13 @@ Include new chapters. + %allfiles; ]> - + @@ -107,6 +124,7 @@ It provides SQL92/SQL3 language support, &intro; &environ; &manage; +&syntax; &datatype; &oper; &func;