database/postgres
database/postgres
1
0
Fork 0
mirror of https://github.com/postgres/postgres.git synced 2025-04-18 13:44:19 +03:00
Code

Support Docs & Contrib

Browse Source
This commit is contained in:
Marc G. Fournier 1996-08-18 22:14:33 +00:00
parent 1960a3b965
commit 9848d3655d
102 changed files with 20187 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
COPYRIGHT Normal file
View File

@ -0,0 +1,22 @@
POSTGRES95 Data Base Management System
Copyright (c) 1994-6 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 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

283
HISTORY Normal file
View File

@ -0,0 +1,283 @@
Postgres95 1.02 Thu Aug 1 18:00:00 EDT 1996
-------------------------------------------------------------
Source code maintainenance and development
* worldwide team of volunteers
* the source tree now in CVS at ftp.ki.net
* developers mailing list - pg95-dev@ki.net
Enhancements
* psql (and underlying libpq library) now has many more options for
formatting output, including HTML
* pg_dump now output the schema and/or the data, with many fixes to
enhance completeness.
* psql used in place of monitor in administration shell scripts.
monitor to be depreciated in next release.
* date/time functions enhanced
* NULL insert/update/comparison fixed/enhanced
* TCL/TK lib and shell fixed to work with both tck7.4/tk4.0 and tcl7.5/tk4.1
Bug Fixes (almost too numerous to mention)
* indexes
* storage management
* check for NULL pointer before dereferencing
* Makefile fixes
New Ports
* added SolarisX86 port
* added BSDI 2.1 port
* added DGUX port
Contributors (appologies to any missed)
* Kurt J. Lidl <lidl@va.pubnix.com>
(missed in first run, but no less important)
* Erich Stamberger <eberger@gewi.kfunigraz.ac.at>
* Jason Wright <jason@shiloh.vnet.net>
* Cees de Groot <C.deGroot@inter.NL.net>
* ernst.molitor@uni-bonn.de
* michael.siebenborn@ae3.Hypo.DE (Michael Siebenborn (6929))
* Brian E. Gallew <geek+@cmu.edu>
* Vadim B. Mikheev <vadim@sable.krasnoyarsk.su>
* Adam Sussman <myddryn@vidya.com>
* Chris Dunlop <chris@onthe.net.au>
* Marc G. Fournier <scrappy@ki.net>
* Dan McGuirk <mcguirk@indirect.com>
* Dr_George_D_Detlefsen <drgeorge@ilt.com>
* Erich Stamberger <eberger@gewi.kfunigraz.ac.at>
* Massimo Dal Zotto <dz@cs.unitn.it>
* Randy Kunkee <kunkee@Starbase.NeoSoft.COM>
* Rick Weldon <rick@wisetech.com>
* Thomas van Reimersdahl <reimersd@dali.techinfo.rwth-aachen.de>
* david bennett <dave@bensoft.com>
* ernst.molitor@uni-bonn.de
* Julian Assange <proff@suburbia.net>
* Bruce Momjian <maillist@candle.pha.pa.us>
* Paul "Shag" Walmsley <ccshag@cclabs.missouri.edu>
* "Alistair G. Crooks" <azcb0@sde.uts.amdahl.com>
Postgres95 1.01 Fri Feb 23 18:20:36 PST 1996
-------------------------------------------------------------
Incompatibilities:
* 1.01 is backwards compatible with 1.0 database provided the user
follow the steps outlined in the MIGRATION_from_1.0_to_1.01 file.
If those steps are not taken, 1.01 is not compatible with 1.0 database.
Enhancements:
* added PQdisplayTuples() to libpq and changed monitor and psql to use it
* added NeXT port (requires SysVIPC implementation)
* added CAST .. AS ... syntax
* added ASC and DESC keywords
* added 'internal' as a possible language for CREATE FUNCTION
internal functions are C functions which have been statically linked
into the postgres backend.
* a new type "name" has been added for system identifiers (table names,
attribute names, etc.) This replaces the old char16 type. The
of name is set by the NAMEDATALEN #define in src/Makefile.global
* a readable reference manual that describes the query language.
* added host-based access control. A configuration file ($PGDATA/pg_hba)
is used to hold the configuration data. If host-based access control
is not desired, comment out HBA=1 in src/Makefile.global.
* changed regex handling to be uniform use of Henry Spencer's regex code
regardless of platform. The regex code is included in the distribution
* added functions and operators for case-insensitive regular expressions.
The operators are ~* and !~*.
* pg_dump uses COPY instead of SELECT loop for better performance
Bug fixes:
* fixed an optimizer bug that was causing core dumps when
functions calls were used in comparisons in the WHERE clause
* changed all uses of getuid to geteuid so that effective uids are used
* psql now returns non-zero status on errors when using -c
* applied public patches 1-14
Postgres95 1.0 Tue Sep 5 11:24:11 PDT 1995
-------------------------------------------------------------
Copyright change:
* The copyright of Postgres 1.0 has been loosened to be freely modifiable
and modifiable for any purpose. Please read the COPYRIGHT file.
Thanks to Professor Michael Stonebraker for making this possible.
Incompatibilities:
* date formats have to be MM-DD-YYYY (or DD-MM-YYYY if you're using
EUROPEAN STYLE). This follows SQL-92 specs.
* "delimiters" is now a keyword
Enhancements:
* sql LIKE syntax has been added
* copy command now takes an optional USING DELIMITER specification.
delimiters can be any single-character string.
* IRIX 5.3 port has been added.
Thanks to Paul Walmsley (ccshag@everest.cclabs.missouri.edu) and others.
* updated pg_dump to work with new libpq
* \d has been added psql
Thanks to Keith Parks (emkxp01@mtcc.demon.co.uk)
* regexp performance for architectures that use POSIX regex has been
improved due to caching of precompiled patterns.
Thanks to Alistair Crooks (agc@uts.amdahl.com)
* a new version of libpq++
Thanks to William Wanders (wwanders@sci.kun.nl)
Bug fixes:
* arbitrary userids can be specified in the createuser script
* \c to connect to other databases in psql now works.
* bad pg_proc entry for float4inc() is fixed
* users with usecreatedb field set can now create databases without
having to be usesuper
* remove access control entries when the entry no longer has any
permissions
* fixed non-portable datetimes implementation
* added kerberos flags to the src/backend/Makefile
* libpq now works with kerberos
* typographic errors in the user manual have been corrected.
* btrees with multiple index never worked, now we tell you they don't
work when you try to use them
Postgres95 Beta 0.03 Fri Jul 21 14:49:31 PDT 1995
------------------------------------------------------
Incompatible changes:
* BETA-0.3 IS INCOMPATIBLE WITH DATABASES CREATED WITH PREVIOUS VERSIONS
(due to system catalog changes and indexing structure changes).
* double-quote (") is deprecated as a quoting character for string literals;
you need to convert them to single quotes (').
* name of aggregates (eg. int4sum) are renamed in accordance with the
SQL standard (eg. sum).
* CHANGE ACL syntax is replaced by GRANT/REVOKE syntax.
* float literals (eg. 3.14) are now of type float4 (instead of float8 in
previous releases); you might have to do typecasting if you depend on it
being of type float8. If you neglect to do the typecasting and you assign
a float literal to a field of type float8, you may get incorrect values
stored!
* LIBPQ has been totally revamped so that frontend applications
can connect to multiple backends
* the usesysid field in pg_user has been changed from int2 to int4 to
allow wider range of Unix user ids.
* the netbsd/freebsd/bsd o/s ports have been consolidated into a
single BSD44_derived port. (thanks to Alistair Crooks)
SQL standard-compliance (the following details changes that makes postgres95
more compliant to the SQL-92 standard):
* the following SQL types are now built-in: smallint, int(eger), float, real,
char(N), varchar(N), date and time.
The following are aliases to existing postgres types:
smallint -> int2
integer, int -> int4
float, real -> float4
char(N) and varchar(N) are implemented as truncated text types. In
addition, char(N) does blank-padding.
* single-quote (') is used for quoting string literals; '' (in addition to
\') is supported as means of inserting a single quote in a string
* SQL standard aggregate names (MAX, MIN, AVG, SUM, COUNT) are used
(Also, aggregates can now be overloaded, i.e. you can define your
own MAX aggregate to take in a user-defined type.)
* CHANGE ACL removed. GRANT/REVOKE syntax added.
- Privileges can be given to a group using the "GROUP" keyword.
For example:
GRANT SELECT ON foobar TO GROUP my_group;
The keyword 'PUBLIC' is also supported to mean all users.
Privileges can only be granted or revoked to one user or group
at a time.
"WITH GRANT OPTION" is not supported. Only class owners can change
access control
- The default access control is to to grant users readonly access.
You must explicitly grant insert/update access to users. To change
this, modify the line in
src/backend/utils/acl.h
that defines ACL_WORLD_DEFAULT
Bug fixes:
* the bug where aggregates of empty tables were not run has been fixed. Now,
aggregates run on empty tables will return the initial conditions of the
aggregates. Thus, COUNT of an empty table will now properly return 0.
MAX/MIN of an empty table will return a tuple of value NULL.
* allow the use of \; inside the monitor
* the LISTEN/NOTIFY asynchronous notification mechanism now work
* NOTIFY in rule action bodies now work
* hash indices work, and access methods in general should perform better.
creation of large btree indices should be much faster. (thanks to Paul
Aoki)
Other changes and enhancements:
* addition of an EXPLAIN statement used for explaining the query execution
plan (eg. "EXPLAIN SELECT * FROM EMP" prints out the execution plan for
the query).
* WARN and NOTICE messages no longer have timestamps on them. To turn on
timestamps of error messages, uncomment the line in
src/backend/utils/elog.h:
/* define ELOG_TIMESTAMPS */
* On an access control violation, the message
"Either no such class or insufficient privilege"
will be given. This is the same message that is returned when
a class is not found. This dissuades non-privileged users from
guessing the existence of privileged classes.
* some additional system catalog changes have been made that are not
visible to the user.
libpgtcl changes:
* The -oid option has been added to the "pg_result" tcl command.
pg_result -oid returns oid of the last tuple inserted. If the
last command was not an INSERT, then pg_result -oid returns "".
* the large object interface is available as pg_lo* tcl commands:
pg_lo_open, pg_lo_close, pg_lo_creat, etc.
Portability enhancements and New Ports:
* flex/lex problems have been cleared up. Now, you should be able to use
flex instead of lex on any platforms. We no longer make assumptions of
what lexer you use based on the platform you use.
* The Linux-ELF port is now supported. Various configuration have been
tested: The following configuration is known to work:
kernel 1.2.10, gcc 2.6.3, libc 4.7.2, flex 2.5.2, bison 1.24
with everything in ELF format,
New utilities:
* ipcclean added to the distribution
ipcclean usually does not need to be run, but if your backend crashes
and leaves shared memory segments hanging around, ipcclean will
clean them up for you.
New documentation:
* the user manual has been revised and libpq documentation added.
Postgres95 Beta 0.02 (Thu May 25 16:54:46 PDT 1995)
------------------------------------------------------
Incompatible changes:
* The SQL statement for creating a database is 'CREATE DATABASE' instead
of 'CREATEDB'. Similarly, dropping a database is 'DROP DATABASE' instead
of 'DESTROYDB'. However, the names of the executables 'createdb' and
'destroydb' remain the same.
New tools:
* pgperl - a Perl (4.036) interface to Postgres95
* pg_dump - a utility for dumping out a postgres database into a
script file containing query commands. The script files are in a ASCII
format and can be used to reconstruct the database, even on other
machines and other architectures. (Also good for converting
a Postgres 4.2 database to Postgres95 database.)
The following ports have been incorporated into postgres95-beta-0.02:
* the NetBSD port by Alistair Crooks
* the AIX port by Mike Tung
* the Windows NT port by Jon Forrest (more stuff but not done yet)
* the Linux ELF port by Brian Gallew
The following bugs have been fixed in postgres95-beta-0.02:
* new lines not escaped in COPY OUT and problem with COPY OUT when first
attribute is a '.'
* cannot type return to use the default user id in createuser
* SELECT DISTINCT on big tables crashes
* Linux installation problems
* monitor doesn't allow use of 'localhost' as PGHOST
* psql core dumps when doing \c or \l
* the "pgtclsh" target missing from src/bin/pgtclsh/Makefile
* libpgtcl has a hard-wired default port number
* SELECT DISTINCT INTO TABLE hangs
* CREATE TYPE doesn't accept 'variable' as the internallength
* wrong result using more than 1 aggregate in a SELECT
Postgres95 Beta 0.01 (Mon May 1 19:03:10 PDT 1995)
------------------------------------------------------
Initial release.

256
INSTALL Normal file
View File

@ -0,0 +1,256 @@
POSTGRES95 INSTALLATION INSTRUCTIONS
Copyright (c) 1996 Regents of the University of California
This directory contains the source and documentation for Postgres95
(version 1.02) Postgres95 is a derivative of POSTGRES 4.2 (the last
release of the UC Berkeley research project). For copyright terms
for postgres95, please see the file named COPYRIGHT. This version
was developed by a team of developers on the postgres developers
mailing list. Version 1.01 was developed by Jolly Chen and Andrew Yu.
Postgres95 has been tested on the following platforms:
alpha - DEC Alpha AXP on OSF/1 2.0
hpux - HP PA-RISC on HP-UX 9.0
i386_solaris - i386 Solaris
sparc_solaris - SUN SPARC on Solaris 2.4
sparc - SUN SPARC on SunOS 4.1.3
ultrix4 - DEC MIPS on Ultrix 4.4
linux - Intel x86 on Linux 1.2 and Linux ELF
BSD44_derived - OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
bsdi - BSD/OS 2.0 and 2.01
bsdi_2_1 - BSD/OS 2.1
aix - IBM on AIX 3.2.5
irix5 - SGI MIPS on IRIX 5.3
dgux - DG/UX 5.4R3.10
Some hooks are provided for
svr4 - Intel x86 on Intel SVR4
next - Motorola MC68K or Intel x86 on NeXTSTEP 3.2
but these are guaranteed not to work as of yet.
Postgres95 is also known to work on a number of other platforms that
the authors have not personally tested.
You should have at least 8 MB of memory and at least 30 MB of disk space to
hold the source, binaries, and user databases.
If you would like to migrate your databases from postgres 1.0 to
postgres 1.02, see the directory called MIGRATION_1.0_TO_1.02. People
upgrading from version 1.01 do not have to make any database changes.
----------------------------------------------------------------------
To install Postgres95 on UNIX platforms:
1. Create the postgres login.
Create a login called postgres (this requires root privileges). We
recommend that you run the postmaster as the user postgres for security
reasons.
If you run the postmaster as yourself, be warned that you essentially
grant all database users the ability to execute arbitrary C functions
as you without your password. (In any case, DO NOT run the postmaster
as root.)
2. Compile and install Postgres95.
If you have earlier versions of Postgres installed, you might want
to install Postgres95 in a different place.
If you're installing Postgres95 on Ultrix 4.x or Linux, see the
porting notes at the end for additional packages that you need to install
before installing Postgres95.
Our Makefiles require GNU make (called gmake in this document) and
also assume that "install" accepts BSD options. The INSTALL
variable in the Makefiles is set to the BSD-compatible version of
install. On some systems, you will have to find a BSD-compatible
install to the location of this program. (eg. bsdinst, which comes
with the MIT X Window System distribution)
Customization can be done by editing src/Makefile.global. You may change
the various configuration options here, such as where the Postgres95
executable files are installed and where postgres looks for the database
directory. The configuration switches are fairly self-explanatory, but we
will go over some of the more commonly-changed options:
- PORTNAME specifies the platform on which Postgres95 is being build
(linux is the default). You might need to change it to reflect your
platform. (sparc for SunOS 4.1.x, sparc_solaris for Solaris 2.4,
ultrix4 for Ultrix 4.4, and hpux for HP-UX 9.0)
- SRCDIR specifies where the source files are located. (defaults
to $(POSTGRESDIR)/src.)
- POSTSGRESDIR specifies the top-level directory where Postgres95
binaries, header files, libraries, and databases are installed.
- POSTGRESLOGIN specifies the user who will be doing initdb and
running the postmaster (defaults to postgres). Do not set
this to root, or any users with UID = 0!
- NAMEDATALEN and OIDNAMELEN allows you to set the maximum
length of system identifiers (table names, function names, etc.)
It defaults to 32. You may alter this if you like, but
be aware that databases created with different NAMEDATALEN's
do not interoperate.
- USE_READLINE specifies whether you want to use the GNU
readline and history libraries for the psql interactive
frontend program.
GNU readline is not supplied with postgres95 and can be found
in the usual ftp sites for GNU software.
- HBA specifies whether you wish to use host-based
authentication for postgres95. If you do use host-based
authentication, after installing, modify the file
$PGDATA/pg_hba accordingly.
After editing src/Makefile.global, you are ready to compile and
install Postgres95 (it takes about 10 minutes on a 133Mhz Pentium
running linux):
% cd src
% gmake
% gmake install
The first gmake ultimately issues the message "All of Postgres95 is
successfully made. Ready to install." If you don't get that, the make
failed, and there should be error messages at the end detailing why.
After the installation is complete, check that you have the following files
in the top level Postgres95 directory (eg. /usr/local/postgres95).
You will find the following executables in the bin directory (which
should be included in the search path of your shell):
% ls /usr/local/postgres95/bin
cleardbdir* destroydb* pg_dump* postgres*
createdb* destroyuser* pg_id* postmaster@
createuser* initdb* pg_version* psql*
You will find the following in the database directory:
% ls -R /usr/local/postgres95/data
files/
pg_hba
data/files:
global1.bki local1_template1.bki
global1.bki.source local1_template1.bki.source
3. Initialize the database.
After you have installed Postgres95, initialize the database by typing:
% initdb
4. Start the postmaster.
Now, you are ready to make the system operational by running the
postmaster daemon. There are a few environment variables which affect
its operation:
PGDATA - location of the database (eg. /usr/local/postgres95/data)
PGPORT - TCP port where it listens for connection (eg. 5432)
You don't have to set these variables if you use the (compile time)
default.
% postmaster -S
5. Testing.
We suggest you run the regression tests to make sure the release
was installed successfully. The regression tests can be found in
src/test/regress. (see src/test/regress/README for more details)
% cd /usr/local/postgres95/src/test/regress
% gmake all runtest
This will run a whole slew of regression tests and might take a long
time to run. When it's done, the output is in the file obj/regress.out.
You can compare this to a sample run that we supply in the file
sample.regress.out. (You should get roughly the same output except
for some pathnames.)
% diff obj/regress.out sample.regress.out
The regression test takes about half an hour to run on a Sparc 10.
You may want to use 'grep -v' to remove unsignificant differences.
6. Run queries.
After the database is initialized, you can create a new database. To
create a database, do the following:
% createdb foo
To connect to the postmaster, you have a choice of two front-end programs.
("psql" is recommended. "monitor" is the old terminal monitor
supplied in earlier versions of Postgres)
% psql foo
Please read the file COPYRIGHT for copyright terms of POSTGRES95
type \? for help on slash commands
type \q to quit
type \g or terminate with semicolon to execute query
You are currently connected to the database: foo
foo=>
----------------------------------------------------------------------
Questions? Bugs? Feedback?
First, please read the Frequently Asked Questions and answers
in the file called FAQ.
If you still have questions, please send them to
postgres95@postgres95.vnet.net.
If you have a bug report to make, please send a filled out version of
the file named "bug.template" to pg95-dev@ki.net.
If you would like to help out with the development and maintenance of
postgres95, send subscribe to the developers mailing list. See
README.support for more information
----------------------------------------------------------------------
Porting Notes:
-------------
Ultrix4.x:
You need to install the libdl-1.1 package since Ultrix 4.x doesn't
have a dynamic loader. It's available in
s2k-ftp.CS.Berkeley.EDU:pub/personal/andrew/libdl-1.1.tar.Z
Linux:
The linux port defaults to the ELF binary format. (Note that if you're
using ELF, you don't need dld because you'll be using the dl library
that comes with Linux ELF instead.)
To compile on non-ELF Linux, comment out the LINUX_ELF line in
src/mk/port/postgres.mk.linux. Also, the dld library MUST be obtained
and installed on the system. It enables dynamic link loading capability
to the postgres port. The dld library can be obtained from the sunsite
linux distributions. The current name is dld-3.2.5.
(Jalon Q. Zimmerman
<sneaker@powergrid.electriciti.com> 5/11/95)
To compile with flex, you need a recent version (2.5.2 or
later). Otherwise, you will get a 'yy_flush_buffer' undefined error.
BSD/OS:
For BSD/OS 2.0 and 2.01, you will need to get flex version 2.5.2
as well as the GNU dld library. Flex version 2.5.3 has a known bug.
NeXT:
The NeXT port was supplied by Tom R. Hageman <tom@basil.icce.rug.nl>.
It requires a SysV IPC emulation library and header files for
shared libary and semaphore stuff. Tom just happens to sell such
a product so contact him for information. He has also indicated that
binary releases of postgres95 for NEXTSTEP will be made available to
the general public. Contact Info@RnA.nl for information.

10
MAKE_CTAGS Normal file
View File

@ -0,0 +1,10 @@
#!/bin/sh
trap "rm -f /tmp/$$" 0 1 2 3 15
rm -f ./tags
find `pwd`/ -type f -name '*.[chyl]' -print|xargs ctags -t -a -f tags
sort tags >/tmp/$$ && mv /tmp/$$ tags
find . -type d -print |while read DIR
do
[ "$DIR" != "." ] && ln -f -s `pwd`/tags $DIR/tags
done

73
MIGRATION_to_1.02.1 Normal file
View File

@ -0,0 +1,73 @@
From scrappy@ki.net Wed Aug 14 20:41:08 1996
Status: RO
X-Status:
Received: from candle.pha.pa.us (maillist@s1-03.ppp.op.net [206.84.209.132]) by quagmire.ki.net (8.7.5/8.7.5) with ESMTP id UAA01234 for <scrappy@ki.net>; Wed, 14 Aug 1996 20:41:00 -0400 (EDT)
Received: (from maillist@localhost) by candle.pha.pa.us (8.7.4/8.7.3) id UAA13966 for scrappy@ki.net; Wed, 14 Aug 1996 20:40:48 -0400 (EDT)
From: Bruce Momjian <maillist@candle.pha.pa.us>
Message-Id: <199608150040.UAA13966@candle.pha.pa.us>
Subject: New migration file
To: scrappy@ki.net (Marc G. Fournier)
Date: Wed, 14 Aug 1996 20:40:47 -0400 (EDT)
X-Mailer: ELM [version 2.4 PL25]
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Here is a new migratoin file for 1.02.1. It includes the 'copy' change
and a script to convert old ascii files.
---------------------------------------------------------------------------
The following notes are for the benefit of users who want to migrate
databases from postgres95 1.01 and 1.02 to postgres95 1.02.1.
If you are starting afresh with postgres95 1.02.1 and do not need
to migrate old databases, you do not need to read any further.
----------------------------------------------------------------------
In order to upgrade older postgres95 version 1.01 or 1.02 databases to
version 1.02.1, the following steps are required:
1) start up a new 1.02.1 postmaster
2) Add the new built-in functions and operators of 1.02.1 to 1.01 or 1.02
databases. This is done by running the new 1.02.1 server against
your own 1.01 or 1.02 database and applying the queries attached at
the end of thie file. This can be done easily through psql. If your
1.01 or 1.02 database is named "testdb" and you have cut the commands
from the end of this file and saved them in addfunc.sql:
% psql testdb -f addfunc.sql
Those upgrading 1.02 databases will get a warning when executing the
last two statements because they are already present in 1.02. This is
not a cause for concern.
* * *
If you are trying to reload a pg_dump or text-mode 'copy tablename to
stdout' generated with a previous version, you will need to run the
attached sed script on the ASCII file before loading it into the
database. The old format used '.' as end-of-data, while '\.' is now the
end-of-data marker. Also, empty strings are now loaded in as '' rather
than NULL. See the copy manual page for full details.
sed 's/^\.$/\\./g' <in_file >out_file
If you are loading an older binary copy or non-stdout copy, there is no
end-of-data character, and hence no conversion necessary.
---------------------------------------------------------------------------
-- following lines added by agc to reflect the case-insensitive
-- regexp searching for varchar (in 1.02), and bpchar (in 1.02.1)
create operator ~* (leftarg = bpchar, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = bpchar, rightarg = text, procedure = texticregexne);
create operator ~* (leftarg = varchar, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = varchar, rightarg = text, procedure = texticregexne);

36
README Normal file
View File

@ -0,0 +1,36 @@
POSTGRES95 Data Base Management System
This directory contains the 1.02 release of Postgres95. See INSTALL for
the installation notes and HISTORY for the changes.
We also have a WWW home page located at:
http://www.ki.net/postgres95
Postgres95 is not public domain software. It is copyrighted by the
University of California but may be used according to the licensing
terms of the the copyright below:
------------------------------------------------------------------------
POSTGRES95 Data Base Management System
Copyright (c) 1994-6 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 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

251
contrib/array/array_iterator.c Normal file
View File

@ -0,0 +1,251 @@
/*
* array_iterator.c --
*
* This file defines a new group of operators which take an
* array and a scalar value, iterate a scalar operator over the
* elements of the array and the value and compute a result as
* the logical OR or AND of the results.
* For example array_int4eq returns true if some of the elements
* of an array of int4 is equal to the given value:
*
* array_int4eq({1,2,3}, 1) --> true
* array_int4eq({1,2,3}, 4) --> false
*
* If we have defined T array types and O scalar operators
* we can define T x O array operators, each of them has a name
* like "array_<basetype><operation>" and takes an array of type T
* iterating the operator O over all the elements. Note however
* that some of the possible combination are invalid, for example
* the array_int4_like because there is no like operator for int4.
* It is now possible to write queries which look inside the arrays:
*
* create table t(id int4[], txt text[]);
* select * from t where t.id *= 123;
* select * from t where t.txt *~ '[a-z]';
* select * from t where t.txt[1:3] **~ '[a-z]';
*
* Copyright (c) 1996, Massimo Dal Zotto <dz@cs.unitn.it>
*/
#include <ctype.h>
#include <stdio.h>
#include <sys/types.h>
#include <string.h>
#include "postgres.h"
#include "pg_type.h"
#include "miscadmin.h"
#include "syscache.h"
#include "access/xact.h"
#include "utils/builtins.h"
#include "utils/elog.h"
static int32
array_iterator(Oid elemtype, Oid proc, int and, ArrayType *array, Datum value)
{
HeapTuple typ_tuple;
TypeTupleForm typ_struct;
bool typbyval;
int typlen;
func_ptr proc_fn;
int pronargs;
int nitems, i, result;
int ndim, *dim;
char *p;
/* Sanity checks */
if ((array == (ArrayType *) NULL)
|| (ARR_IS_LO(array) == true)) {
/* elog(NOTICE, "array_iterator: array is null"); */
return (0);
}
ndim = ARR_NDIM(array);
dim = ARR_DIMS(array);
nitems = getNitems(ndim, dim);
if (nitems == 0) {
/* elog(NOTICE, "array_iterator: nitems = 0"); */
return (0);
}
/* Lookup element type information */
typ_tuple = SearchSysCacheTuple(TYPOID, ObjectIdGetDatum(elemtype),0,0,0);
if (!HeapTupleIsValid(typ_tuple)) {
elog(WARN,"array_iterator: cache lookup failed for type %d", elemtype);
return 0;
}
typ_struct = (TypeTupleForm) GETSTRUCT(typ_tuple);
typlen = typ_struct->typlen;
typbyval = typ_struct->typbyval;
/* Lookup the function entry point */
proc_fn == (func_ptr) NULL;
fmgr_info(proc, &proc_fn, &pronargs);
if ((proc_fn == NULL) || (pronargs != 2)) {
elog(WARN, "array_iterator: fmgr_info lookup failed for oid %d", proc);
return (0);
}
/* Scan the array and apply the operator to each element */
result = 0;
p = ARR_DATA_PTR(array);
for (i = 0; i < nitems; i++) {
if (typbyval) {
switch(typlen) {
case 1:
result = (int) (*proc_fn)(*p, value);
break;
case 2:
result = (int) (*proc_fn)(* (int16 *) p, value);
break;
case 3:
case 4:
result = (int) (*proc_fn)(* (int32 *) p, value);
break;
}
p += typlen;
} else {
result = (int) (*proc_fn)(p, value);
if (typlen > 0) {
p += typlen;
} else {
p += INTALIGN(* (int32 *) p);
}
}
if (result) {
if (!and) {
return (1);
}
} else {
if (and) {
return (0);
}
}
}
if (and && result) {
return (1);
} else {
return (0);
}
}
/*
* Iterators for type _text
*/
int32
array_texteq(ArrayType *array, char* value)
{
return array_iterator((Oid) 25, /* text */
(Oid) 67, /* texteq */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_texteq(ArrayType *array, char* value)
{
return array_iterator((Oid) 25, /* text */
(Oid) 67, /* texteq */
1, /* logical and */
array, (Datum)value);
}
int32
array_textregexeq(ArrayType *array, char* value)
{
return array_iterator((Oid) 25, /* text */
(Oid) 81, /* textregexeq */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_textregexeq(ArrayType *array, char* value)
{
return array_iterator((Oid) 25, /* text */
(Oid) 81, /* textregexeq */
1, /* logical and */
array, (Datum)value);
}
/*
* Iterators for type _char16. Note that the regexp operators
* take the second argument of type text.
*/
int32
array_char16eq(ArrayType *array, char* value)
{
return array_iterator((Oid) 20, /* char16 */
(Oid) 490, /* char16eq */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_char16eq(ArrayType *array, char* value)
{
return array_iterator((Oid) 20, /* char16 */
(Oid) 490, /* char16eq */
1, /* logical and */
array, (Datum)value);
}
int32
array_char16regexeq(ArrayType *array, char* value)
{
return array_iterator((Oid) 20, /* char16 */
(Oid) 700, /* char16regexeq */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_char16regexeq(ArrayType *array, char* value)
{
return array_iterator((Oid) 20, /* char16 */
(Oid) 700, /* char16regexeq */
1, /* logical and */
array, (Datum)value);
}
/*
* Iterators for type _int4
*/
int32
array_int4eq(ArrayType *array, int4 value)
{
return array_iterator((Oid) 23, /* int4 */
(Oid) 65, /* int4eq */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_int4eq(ArrayType *array, int4 value)
{
return array_iterator((Oid) 23, /* int4 */
(Oid) 65, /* int4eq */
1, /* logical and */
array, (Datum)value);
}
int32
array_int4gt(ArrayType *array, int4 value)
{
return array_iterator((Oid) 23, /* int4 */
(Oid) 147, /* int4gt */
0, /* logical or */
array, (Datum)value);
}
int32
array_all_int4gt(ArrayType *array, int4 value)
{
return array_iterator((Oid) 23, /* int4 */
(Oid) 147, /* int4gt */
1, /* logical and */
array, (Datum)value);
}

26
contrib/array/array_iterator.doc Normal file
View File

@ -0,0 +1,26 @@
From: Massimo Dal Zotto <dz@cs.unitn.it>
Date: Mon, 6 May 1996 01:03:37 +0200 (MET DST)
Subject: [PG95]: new operators for arrays
- -----BEGIN PGP SIGNED MESSAGE-----
Hi,
I have written an extension to Postgres95 which allows to use qualification
clauses based on the values of single elements of arrays.
For example I can now select rows having some or all element of an array
attribute equal to a given value or matching a regular expression:
select * from t where t.foo *= 'bar';
select * from t where t.foo **~ '^ba[rz]';
The scheme is quite general, each operator which operates on a base type can
be iterated over the elements of an array. It seem to work well but defining
each new operators requires writing a different C function. Furthermore in
each function there are two hardcoded OIDs which reference a base type and
a procedure. Not very portable. Can anyone suggest a better and more portable
way to do it ? Do you think this could be a useful feature for next release ?
Here is my code, it can be compiled and loaded as a dynamic module without
need to recompile the backend. I have defined only the few operators I needed,
the list can be extended. Feddback is welcome.

137
contrib/array/array_iterator.sql Normal file
View File

@ -0,0 +1,137 @@
/*
* SQL code
- - -- load the new functions
- - --
load '/home/dz/lib/postgres/array_iterator.so';
- - -- define the array operators *=, **=, *~ and **~ for type _text
- - --
create function array_texteq(_text, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_texteq(_text, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_textregexeq(_text, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_textregexeq(_text, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create operator *= (
leftarg=_text,
rightarg=text,
procedure=array_texteq);
create operator **= (
leftarg=_text,
rightarg=text,
procedure=array_all_texteq);
create operator *~ (
leftarg=_text,
rightarg=text,
procedure=array_textregexeq);
create operator **~ (
leftarg=_text,
rightarg=text,
procedure=array_all_textregexeq);
- - -- define the array operators *=, **=, *~ and **~ for type _char16
- - --
create function array_char16eq(_char16, char16)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_char16eq(_char16, char16)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_char16regexeq(_char16, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_char16regexeq(_char16, text)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create operator *= (
leftarg=_char16,
rightarg=char16,
procedure=array_char16eq);
create operator **= (
leftarg=_char16,
rightarg=char16,
procedure=array_all_char16eq);
create operator *~ (
leftarg=_char16,
rightarg=text,
procedure=array_char16regexeq);
create operator **~ (
leftarg=_char16,
rightarg=text,
procedure=array_all_char16regexeq);
- - -- define the array operators *=, **=, *> and **> for type _int4
- - --
create function array_int4eq(_int4, int4)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_int4eq(_int4, int4)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_int4gt(_int4, int4)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create function array_all_int4gt(_int4, int4)
returns bool
as '/home/dz/lib/postgres/array_iterator.so'
language 'c';
create operator *= (
leftarg=_int4,
rightarg=int4,
procedure=array_int4eq);
create operator **= (
leftarg=_int4,
rightarg=int4,
procedure=array_all_int4eq);
create operator *> (
leftarg=_int4,
rightarg=int4,
procedure=array_int4gt);
create operator **> (
leftarg=_int4,
rightarg=int4,
procedure=array_all_int4gt);
*/
/* end of file */

147
contrib/datetime/datetime_functions.c Normal file
View File

@ -0,0 +1,147 @@
/*
* datetime_functions.c --
*
* This file defines new functions for the time and date data types.
*
* Copyright (c) 1996, Massimo Dal Zotto <dz@cs.unitn.it>
*/
#include <time.h>
#include "postgres.h"
#include "pg_type.h"
#include "utils/palloc.h"
typedef struct DateADT {
char day;
char month;
short year;
} DateADT;
typedef struct TimeADT {
short hr;
short min;
float sec;
} TimeADT;
TimeADT *
time_difference(TimeADT *time1, TimeADT *time2)
{
TimeADT *time = (TimeADT*)palloc(sizeof(TimeADT));
time->sec = time1->sec - time2->sec;
time->min = time1->min - time2->min;
time->hr = time1->hr - time2->hr;
if (time->sec < 0) {
time->sec += 60.0;
time->min--;
} else if (time->sec >= 60.0) {
time->sec -= 60.0;
time->min++;
}
if (time->min < 0) {
time->min += 60;
time->hr--;
} else if (time->min >= 60) {
time->min -= 60;
time->hr++;
}
if (time->hr < 0) {
time->hr += 24;
} else if (time->hr >= 24) {
time->hr -= 24;
}
return (time);
}
TimeADT *
currentTime()
{
time_t current_time;
struct tm *tm;
TimeADT *result = (TimeADT*)palloc(sizeof(TimeADT));
current_time = time(NULL);
tm = localtime(&current_time);
result->sec = tm->tm_sec;
result->min = tm->tm_min;
result->hr = tm->tm_hour;
return (result);
}
int4
currentDate()
{
time_t current_time;
struct tm *tm;
int4 result;
DateADT *date = (DateADT*)&result;
current_time = time(NULL);
tm = localtime(&current_time);
date->day = tm->tm_mday;
date->month = tm->tm_mon+1;
date->year = tm->tm_year+1900;
return (result);
}
int4
hours(TimeADT *time)
{
return (time->hr);
}
int4
minutes(TimeADT *time)
{
return (time->min);
}
int4
seconds(TimeADT *time)
{
int seconds = (int)time->sec;
return (seconds);
}
int4
day(int4 val)
{
DateADT *date = (DateADT*)&val;
return (date->day);
}
int4
month(int4 val)
{
DateADT *date = (DateADT*)&val;
return (date->month);
}
int4
year(int4 val)
{
DateADT *date = (DateADT*)&val;
return (date->year);
}
int4
asMinutes(TimeADT *time)
{
int seconds = (int)time->sec;
return (time->min + 60*time->hr);
}
int4
asSeconds(TimeADT *time)
{
int seconds = (int)time->sec;
return (seconds + 60*time->min + 3600*time->hr);
}

25
contrib/datetime/datetime_functions.doc Normal file
View File

@ -0,0 +1,25 @@
From: Massimo Dal Zotto <dz@cs.unitn.it>
Date: Tue, 14 May 1996 14:31:18 +0200 (MET DST)
Subject: [PG95]: new postgres functions
- -----BEGIN PGP SIGNED MESSAGE-----
Some time ago I read in the mailing list requests of people looking
for more time and date functions. I have now written some of them:
time_difference(time1, time2) ,also defined as operator '-'
hour(time)
minutes(time)
seconds(time)
asMinutes(time)
asSeconds(time)
currentTime()
currentDate()
The file can be compiled as shared library and loaded as dynamic module
without need to recompile the backend. This can also be taken as an example
of the extensibility of postgres (user-defined functions, operators, etc).
I would be nice to see more of these user contributed modules posted to this
list and hopefully accessible from the Postgres home page.

69
contrib/datetime/datetime_functions.sql Normal file
View File

@ -0,0 +1,69 @@
-- SQL code to load and define 'datetime' functions
-- load the new functions
load '/home/dz/lib/postgres/datetime_functions.so';
-- define the new functions in postgres
create function time_difference(time,time)
returns time
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function currentDate()
returns date
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function currentTime()
returns time
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function hours(time)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function minutes(time)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function seconds(time)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function day(date)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function month(date)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function year(date)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function asMinutes(time)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create function asSeconds(time)
returns int4
as '/home/dz/lib/postgres/datetime_functions.so'
language 'c';
create operator - (
leftarg=time,
rightarg=time,
procedure=time_difference);

19
contrib/pginterface/Makefile Normal file
View File

@ -0,0 +1,19 @@
#
# Makefile
#
#
TARGET = pginsert
CFLAGS = -g -Wall -I/u/postgres95/include
LIBS = -L/u/postgres95/lib -lpq
$(TARGET) : pginsert.o pginterface.o halt.o
$(CC) -o $(TARGET) $(XFLAGS) $(CFLAGS) \
pginsert.o pginterface.o halt.o $(LIBS)
clean:
rm -f *.o $(TARGET) log core
install:
make clean
make CFLAGS=-O
install -s -o bin -g bin $(TARGET) /usr/local/bin

42
contrib/pginterface/README Normal file
View File

@ -0,0 +1,42 @@
Pginterface 1.0
Attached is a copy of the Postgres support routines I wrote to allow me
to more cleanly interface to the libpg library, more like a 4gl SQL
interface.
It has several features that may be useful for others:
I have simplified the C code that calls libpq by wrapping all the
functionality of libpq in calls to connectdb(), doquery(), fetch(), and
disconnectdb(). Each call returns a structure or value, so if you need
to do more work with the result, you can. Also, I have a global
variable that allows you to disable the error checking I have added to
the doquery() routine.
I have added a function called fetch(), which allows you to pass
pointers as parameters, and on return the variables are filled with the
data from the binary cursor you opened. These binary cursors are not
useful if you are running the query engine on a system with a different
architecture than the database server. If you pass a NULL pointer, the
column is skipped, and you can use libpq to handle it as you wish.
I have used sigprocmask() to block the reception of certain signals
while the program is executing SQL queries. This prevents a user
pressing Control-C from stopping all the back ends. It blocks SIGHUP,
SIGINT, and SIGTERM, but does not block SIGQUIT or obviously kill -9.
If your platform does not support sigprocmask(), you can remove those
function calls. ( Am I correct that abnormal termination can cause
shared memory resynchronization?)
There is a demo program called pginsert that demonstrates how the
library can be used.
You can create a library of pginterface.c and halt.c, and just include
pginterface.h in your source code.
I am willing to maintain this if people find problems or want additional
functionality.
Bruce Momjian (root@candle.pha.pa.us)

58
contrib/pginterface/halt.c Normal file
View File

@ -0,0 +1,58 @@
/*
**
** halt.c
**
** This is used to print out error messages and exit
*/
#include <varargs.h>
#include <signal.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <errno.h>
/*-------------------------------------------------------------------------
**
** halt - print error message, and call clean up routine or exit
**
**------------------------------------------------------------------------*/
/*VARARGS*/
void halt(va_alist)
va_dcl
{
va_list arg_ptr;
char *format, *pstr;
void (*sig_func)();
va_start(arg_ptr);
format = va_arg(arg_ptr,char *);
if (strncmp(format,"PERROR", 6) != 0)
vfprintf(stderr,format,arg_ptr);
else
{
for (pstr=format+6; *pstr == ' ' || *pstr == ':'; pstr++)
;
vfprintf(stderr,pstr,arg_ptr);
perror("");
}
va_end(arg_ptr);
fflush(stderr);
/* call one clean up function if defined */
if ( (sig_func = signal(SIGTERM, SIG_DFL)) != SIG_DFL &&
sig_func != SIG_IGN)
(*sig_func)(0);
else if ( (sig_func = signal(SIGHUP, SIG_DFL)) != SIG_DFL &&
sig_func != SIG_IGN)
(*sig_func)(0);
else if ( (sig_func = signal(SIGINT, SIG_DFL)) != SIG_DFL &&
sig_func != SIG_IGN)
(*sig_func)(0);
else if ( (sig_func = signal(SIGQUIT, SIG_DFL)) != SIG_DFL &&
sig_func != SIG_IGN)
(*sig_func)(0);
exit(1);
}

7
contrib/pginterface/halt.h Normal file
View File

@ -0,0 +1,7 @@
/*
** halt.h
**
*/
void halt();

98
contrib/pginterface/pginsert.c Normal file
View File

@ -0,0 +1,98 @@
/*
* insert.c
*
*/
#include <stdio.h>
#include <signal.h>
#include <time.h>
#include "halt.h"
#include <libpq-fe.h>
#include "pginterface.h"
int main(int argc, char **argv)
{
char query[4000];
int row =1;
int aint;
float afloat;
double adouble;
char achar[11], achar16[17], abpchar[11], avarchar[51], atext[51];
time_t aabstime;
if (argc != 2)
halt("Usage: %s database\n",argv[0]);
connectdb(argv[1],NULL,NULL,NULL,NULL);
on_error_continue();
doquery("DROP TABLE testfetch");
on_error_stop();
doquery("\
CREATE TABLE testfetch( \
aint int4, \
afloat float4, \
adouble float8, \
achar char, \
achar16 char16, \
abpchar char(10), \
avarchar varchar(50), \
atext text, \
aabstime abstime) \
");
while(1)
{
sprintf(query,"INSERT INTO testfetch VALUES ( \
%d, \
2322.12, \
'923121.0323'::float8, \
'A', \
'Betty', \
'Charley', \
'Doug', \
'Ernie', \
'now' )", row);
doquery(query);
doquery("BEGIN WORK");
doquery("DECLARE c_testfetch BINARY CURSOR FOR \
SELECT * FROM testfetch");
doquery("FETCH ALL IN c_testfetch");
while (fetch(
&aint,
&afloat,
&adouble,
achar,
achar16,
abpchar,
avarchar,
atext,
&aabstime) != END_OF_TUPLES)
printf("int %d\nfloat %f\ndouble %f\nchar %s\nchar16 %s\n\
bpchar %s\nvarchar %s\ntext %s\nabstime %s",
aint,
afloat,
adouble,
achar,
achar16,
abpchar,
avarchar,
atext,
ctime(&aabstime));
doquery("CLOSE c_testfetch");
doquery("COMMIT WORK");
printf("--- %-d rows inserted so far\n",row);
row++;
}
disconnectdb();
return 0;
}

177
contrib/pginterface/pginterface.c Normal file
View File

@ -0,0 +1,177 @@
/*
* pginterface.c
*
*/
#include <stdio.h>
#include <signal.h>
#include <string.h>
#include <stdarg.h>
#include "halt.h"
#include <libpq-fe.h>
#include "pginterface.h"
static void sig_disconnect();
static void set_signals();
#define NUL '\0'
/* GLOBAL VARIABLES */
static PGconn* conn;
static PGresult* res = NULL;
#define ON_ERROR_STOP 0
#define ON_ERROR_CONTINUE 1
static int on_error_state = ON_ERROR_STOP;
/* LOCAL VARIABLES */
static sigset_t block_sigs, unblock_sigs;
static int tuple;
/*
**
** connectdb - returns PGconn structure
**
*/
PGconn *connectdb( char *dbName,
char *pghost,
char *pgport,
char *pgoptions,
char *pgtty)
{
/* make a connection to the database */
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
if (PQstatus(conn) == CONNECTION_BAD)
halt("Connection to database '%s' failed.\n%s\n", dbName,
PQerrorMessage(conn));
set_signals();
return conn;
}
/*
**
** disconnectdb
**
*/
void disconnectdb()
{
PQfinish(conn);
}
/*
**
** doquery - returns PGresult structure
**
*/
PGresult *doquery(char *query)
{
if (res != NULL)
PQclear(res);
sigprocmask(SIG_SETMASK,&block_sigs,NULL);
res = PQexec(conn, query);
sigprocmask(SIG_SETMASK,&unblock_sigs,NULL);
if (on_error_state == ON_ERROR_STOP &&
(res == NULL ||
PQresultStatus(res) == PGRES_BAD_RESPONSE ||
PQresultStatus(res) == PGRES_NONFATAL_ERROR ||
PQresultStatus(res) == PGRES_FATAL_ERROR))
{
if (res != NULL)
fprintf(stderr,"query error: %s\n",PQcmdStatus(res));
else fprintf(stderr,"connection error: %s\n",PQerrorMessage(conn));
PQfinish(conn);
halt("failed request: %s\n", query);
}
tuple = 0;
return res;
}
/*
**
** fetch - returns tuple number (starts at 0), or the value END_OF_TUPLES
** NULL pointers are skipped
**
*/
int fetch(void *param, ...)
{
va_list ap;
int arg, num_args;
num_args = PQnfields(res);
if (tuple >= PQntuples(res))
return END_OF_TUPLES;
va_start(ap, param);
for (arg = 0; arg < num_args; arg++)
{
if (param != NULL)
{
if (PQfsize(res, arg) == -1)
{
memcpy(param,PQgetvalue(res,tuple,arg),PQgetlength(res,tuple,arg));
((char *)param)[PQgetlength(res,tuple,arg)] = NUL;
}
else
memcpy(param,PQgetvalue(res,tuple,arg),PQfsize(res,arg));
}
param = va_arg(ap, char *);
}
va_end(ap);
return tuple++;
}
/*
**
** on_error_stop
**
*/
void on_error_stop()
{
on_error_state = ON_ERROR_STOP;
}
/*
**
** on_error_continue
**
*/
void on_error_continue()
{
on_error_state = ON_ERROR_CONTINUE;
}
/*
**
** sig_disconnect
**
*/
static void sig_disconnect()
{
fprintf(stderr,"exiting...\n");
PQfinish(conn);
exit(1);
}
/*
**
** set_signals
**
*/
static void set_signals()
{
sigemptyset(&block_sigs);
sigemptyset(&unblock_sigs);
sigaddset(&block_sigs,SIGTERM);
sigaddset(&block_sigs,SIGHUP);
sigaddset(&block_sigs,SIGINT);
/* sigaddset(&block_sigs,SIGQUIT); no block */
sigprocmask(SIG_SETMASK,&unblock_sigs,NULL);
signal(SIGTERM,sig_disconnect);
signal(SIGHUP,sig_disconnect);
signal(SIGINT,sig_disconnect);
signal(SIGQUIT,sig_disconnect);
}

13
contrib/pginterface/pginterface.h Normal file
View File

@ -0,0 +1,13 @@
/*
* pglib.h
*
*/
PGresult *doquery(char *query);
PGconn *connectdb();
void disconnectdb();
int fetch(void *param, ...);
void on_error_continue();
void on_error_stop();
#define END_OF_TUPLES (-1)

83
contrib/soundex/soundex.c Normal file
View File

@ -0,0 +1,83 @@
/*****************************************************************************/
/* soundex.c */
/*****************************************************************************/
#include <string.h>
#include <stdio.h>
#include "postgres.h" /* for char16, etc. */
#include "utils/palloc.h" /* for palloc */
#include "libpq-fe.h" /* for TUPLE */
#include <stdio.h>
#include <ctype.h>
/* prototype for soundex function */
char *soundex(char *instr, char *outstr);
text *text_soundex(text *t)
{
/* ABCDEFGHIJKLMNOPQRSTUVWXYZ */
char *table = "01230120022455012623010202";
int count = 0;
text *new_t;
char outstr[6+1]; /* max length of soundex is 6 */
char *instr;
/* make a null-terminated string */
instr=palloc(VARSIZE(t)+1);
memcpy(instr,VARDATA(t),VARSIZE(t)-VARHDRSZ);
instr[VARSIZE(t)-VARHDRSZ] = (char)0;
/* load soundex into outstr */
soundex(instr, outstr);
/* Now the outstr contains the soundex of instr */
/* copy outstr to new_t */
new_t = (text *) palloc(strlen(outstr)+VARHDRSZ);
memset(new_t, 0, strlen(outstr)+1);
VARSIZE(new_t) = strlen(outstr)+VARHDRSZ;
memcpy((void *) VARDATA(new_t),
(void *) outstr,
strlen(outstr));
/* free instr */
pfree(instr);
return(new_t);
}
char *soundex(char *instr, char *outstr)
{ /* ABCDEFGHIJKLMNOPQRSTUVWXYZ */
char *table = "01230120022455012623010202";
int count = 0;
while(!isalpha(instr[0]) && instr[0])
++instr;
if(!instr[0]) { /* Hey! Where'd the string go? */
outstr[0]=(char)0;
return outstr;
}
if(toupper(instr[0]) == 'P' && toupper(instr[1]) == 'H') {
instr[0] = 'F';
instr[1] = 'A';
}
*outstr++ = (char)toupper(*instr++);
while(*instr && count < 5) {
if(isalpha(*instr) && *instr != *(instr-1)) {
*outstr = table[toupper(instr[0]) - 'A'];
if(*outstr != '0') {
++outstr;
++count;
}
}
++instr;
}
*outstr = '\0';
return(outstr);
}

57
contrib/soundex/soundex.sql Normal file
View File

@ -0,0 +1,57 @@
--------------- soundex.sql:
CREATE FUNCTION text_soundex(text) RETURNS text
AS '/usr/local/postgres/postgres95/src/funcs/soundex.so' LANGUAGE 'c';
SELECT text_soundex('hello world!');
CREATE TABLE s (nm text)\g
insert into s values ('john')\g
insert into s values ('joan')\g
insert into s values ('wobbly')\g
select * from s
where text_soundex(nm) = text_soundex('john')\g
select nm from s a, s b
where text_soundex(a.nm) = text_soundex(b.nm)
and a.oid <> b.oid\g
CREATE FUNCTION text_sx_eq(text, text) RETURNS bool AS
'select text_soundex($1) = text_soundex($2)'
LANGUAGE 'sql'\g
CREATE FUNCTION text_sx_lt(text,text) RETURNS bool AS
'select text_soundex($1) < text_soundex($2)'
LANGUAGE 'sql'\g
CREATE FUNCTION text_sx_gt(text,text) RETURNS bool AS
'select text_soundex($1) > text_soundex($2)'
LANGUAGE 'sql';
CREATE FUNCTION text_sx_le(text,text) RETURNS bool AS
'select text_soundex($1) <= text_soundex($2)'
LANGUAGE 'sql';
CREATE FUNCTION text_sx_ge(text,text) RETURNS bool AS
'select text_soundex($1) >= text_soundex($2)'
LANGUAGE 'sql';
CREATE FUNCTION text_sx_ne(text,text) RETURNS bool AS
'select text_soundex($1) <> text_soundex($2)'
LANGUAGE 'sql';
DROP OPERATOR #= (text,text)\g
CREATE OPERATOR #= (leftarg=text, rightarg=text, procedure=text_sx_eq,
commutator=text_sx_eq)\g
SELECT *
FROM s
WHERE text_sx_eq(nm,'john')\g
SELECT *
from s
where s.nm #= 'john';

361
contrib/string/string_io.c Normal file
View File

@ -0,0 +1,361 @@
/*
* string_io.c --
*
* This file defines new input/output conversion routines for strings.
*
* Copyright (c) 1996, Massimo Dal Zotto <dz@cs.unitn.it>
*/
#include <ctype.h>
#include <string.h>
#include "postgres.h"
#include "utils/elog.h"
#include "utils/palloc.h"
#include "utils/builtins.h"
/* define this if you want to see iso-8859 characters */
#define ISO8859
#define MIN(x, y) ((x) < (y) ? (x) : (y))
#define VALUE(char) ((char) - '0')
#define DIGIT(val) ((val) + '0')
#define ISOCTAL(c) (((c) >= '0') && ((c) <= '7'))
#ifndef ISO8859
#define NOTPRINTABLE(c) (!isprint(c))
#else
#define NOTPRINTABLE(c) (!isprint(c) && ((c) < 0xa0))
#endif
/*
* string_output() --
*
* This function takes a pointer to a string data and an optional
* data size and returns a printable representation of the data
* translating all escape sequences to C-like \nnn or \c escapes.
* The function is used by output methods of various string types.
*
* Arguments:
* data - input data (can be NULL)
* size - optional size of data. A negative value indicates
* that data is a null terminated string.
*
* Returns:
* a pointer to a new string containing the printable
* representation of data.
*/
char *
string_output(char *data, int size)
{
register unsigned char c, *p, *r, *result;
register int l, len;
if (data == NULL) {
result = (char *) palloc(2);
result[0] = '-';
result[1] = '\0';
return (result);
}
if (size < 0) {
size = strlen(data);
}
/* adjust string length for escapes */
len = size;
for (p=data,l=size; l>0; p++,l--) {
switch (*p) {
case '\\':
case '"' :
case '{':
case '}':
case '\b':
case '\f':
case '\n':
case '\r':
case '\t':
case '\v':
len++;
break;
default:
if (NOTPRINTABLE(c)) {
len += 3;
}
}
}
len++;
result = (char *) palloc(len);
for (p=data,r=result,l=size; (l > 0) && (c = *p); p++,l--) {
switch (c) {
case '\\':
case '"' :
case '{':
case '}':
*r++ = '\\';
*r++ = c;
break;
case '\b':
*r++ = '\\';
*r++ = 'b';
break;
case '\f':
*r++ = '\\';
*r++ = 'f';
break;
case '\n':
*r++ = '\\';
*r++ = 'n';
break;
case '\r':
*r++ = '\\';
*r++ = 'r';
break;
case '\t':
*r++ = '\\';
*r++ = 't';
break;
case '\v':
*r++ = '\\';
*r++ = 'v';
break;
default:
if (NOTPRINTABLE(c)) {
*r = '\\';
r += 3;
*r-- = DIGIT(c & 07);
c >>= 3;
*r-- = DIGIT(c & 07);
c >>= 3;
*r = DIGIT(c & 03);
r += 3;
} else {
*r++ = c;
}
}
}
*r = '\0';
return((char *) result);
}
/*
* string_input() --
*
* This function accepts a C string in input and copies it into a new
* object allocated with palloc() translating all escape sequences.
* An optional header can be allocatd before the string, for example
* to hold the length of a varlena object.
* This function is not necessary for input from sql commands because
* the parser already does escape translation, all data input routines
* receive strings in internal form.
*
* Arguments:
* str - input string possibly with escapes
* size - the required size of new data. A value of 0
* indicates a variable size string, while a
* negative value indicates a variable size string
* of size not greater than this absolute value.
* hdrsize - size of an optional header to be allocated before
* the data. It must then be filled by the caller.
* rtn_size - an optional pointer to an int variable where the
* size of the new string is stored back.
*
* Returns:
* a pointer to the new string or the header.
*/
char *
string_input(char *str, int size, int hdrsize, int *rtn_size)
{
register unsigned char *p, *r;
unsigned char *result;
int len;
if ((str == NULL) || (hdrsize < 0)) {
return (char *) NULL;
}
/* Compute result size */
len = strlen(str);
for (p=str; *p; ) {
if (*p++ == '\\') {
if (ISOCTAL(*p)) {
if (ISOCTAL(*(p+1))) {
p++;
len--;
}
if (ISOCTAL(*(p+1))) {
p++;
len--;
}
}
if (*p) p++;
len--;
}
}
/* result has variable length */
if (size == 0) {
size = len+1;
} else
/* result has variable length with maximum size */
if (size < 0) {
size = MIN(len, - size)+1;
}
result = (char *) palloc(hdrsize+size);
memset(result, 0, hdrsize+size);
if (rtn_size) {
*rtn_size = size;
}
r = result + hdrsize;
for (p=str; *p; ) {
register unsigned char c;
if ((c = *p++) == '\\') {
switch (c = *p++) {
case '\0':
p--;
break;
case '0':
case '1':
case '2':
case '3':
case '4':
case '5':
case '6':
case '7':
c = VALUE(c);
if (isdigit(*p)) {
c = (c<<3) + VALUE(*p++);
}
if (isdigit(*p)) {
c = (c<<3) + VALUE(*p++);
}
*r++ = c;
break;
case 'b':
*r++ = '\b';
break;
case 'f':
*r++ = '\f';
break;
case 'n':
*r++ = '\n';
break;
case 'r':
*r++ = '\r';
break;
case 't':
*r++ = '\t';
break;
case 'v':
*r++ = '\v';
break;
default:
*r++ = c;
}
} else {
*r++ = c;
}
}
return((char *) result);
}
char *
c_charout(int32 c)
{
char str[2];
str[0] = (char) c;
str[1] = '\0';
return (string_output(str, 1));
}
char *
c_char2out(uint16 s)
{
return (string_output((char *) &s, 2));
}
char *
c_char4out(uint32 s)
{
return (string_output((char *) &s, 4));
}
char *
c_char8out(char *s)
{
return (string_output(s, 8));
}
char *
c_char16out(char *s)
{
return (string_output(s, 16));
}
/*
* This can be used for text, bytea, SET and unknown data types
*/
char *
c_textout(struct varlena *vlena)
{
int len = 0;
char *s = NULL;
if (vlena) {
len = VARSIZE(vlena) - VARHDRSZ;
s = VARDATA(vlena);
}
return (string_output(s, len));
}
/*
* This can be used for varchar and bpchar strings
*/
char *
c_varcharout(char *s)
{
int len;
if (s) {
len = *(int32*)s - 4;
s += 4;
}
return (string_output(s, len));
}
#ifdef 0
struct varlena *
c_textin(char *str)
{
struct varlena *result;
int len;
if (str == NULL) {
return ((struct varlena *) NULL);
}
result = (struct varlena *) string_input(str, 0, VARHDRSZ, &len);
VARSIZE(result) = len;
return (result);
}
char *
c_char16in(char *str)
{
return (string_input(str, 16, 0, NULL));
}
#endif

111
contrib/string/string_io.sql Normal file
View File

@ -0,0 +1,111 @@
- - -- load the new functions
- - --
load '/home/dz/lib/postgres/string_output.so';
- - -- create function c_textin(opaque)
- - -- returns text
- - -- as '/home/dz/lib/postgres/string_output.so'
- - -- language 'c';
create function c_charout(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_char2out(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_char4out(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_char8out(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_char16out(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_textout(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
create function c_varcharout(opaque)
returns int4
as '/home/dz/lib/postgres/string_output.so'
language 'c';
- - -- define a function which sets the new output routines for char types
- - --
- - -- select c_mode();
- - --
create function c_mode()
returns text
as 'update pg_type set typoutput=''c_charout'' where typname=''char''\;
update pg_type set typoutput=''c_char2out'' where typname=''char2''\;
update pg_type set typoutput=''c_char4out'' where typname=''char4''\;
update pg_type set typoutput=''c_char8out'' where typname=''char8''\;
update pg_type set typoutput=''c_char16out'' where typname=''char16''\;
update pg_type set typoutput=''c_textout'' where typname=''text''\;
update pg_type set typoutput=''c_textout'' where typname=''bytea''\;
update pg_type set typoutput=''c_textout'' where typname=''unknown''\;
update pg_type set typoutput=''c_textout'' where typname=''SET''\;
update pg_type set typoutput=''c_varcharout'' where typname=''varchar''\;
update pg_type set typoutput=''c_varcharout'' where typname=''bpchar''\;
select ''c_mode''::text'
language 'sql';
- - -- define a function which restores the original routines for char types
- - --
- - -- select pg_mode();
- - --
create function pg_mode()
returns text
as 'update pg_type set typoutput=''charout'' where typname=''char''\;
update pg_type set typoutput=''char2out'' where typname=''char2''\;
update pg_type set typoutput=''char4out'' where typname=''char4''\;
update pg_type set typoutput=''char8out'' where typname=''char8''\;
update pg_type set typoutput=''char16out'' where typname=''char16''\;
update pg_type set typoutput=''textout'' where typname=''text''\;
update pg_type set typoutput=''textout'' where typname=''bytea''\;
update pg_type set typoutput=''textout'' where typname=''unknown''\;
update pg_type set typoutput=''textout'' where typname=''SET''\;
update pg_type set typoutput=''varcharout'' where typname=''varchar''\;
update pg_type set typoutput=''varcharout'' where typname=''bpchar''\;
select ''pg_mode''::text'
language 'sql';
- - -- or do the changes manually
- - --
- - -- update pg_type set typoutput='charout' where typname='char';
- - -- update pg_type set typoutput='char2out' where typname='char2';
- - -- update pg_type set typoutput='char4out' where typname='char4';
- - -- update pg_type set typoutput='char8out' where typname='char8';
- - -- update pg_type set typoutput='char16out' where typname='char16';
- - -- update pg_type set typoutput='textout' where typname='text';
- - -- update pg_type set typoutput='textout' where typname='bytea';
- - -- update pg_type set typoutput='textout' where typname='unknown';
- - -- update pg_type set typoutput='textout' where typname='SET';
- - -- update pg_type set typoutput='varcharout' where typname='varchar';
- - -- update pg_type set typoutput='varcharout' where typname='bpchar';
- - --
- - -- update pg_type set typoutput='c_charout' where typname='char';
- - -- update pg_type set typoutput='c_char2out' where typname='char2';
- - -- update pg_type set typoutput='c_char4out' where typname='char4';
- - -- update pg_type set typoutput='c_char8out' where typname='char8';
- - -- update pg_type set typoutput='c_char16out' where typname='char16';
- - -- update pg_type set typoutput='c_textout' where typname='text';
- - -- update pg_type set typoutput='c_textout' where typname='bytea';
- - -- update pg_type set typoutput='c_textout' where typname='unknown';
- - -- update pg_type set typoutput='c_textout' where typname='SET';
- - -- update pg_type set typoutput='c_varcharout' where typname='varchar';
- - -- update pg_type set typoutput='c_varcharout' where typname='bpchar';

180
contrib/zap_ltv/README Normal file
View File

@ -0,0 +1,180 @@
From ccshag@cclabs.missouri.edu Wed Jul 10 04:27:16 1996
Received: from realtime.cc.missouri.edu (realtime.cc.missouri.edu [128.206.212.69]) by ki.net (8.7.5/8.7.5) with ESMTP id EAA12722 for <scrappy@ki.net>; Wed, 10 Jul 1996 04:27:13 -0400 (EDT)
Received: from localhost (ccshag@localhost) by realtime.cc.missouri.edu (8.7.1/8.7.1) with SMTP id DAA00915; Wed, 10 Jul 1996 03:26:42 -0500 (CDT)
X-Authentication-Warning: realtime.cc.missouri.edu: ccshag owned process doing -bs
Date: Wed, 10 Jul 1996 03:26:41 -0500 (CDT)
From: "Paul 'Shag' Walmsley" <ccshag@cclabs.missouri.edu>
Sender: ccshag@cclabs.missouri.edu
To: postgres95-hackers@oozoo.vnet.net
cc: pixel@tiger.coe.missouri.edu, michael.siebenborn@ae3.Hypo.DE,
scrappy@ki.net
Subject: Workaround for database corruption problems [long]
Message-ID: <Pine.SGI.3.93.960710023021.673B-100000@realtime.cc.missouri.edu>
X-Disclaimer: The opinions of this writer do not necessarily represent those of the University of Missouri-Columbia.
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Status: RO
X-Status:
I've been poking through the guts of POSTGRES95 in pursuit of the
previously-mentioned "database corruption" problem, and I think that I
have some preliminary answers and a workaround for people to play around
with.
Specifically, the problem that I'm referring to is manifested by
pg_log, pg_time, or pg_variable either growing to huge sizes (usually
128MB) or showing evidence of internal corruption. Symptoms that appear
to the user include receiving messages like the following in psql or
monitor:
"WARN:cannot open segment 1 of relation pg_time"
"WARN:cannot write block 16384 of pg_log"
.. which are followed up in a 'postmaster -d 3' debug log by a
"NOTICE:AbortTransaction and not in in-progress state"
It's been my experience that this problem is difficult to reproduce on
demand; I've tried several different ways and haven't succeeded. (If
anyone knows how to reliably reproduce this, please E-mail me.) I was,
however, able to obtain a database in a corrupted state from one of the
fellows on campus here running POSTGRES95; and following is something of a
post-mortem.
----------
The problem with the database is that after any query, POSTGRES95 attempts
to generate a huge pg_log file and fails (running out of disk space) with
a "WARN:cannot write block 16384 of pg_log" message. The contents of the
database and its internal structure were reasonably intact - I discovered
that I was able to execute a single SQL query per-backend, and could
therefore back the contents of the database up with a COPY command. (I
wasn't able to use pg_dump; it failed on its BEGIN TRANSACTION step.)
Inspection of data/pg_log, data/pg_variable, and data/pg_time revealed the
following;
realtime /usr/postgres95 > od -x data/pg_log.old | head
0000000 0060 2000 2000 2000 f680 0000 ed00 0000
0000020 e300 0000 dc00 0000 ce00 0000 bc00 0000
0000040 b140 0000 a740 0000 9dc0 0000 9180 0000
0000060 8580 0000 7c80 0000 6fc0 0000 6480 0000
0000100 58c0 0000 4fc0 0000 4640 0000 3a80 0000
0000120 30c0 0000 23c0 0000 1900 0000 0c40 0000
0000140 0000 0000 0000 0000 0000 0000 0000 0000
*
0000200 8800 0000 0000 0000 0800 0000 0000 0000
0000220 0800 0000 0000 0000 0800 0000 0000 0000
Now, already something is obviously wrong: pg_log shouldn't have any
values other than 0, 1, 2, 4, 8, a, c, or e for each nybble (see the XID_
... definitions in src/backend/access/transam.h:35; two of these can be
stored per nybble.)
realtime /usr/postgres95 > od -x data/pg_variable.old | head
0000000 0058 2000 2000 2740 f240 0000 e400 0000
0000020 d780 0000 cac0 0000 b840 0000 a900 0000
0000040 9f80 0000 9280 0000 8580 0000 78c0 0000
0000060 6c80 0000 6200 0000 5800 0000 4f80 0000
0000100 44c0 0000 39c0 0000 2d80 0000 2600 0000
0000120 1c00 0000 0e00 0000 0000 0000 0000 0000
0000140 0000 0000 0000 0000 0000 0000 0000 0000
*
0000700 0000 01bc 0000 009c 0014 ffff ffff 0000
0000720 0004 5f0b 0000 0000 0000 0ba3 0000 0c23
This is obviously broken too; the only bytes that should be non-zero in
pg_variable are the first 16 (see src/backend/access/transam.h:99).
realtime /usr/postgres95 > od -x data/pg_time.old | head -10
0000000 0000 0000 0000 0000 0000 0000 0000 0000
*
0004000 31c6 09ae 0000 0000 31c6 09b3 31a9 79a6
0004020 31a9 79a6 31a9 79a8 31a9 79a9 31a9 79a9
0004040 31a9 79a9 31a9 79aa 31a9 79aa 31a9 79aa
0004060 31a9 79aa 31a9 79aa 31a9 79ab 31a9 79ab
0004100 31a9 79ab 31a9 79ac 31a9 79ac 31a9 79ac
0004120 31a9 79ac 31a9 79ad 31a9 79ad 31a9 79ae
0004140 31a9 79ae 31a9 79af 31a9 79af 31a9 79af
0004160 31a9 79b0 31a9 79b0 31a9 79b4 31a9 79b4
realtime /usr/postgres95 > od -x data/pg_time.old +32b | head -10
0032000 6665 6520 666f 7220 31c5 cb61 696e 6720
0032020 6465 7665 6c6f 7065 7273 2062 7579 2061
0032040 206c 6f77 2d69 6e63 6f6d 6520 6170 6172
0032060 746d 656e 7420 636f 6d70 6c65 7869 6e20
0032100 7468 6520 7472 6561 7375 7265 7227 7320
0032120 7761 7264 2066 726f 6d20 7468 6520 6665
0032140 6465 7261 6c20 676f 7665 726e 6d65 6e74
0032160 2066 6f72 2024 313b 2064 6576 656c 6f70
0032200 6572 7361 6c73 6f20 31c5 cb7c 31be 91a2
0032220 31be 91a2 31be 91a2 31be 91a2 31be 91a3
The first part of pg_time looked okay -- filled with 4-byte time values
with the occasional "00 00 00 00" here and there -- but inspection into
pg_time's guts revealed some preposterous numbers.
For your comparing pleasure, I include copies of what these files
_should_ look like -- more or less -- from a newly initdb'd database
directory:
realtime /usr/postgres95 > od -x data-new-initdb/pg_log
0000000 0000 0000 0000 0000 0000 0000 0000 0000
*
0000200 8aaa aaaa aaaa aaa8 0000 0000 0000 0000
0000220 0000 0000 0000 0000 0000 0000 0000 0000
*
0020000
realtime /usr/postgres95 > od -x data-new-initdb/pg_variable
0000000 0000 0000 0000 0222 0000 021e 0000 5120
0000020 0000 0000 0000 0000 0000 0000 0000 0000
*
0020000
realtime /usr/postgres95 > od -x data-new-initdb/pg_time
0000000 0000 0000 0000 0000 0000 0000 0000 0000
*
0004000 31e3 4fb3 0000 0000 31e3 4fb4 31e3 4fb4
0004020 31e3 4fb4 31e3 4fb5 31e3 4fb5 31e3 4fb5
0004040 31e3 4fb6 31e3 4fb6 31e3 4fb6 31e3 4fb6
0004060 31e3 4fb7 31e3 4fb7 31e3 4fb7 31e3 4fb7
0004100 31e3 4fb8 31e3 4fb8 31e3 4fb8 31e3 4fb9
0004120 31e3 4fb9 31e3 4fb9 31e3 4fb9 31e3 4fba
0004140 31e3 4fba 31e3 4fba 31e3 4fbb 31e3 4fbb
0004160 31e3 4fbb 31e3 4fbb 31e3 4fbb 0000 0000
0004200 0000 0000 0000 0000 0000 0000 0000 0000
*
0020000
What's more, if I view pg_log, pg_variable, and pg_time with a text
editor, I discover that the corrupted areas contain fragments of tuples
from the database!
----------
Since I have been unable to reproduce this problem on demand (and
therefore have a complete picture of all of the queries executed on the
database), I've only been able to speculate on the original cause of the
problem. One explanation would be some kind of buffer manager bug; or
perhaps the backend is running low on file descriptors and bollixing
existing ones? I intend to continue tracking this down as I have the
time, but in the interim, I've created a quick Perl script that is
designed to restore some sense of rationality to the
pg_{log,time,variable} files. It's a horribly barbaric way to do this --
at the very least, it almost certainly breaks time travel, and will
almost certainly result in duplicate oid problems -- but it restored my
pathological database here to a sufficiently working state such that I
could run pg_dump on it and do various other queries with it. The script
is included at the bottom of this message.
Anyway, fellow posthackers, assuming that no one raises any red flags
about this, I'll post it on postgres95@oozoo.vnet.net as a temporary
stop-gap workaround to allow people to recover their databases when this
sort of problem occurs.
I wish I had more time to do this kind of thing.
- Paul "Shag" Walmsley <ccshag@cclabs.missouri.edu>
"Knowing is not enough." -- Hal Hartley, "Surviving Desire"

93
contrib/zap_ltv/zap_ltv.pl Normal file
View File

@ -0,0 +1,93 @@
#!/bin/perl
#
# zap_ltv - attempt to restore a POSTGRES95 database afflicted with
# pg_log, pg_time, or pg_variable corruption to
# minimal functionality
#
# Paul Walmsley <ccshag@cclabs.missouri.edu>
#
# Legalese:
#
# In no event shall Paul Walmsley be liable to any party for direct,
# indirect, special, incidental, or consequential damages, including
# lost profits, arising from the use of this software, even if Paul Walmsley
# has been advised of the possibility of such damage. Paul Walmsley
# 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 Paul Walmsley has no obligations to provide maintenance, support,
# updates, enhancements, or modifications.
#
# Thanks, Berkeley ;-)
print "This program should only be run if POSTGRES95 is not currently\n";
print "running on this system. It should also not be run unless you \n";
print "are having seemingly unrecoverable problems with your POSTGRES95\n";
print "database related to pg_log, pg_time, or pg_variable corruption.\n\n";
print "This program replaces the existing pg_log, pg_time, and pg_variable\n";
print "files with \"clean\" copies of those files. This will almost \n";
print "certainly result in duplicate IDs when any INSERTs are attempted,\n";
print "and probably has other side-effects as well. Back up your databases\n"
print "and re-initdb from scratch after using this!\n\n";
print "This program will attempt to make a backup of your pg_time,\n";
print "pg_log, and pg_variable files (to pg_time.backup, pg_log.backup,\n";
print "and pg_variable.backup, respectively).\n\n";
print "This program bears no guarantees nor any warranties whatsoever.\n";
print "View the source for details.\n\n";
print "Press ENTER to zap your pg_log, pg_time, and pg_variable files:";
$trash=<STDIN>;
$pg_log_data=pack('xxxx@8192',0);
$pg_time_data=pack('xxxx@8192',0);
# next_tid, last_tid, and oid are pulled from a fresh initdb
$pg_variable_data=pack('xxxxxxCCxxCCxxCC@8192',2,34,2,30,81,32);
if (length($pg_log_data)!=8192) {
die "pg_log_data must be exactly 8192 bytes long";
}
if (length($pg_time_data)!=8192) {
die "pg_time_data must be exactly 8192 bytes long";
}
if (length($pg_variable_data)!=8192) {
die "pg_variable_data must be exactly 8192 bytes long";
}
if (! -f 'pg_database') {
die "This program must be run from your POSTGRES95 data directory.";
}
system('cp pg_log pg_log.backup');
open(PG_LOG,'>pg_log');
binmode(PG_LOG);
$written=syswrite(PG_LOG,$pg_log_data,8192);
close(PG_LOG);
if ($written!=8192) {
die "pg_log write failed: $!";
}
$written=0;
system('cp pg_time pg_time.backup');
open(PG_TIME,'>pg_time');
binmode(PG_TIME);
$written=syswrite(PG_TIME,$pg_time_data,8192);
close(PG_TIME);
if ($written!=8192) {
die "pg_time write failed: $!";
}
$written=0;
system('cp pg_variable pg_variable.backup');
open(PG_VARIABLE,'>pg_variable');
binmode(PG_VARIABLE);
$written=syswrite(PG_VARIABLE,$pg_variable_data,8192);
close(PG_VARIABLE);
if ($written!=8192) {
die "pg_variable write failed: $!";
}
print "Done.\n";

44
doc/1.0_to_1.01.sql Normal file
View File

@ -0,0 +1,44 @@
-- add builtin functions that are new to 1.01
create function int4eqoid (int4, oid) returns bool as 'foo'
language 'internal';
create function oideqint4 (oid, int4) returns bool as 'foo'
language 'internal';
create function char2icregexeq (char2, text) returns bool as 'foo'
language 'internal';
create function char2icregexne (char2, text) returns bool as 'foo'
language 'internal';
create function char4icregexeq (char4, text) returns bool as 'foo'
language 'internal';
create function char4icregexne (char4, text) returns bool as 'foo'
language 'internal';
create function char8icregexeq (char8, text) returns bool as 'foo'
language 'internal';
create function char8icregexne (char8, text) returns bool as 'foo'
language 'internal';
create function char16icregexeq (char16, text) returns bool as 'foo'
language 'internal';
create function char16icregexne (char16, text) returns bool as 'foo'
language 'internal';
create function texticregexeq (text, text) returns bool as 'foo'
language 'internal';
create function texticregexne (text, text) returns bool as 'foo'
language 'internal';
-- add builtin functions that are new to 1.01
create operator = (leftarg = int4, rightarg = oid, procedure = int4eqoid);
create operator = (leftarg = oid, rightarg = int4, procedure = oideqint4);
create operator ~* (leftarg = char2, rightarg = text, procedure = char2icregexeq);
create operator !~* (leftarg = char2, rightarg = text, procedure = char2icregexne);
create operator ~* (leftarg = char4, rightarg = text, procedure = char4icregexeq);
create operator !~* (leftarg = char4, rightarg = text, procedure = char4icregexne);
create operator ~* (leftarg = char8, rightarg = text, procedure = char8icregexeq);
create operator !~* (leftarg = char8, rightarg = text, procedure = char8icregexne);
create operator ~* (leftarg = char16, rightarg = text, procedure = char16icregexeq);
create operator !~* (leftarg = char16, rightarg = text, procedure = char16icregexne);
create operator ~* (leftarg = text, rightarg = text, procedure = texticregexeq);
create operator !~* (leftarg = text, rightarg = text, procedure = texticregexne);

827
doc/FAQ Normal file
View File

@ -0,0 +1,827 @@
==================================================
Frequently Asked Questions (FAQ) for Postgres95
==================================================
last updated: Sun Aug 11 01:35:34 EDT 1996
current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
original author: Jolly Chen (jolly@cs.berkeley.edu)
changes in this version (* = modified, + = new):
* 1.8) What documentation is available for Postgres95?
* 3.13) What is the maximum size for a tuple?
* 3.14) I defined indices but my queries don't seem to make use of them. Why?
* 3.37) What is the time-warp feature and how does it relate to vacuum?
+ 3.38) How do I tune the database engine for better performace?
This file is divided approximately as follows:
1.*) General questions
2.*) Installation questions
3.*) Postgres95 Features questions
4.*) Questions about extending Postgres95
5.*) Bugs
Questions answered:
1.1) What is Postgres95?
1.2) What does Postgres95 run on?
1.3) Where can I get Postgres95?
1.4) What's the copyright on Postgres95?
1.5) Support for Postgres95
1.6) Future releases of Postgres95
1.7) Is there a commercial version of Postgres95?
1.9) What version of SQL does Postgres95 use?
1.10) Does Postgres95 work with databases from earlier versions of postgres?
1.11) How many people use Postgres95?
2.1) I get the error "cpp: command not found" when I try to compile
2.2) I get 'yy_flush_buffer undefined' when I try to compile the backend
2.3) initdb doesn't run
2.4) when I start up the postmaster, I get
2.5) The system seems to be confused about commas, decimal points, and
2.6) How do I install postgres95 somewhere other than /usr/local/postgres95?
2.7) The backend compiled successfully, but compiling libpq resulted
in a complaint: "libpq/pqcomm.h" not found when compiling fe-auth.c.
2.8) Where can I find the bug fixes for postgres95?
2.9) I can't apply the patches even though everything looks like it should
work.
2.10) When I run postmaster, I get a Bad System Call core dumped message.
2.11) I get the error message "obj/fmgr.h: No such file or directory"
2.12) When I try to start the postmaster, I get IpcMemoryCreate errors.
2.13) I get the strange make errors right at the beginning:
2.14) I have changed a source file, but a recompile does not see the
3.1) How do I specify a KEY or other constraints on a column?
3.2) Does Postgres95 support nested subqueries?
3.3) How do I define a unique indices?
3.4) I've having a lot of problems with using rules.
3.5) I can't seem to write into the middle of large objects reliably.
3.6) Does postgres95 have a graphical user interface? A report
3.7) How can I write client applications to Postgres95?
3.8) How do I prevent other hosts from accessing my Postgres95
3.9) How do I set up a pg_group?
3.10) What is the exact difference between binary cursors and normal cursors?
3.11) Why doesn't the != operator work?
3.12) What is a R-tree index and what is it used for?
3.13) What is the maximum size for a tuple?
3.14) I defined indices but my queries don't seem to make use of them. Why?
3.15) Are there ODBC drivers for Postgres95?
3.16) How do I use postgres for multi-dimensional indexing (> 2 dimensions)?
3.17) How do I do regular expression searches? case-insensitive
regexp searching?
3.18) I can't access the database as the 'root' user.
3.19) I experienced a server crash during a vacuum. How do I remove the
lock file?
3.20) What is the difference between the various character types?
3.21) In a query, how do I detect if a field is NULL?
3.22) How do I see how the query optimizer is evaluating my query?
3.23) How do I create a serial field?
3.24) How do I create a multi-column index?
3.25) What are the temp_XXX files in my database directory?
3.26) Why are my table files not getting any smaller after a delete?
3.27) Why can't I connect to my database from another machine?
3.28) I get the error 'default index class unsupported' when creating an
index. How do I do it?
3.29) Why does creating an index crash the backend server?
3.30) How do I specify a decimal constant as a float8, or a string as a text?
3.31) How do I find out what indexes or operations are defined in the
database?
3.32) My database is corrupt. I can't do anything. What should I do?
3.33) Createdb, destroydb, createuser,destroyuser don't run. Why?
3.34) Why does 'createuser' return 'unexpected last match in input()'?
3.35) All my servers crash under concurrent table access. Why?
3.36) What tools are available for hooking postgres to Web pages?
3.37) What is the time-warp feature and how does it relate to vacuum?
3.38) How do I tune the database engine for better performace?
4.1) I wrote a user-defined function and when I run it in psql, it
dumps core.
4.2) I get messages of the type NOTICE:PortalHeapMemoryFree: 0x402251d0
4.3) I've written some nifty new types and functions for Postgres95.
4.4) How do I write a C function to return a tuple?
5.1) How do I find out about bug fixes?
5.2) How do I make a bug report?
----------------------------------------------------------------------
Section 1: General Questions
----------------------------------------------------------------------
1.1) What is Postgres95?
Postgres95 is an enhancement of the POSTGRES database
management system, a next-generation DBMS research prototype.
While Postgres95 retains the powerful data model and rich data
types of POSTGRES, it replaces the PostQuel query language with an
extended subset of SQL. Postgres95 is free and the complete
source is available.
Postgres95 development is being performed by a team of Internet
developers who all subscribe to the Postgres95 development mailing
list. The current coordinator is Marc G. Fournier (scrappy@ki.net).
(See below on how to join). This team is now responsible for all
current and future development of Postgres95.
The authors of Postgres95 1.01 were Andrew Yu and Jolly Chen.
Many others have contributed to the porting, testing, debugging and
enhancement of the code. The original Postgres code, from which
Postgres95 is derived, was the effort of many graduate
students, undergraduate students, and staff programmers
working under the direction of Professor Michael Stonebraker
at the University of California, Berkeley.
1.2) What does Postgres95 run on?
The authors have compiled and tested Postgres95 on the following
platforms(some of these compiles require gcc 2.7.0):
- DEC Alpha AXP on OSF/1 2.0
- HP PA-RISC on HP-UX 9.0
- i386 Solaris
- SUN SPARC on Solaris 2.4
- SUN SPARC on SunOS 4.1.3
- DEC MIPS on Ultrix 4.4
- Intel x86 on Linux 1.2 and Linux ELF
- OSs derived from 4.4-lite BSD (NetBSD, FreeBSD)
- IBM on AIX 3.2.5
- BSD/OS 2.0, 2.01 & 2.1
- SGI MIPS on IRIX 5.3
The following ports are bundled with the Postgres95 distribution. The
authors do not have handy access to these platforms but the
ports have been tested by the others.
- Motorola MC68K or Intel x86 on NeXTSTEP 3.2
- Intel x86 on Intel SVR4
1.3) Where can I get Postgres95?
The primary anonymous ftp site for postgres95 is:
ftp://ftp.ki.net/pub/postgres95
A mirror site exists at:
ftp://postgres95.vnet.net/pub/postgres95
1.4) What's the copyright on Postgres95?
Postgres95 is subject to the following COPYRIGHT.
POSTGRES95 Data Base Management System
Copyright (c) 1994-6 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 MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
1.5) Support for Postgres95
There is no official support for Postgres95 from the original
maintainers or from University of California, Berkeley. It is
maintained through volunteer effort only.
With the generosity of the Jason Wright and others at Vnet,
the postgres95 mailing list now has a new home --
postgres95@postgres95.vnet.net. It is available for
discussion of matters pertaining to Postgres95, including but
not limited to bug reports and fixes. For info on how to
subscribe, send a mail with the lines in the body (not the
subject line):
help
info postgres95
to
majordomo@postgres95.vnet.net
There is also a digest list available. To subscribe to this list,
send email to majordomo@postgres95.vnet.net with a BODY of:
subscribe postgres95-digest
Digests are sent out to members of this list whenever the main list has
received around 30k of messages.
Archives and digests of the new mailing list at Vnet can be found at:
ftp://postgres95.vnet.net/pub/postgres95/archives
ftp://postgres95.vnet.net/pub/postgres95/digests
There is also a developers mailing list available. To subscribe to
this list, send email to pg95-dev-request@ki.net with a BODY of:
subscribe pg95-dev
Additional information about Postgres95 can be found via the
postgres95 WWW home page at:
http://www.ki.net/postgres95
1.6) Future releases of Postgres95
The latest release of postgres95 is version 1.02.
1.7) Is there a commercial version of Postgres95?
Illustra Information Technology (a wholly owned subsidiary of
Informix Software, Inc.) sells an object-relational
DBMS called Illustra that was originally based on postgres.
Illustra has cosmetic similarities to postgres95 but has more
features, is more robust, performs better, and offers real
documentation and support. On the flip side, it costs money.
For more information, contact sales@illustra.com
1.8) What documentation is available for Postgres95?
A user manual, manual pages, and some small test examples
are included in the distribution. The www page contains
pointers to an implementation guide and five papers written
about postgres design concepts and features.
1.9) What version of SQL does Postgres95 use?
Postgres95 supports a subset of SQL-92. It has most of the
important constructs but lacks some of the functionality.
The most visible differences are:
- no support for primary keys or column constraints
- no support for nested subqueries
- no HAVING clause under a GROUP BY
On the other hand, you get to create user-defined types,
functions, inheritance etc. If you're willing to help with
postgres95 coding, eventually we can also add the missing
features listed above.
1.10) Does Postgres95 work with databases from earlier versions of postgres?
Postgres95 v1.02 is compatible with databases created with v1.01.
Those upgrading from 1.0 to 1.02 should read the directions in the
MIGRATION_1.0_TO_1.02 directory.
1.11) How many people use Postgres95?
Since we don't have any licensing or registration scheme, it's
impossible to tell. We do know hundreds copies of postgres95
v1.* have been downloaded, and that there many hundreds of
subscribers to the mailing lists.
----------------------------------------------------------------------
Section 2: Installation Questions
----------------------------------------------------------------------
2.1) I get the error "cpp: command not found" when I try to compile
the backend.
Edit the src/backend/utils/Gen_fmgrtab.sh script to include the path
for the cpp for your particular site.
2.2) I get 'yy_flush_buffer undefined' when I try to compile the backend
Use a more recent version of flex, version 2.5.2. Version 2.5.3
has a known bug.
2.3) initdb doesn't run
* check to see that you have the proper paths set
* check that the 'postgres' user owns all the right files
* ensure that there are files in $PGDATA/files, and that they
are non-empty. If they aren't, then "gmake install" failed for
some reason
2.4) when I start up the postmaster, I get
"FindBackend: could not find a backend to execute..."
"postmaster: could not find backend to execute..."
You probably do not have the right path set up. the 'postgres'
executable needs to be in your path.
2.5) The system seems to be confused about commas, decimal points, and
date formats.
Check your locale configuration. postgres95 uses the locale
settings of the user that ran the postmaster process. Set those
accordingly for your operating environment.
2.6) How do I install postgres95 somewhere other than /usr/local/postgres95?
You need to manually edit the paths in src/Makefile.global to
your site configuration.
2.7) The backend compiled successfully, but compiling libpq resulted
in a complaint: "libpq/pqcomm.h" not found when compiling fe-auth.c.
You've probably installed postgres95 somewhere other than
/usr/local/postgres, but didn't edit the src/Makefile.global
accordingly. See question 2.6.
2.8) Where can I find the bug fixes for postgres95?
The patches should be applied in the order listed. The patch files
can be ftp'ed directly from the directory:
ftp://ftp.ki.net/pub/postgres95
2.9) I can't apply the patches even though everything looks like it should
work.
If you cut and paste directly off your web browser, tabs and
whitespaces may not be preserved properly. Use the 'save as file'
option from your web browser instead.
2.10) When I run postmaster, I get a Bad System Call core dumped message.
It could be a variety of problems, but first check to see that you
have system V extensions installed on your kernel. Postgres95
requires kernel support for shared memory.
2.11) I get the error message "obj/fmgr.h: No such file or directory"
This indicates that you did not generate the file fmgr.h
properly. Something failed in the running of the
src/backend/utils/Gen_fmgrtab.sh script. Check to see the
paths used in that script is appropriate to your system.
2.12) When I try to start the postmaster, I get IpcMemoryCreate errors.
You either do not have shared memory configured properly in kernel
or you need to enlarge the shared memory available in the kernel.
The exact amount you need depends on your architecture and how
many buffers you configure postmaster to run with. For most
systems, with default buffer sizes, you need a minimum of ~760K.
2.13) I get the strange make errors right at the beginning:
warning: NUL character seen; rest of line ignored
*** missing separator. Stop.
or
Is a directory. Stop.
Eliminate any whitespaces at the end of the PORTNAME line in
Makefile.global. Extraneous tabs or spaces will confuse the make
templates.
2.14) I have changed a source file, but a recompile does not see the
change?
The Makefiles do not have the proper dependencies. You have to
do a 'make clean' and then another 'make'.
----------------------------------------------------------------------
Section 3: Postgres95 Features
----------------------------------------------------------------------
3.1) How do I specify a KEY or other constraints on a column?
Column constraints are not supported in postgres95.
As a consequence, the system does not check for duplicates.
3.2) Does Postgres95 support nested subqueries?
Subqueries are not implemented, but they can be simulated using sql
functions.
3.3) How do I define a unique indices?
Postgres95 does not support unique indices. Defining an index does
not preclude insertion of duplicate index key values.
3.4) I've having a lot of problems with using rules.
Currently, the rule system in postgres95 is mostly broken. It
works enough to support the view mechanism, but that's about it. Use
postgres95 rules at your own peril.
3.5) I can't seem to write into the middle of large objects reliably.
The Inversion large object system in postgres95 is also
mostly broken. It works well enough for storing large wads
of data and reading them back out, but the implementation has
some underlying problems. Use postgres95 large objects at
your own peril.
3.6) Does postgres95 have a graphical user interface? A report
generator? A embedded query language interface?
No. No. No. Not in the official distribution at least. Some
users have reported some success at using 'pgbrowse' and 'onyx' as
frontends to postgres95. Several contributions are working on
tk based frontend tools. Ask on the mailing list.
3.7) How can I write client applications to Postgres95?
Postgres95 supports a C-callable library interface called libpq
as well as a Tcl-based library interface called libtcl.
Others have contributed a perl interface and a WWW gateway
to postgres95. See the postgres95 home pages for more details.
3.8) How do I prevent other hosts from accessing my Postgres95
backend?
Use host-based authentication by modifying the file
$PGDATA/pg_hba accordingly.
3.9) How do I set up a pg_group?
Currently, there is no easy interface to set up user groups.
You have to explicitly insert/update the pg_group table. For example:
jolly=> insert into pg_group (groname, grosysid, grolist)
jolly=> values ('posthackers', '1234', '{5443, 8261}');
INSERT 548224
jolly=> grant insert on foo to group posthackers;
CHANGE
jolly=>
The fields in pg_group are:
groname: the group name. This a char16 and should
be purely alphanumeric. Do not include underscores
or other punctuation.
grosysid: the group id. This is an int4.
This should be unique for each group.
grolist: the list of pg_user id's that belong in the group.
This is an int4[].
3.10) What is the exact difference between binary cursors and normal cursors?
Normal cursors return data back in ASCII format. Since data is stored
natively in binary format, the system must do a conversion to produce
the ASCII format. In addition, ASCII formats are often large in size
than binary format. Once the attributes come back in ASCII, often the
client application then has to convert it to a binary format to
manipulate it anyway.
Binary cursors give you back the data in the native binary
representation. Thus, binary cursors will tend to be a little faster
since there's less overhead of conversion.
However, ASCII is architectural neutral whereas binary representation
can differ between different machine architecture. Thus, if your client
machine uses a different representation than you server machine, getting
back attributes in binary format is probably not what you want. Also,
if your main purpose is displaying the data in ASCII, then getting it
back in ASCII will save you some effort on the client side.
3.11) Why doesn't the != operator work?
SQL specifies <> as the inequality operator, and that is what
we have defined for the built-in types. You are free, however, to
extend postgres95 to include the != operator if you like.
3.12) What is a R-tree index and what is it used for?
An r-tree index is used for indexing spatial data. A hash index can't
handle range searches. A B-tree index only handles range searches in a
single dimension. R-tree's can handle multi-dimensional data. For
example, if a R-tree index can be built on an attribute of type
'point', the system can more efficient answer queries like select all
points within a bounding rectangle.
The canonical paper that describes the original R-Tree design is:
Guttman, A. "R-Trees: A Dynamic Index Structure for Spatial Searching."
Proc of the 1984 ACM SIGMOD Int'l Conf on Mgmt of Data, 45-57.
You can also find this paper in Stonebraker's "Readings in Database
Systems"
3.13) What is the maximum size for a tuple?
Tuples are limited to 8K bytes. Taking into account system attributes
and other overhead, one should stay well shy of 8,000 bytes to be on
the safe side. To use attributes larger than 8K, try using the large
objects interface.
Tuples do not cross 8k boundaries so a 5k tuple will require 8k
of storage.
3.14) I defined indices but my queries don't seem to make use of them. Why?
Postgres95 does not automatically maintain statistics. One has to
make an explicit 'vacuum' call to update the statistics. After
statistics are updated, the optimizer has a better shot at using
indices. Note that the optimizer is limited and does not use indices
in some circumstances (such as OR clauses).
If the system still does not see the index, it is probably because you
have created an index on a field with the improper *_ops type. For
example, you have created a CHAR(4) field, but have specified a
char_ops index type_class.
See the create_index manual page for information on what type classes
are available. It must match the field type.
Postgres does not warn the user when the improper index is created.
Indexes not used for ORDER BY operations.
3.15) Are there ODBC drivers for Postgres95?
PostODBC is available as an ODBC driver for Postgres95.
For all people being interested in PostODBC, a freely available ODBC
driver for Postgres95, there are now two mailing lists devoted to the
discussion of PostODBC. The mailing lists are:
postodbc-users@listserv.direct.net
and
postodbc-developers@listserv.direct.net
these lists are ordinary majordomo mailing lists. You can subscribe
by sending a mail to
majordomo@listserv.direct.net
3.16) How do I use postgres for multi-dimensional indexing (> 2 dimensions)?
Builtin R-Trees can handle polygons and boxes. In theory, R-trees can
be extended to handle higher number of dimensions. In practice,
extending R-trees require a bit of work and we don't currently have
any documentation on how to do it.
3.17) How do I do regular expression searches? case-insensitive
regexp searching?
Postgres95 supports the SQL LIKE syntax as well as more general
regular expression searching with the ~ operator. The !~ is the
negated regexp operator. ~* and !~* are the case-insensitive regular
expression operators.
3.18) I can't access the database as the 'root' user.
You should not create database users with user id 0(root). They will
be unable to access the database. This is a security precaution
because of the ability of any user to dynamically link object modules
into the database engine.
3.19) I experienced a server crash during a vacuum. How do I remove the
lock file?
If the server crashes during a vacuum command, chances are it will
leave a lock file hanging around. Attempts to re-run the vacuum
command result in
WARN:can't create lock file -- another vacuum cleaner running?
If you are sure that no vacuum is actually running, you can remove the
file called "pg_vlock" in your database directory (which is
$PGDATA/base/<dbName>)
3.20) What is the difference between the various character types?
Type Internal Name Notes
--------------------------------------------------
CHAR char 1 character }
CHAR2 char2 2 characters }
CHAR4 char4 4 characters } optimized for a fixed length
CHAR8 char8 8 characters }
CHAR16 char16 16 characters }
CHAR(#) bpchar blank padded to the specified fixed length
VARCHAR(#) varchar size specifies maximum length, no padding
TEXT text length limited only by maximum tuple length
BYTEA bytea variable-length array of bytes
Remember, you need to use the internal name when creating indexes
on these fields or when doing other internal operations.
The last four types above are "varlena" types (i.e. the first
four bytes is the length, followed by the data). CHAR(#) and
VARCHAR(#) allocate the maximum number of bytes no matter how
much data is stored in the field. TEXT and BYTEA are the only
character types that have variable length on the disk.
3.21) In a query, how do I detect if a field is NULL?
Postgres95 has two builtin keywords, "isnull" and "notnull" (note no
spaces). For example:
select * from tbl where field isnull
will return rows from tbl where the field is null valued.
3.22) How do I see how the query optimizer is evaluating my query?
Place the word 'EXPLAIN' at the beginning of the query, for example:
EXPLAIN SELECT * FROM table1 WHERE age = 23;
3.23) How do I create a serial field?
There is no way to create a serial or unique field in Postgres95. You
can use each row's oid field as a unique value. However, if you need
to dump and reload the database, you will be assigned new oid's.
There is no way to restore the original oids.
One valid way of doing this is to create a function:
create table my_oids (f1 int4);
insert into my_oids values (1);
create function new_oid () returns int4 as
'update my_oids set f1 = f1 + 1; select f1 from my_oids; '
language 'sql';
then:
create table my_stuff (my_key int4, value text);
insert into my_stuff values (new_oid(), 'hello');
However, keep in mind there is a race condition here where one
server could do the update, then another one do an update, and
they both could select the same new id. This statement should
be performed within a transaction.
3.24) How do I create a multi-column index?
You can not directly create a multi-column index using create index.
You need to define a function which acts on the multiple columns, then
use create index with that function.
3.25) What are the temp_XXX files in my database directory?
They are temp_ files generated by the query executor. For example,
if a sort needs to be done to satisfy an ORDER BY, some temp files are
generated as a result of the sort.
If you have no transactions or sorts running at the time, it is safe to
delete the temp_ files.
3.26) Why are my table files not getting any smaller after a delete?
If you run vacuum, unused rows will be marked for reuse, but the file
blocks are not released. We could move the unused rows to the end of
the file and use ftruncate() to decrease the file size, but no one has
implemented this yet.
3.27) Why can't I connect to my database from another machine?
The default configuration allows only connections from tcp/ip host
localhost. You need to add a host entry to the file
postgres95/data/pg_hba.
3.28) I get the error 'default index class unsupported' when creating an
index. How do I do it?
You probably used:
create index idx1 on person using btree (name);
Postgres95 indexes are extensible, and therefore you must specify a
class_type when creating an index. Read the manual page for create
index (called create_index).
3.29) Why does creating an index crash the backend server?
You have probably defined an incorrect *_ops type class for the field
you are indexing.
3.30) How do I specify a decimal constant as a float8, or a string as a text?
Use the :: operator. It is needed only when the default promotion
rules fail. i.e.:
insert into tab1 values (4.23::float8, '2343'::text)
3.31) How do I find out what indexes or operations are defined in the
database?
Run the file postgres95/src/tutorial/syscat.source. It illustrates
many of the 'select's needed to get information out of the database
system tables.
3.32) My database is corrupt. I can't do anything. What should I do?
The 1.02 release has a README file and utility that describes a
possible cause of the problem and a workaround. See the file
postgres95/contrib/zap_ltv/README for more information. Also
please contact the README author to help generate a complete
fix for this bug.
This bug may be fixed in 1.02.
3.33) Createdb, destroydb, createuser,destroyuser don't run. Why?
Release 1.02 does not have this problem.
The 1.01 release of postgres95 uses a variable called PAGER to
filter the output of SELECT statements. Unfortunately, this
PAGER is used even when the standard output is not a terminal.
Upgrade to 1.02, due out August 1996, or undefine your PAGER
variable. There is also a patch located in the July archives of
the mailing list that fixes this problem on 1.01.
3.34) Why does 'createuser' return 'unexpected last match in input()'?
You have compile postgres with flex version 2.5.3. There is bug
in this version of flex. Use flex version 2.5.2 instead. There
is a doc/README.flex file which will properly patch the flex 2.5.3
source code.
3.35) All my servers crash under concurrent table access. Why?
This problem can be caused by a kernel that is not configured to
support semaphores.
3.36) What tools are available for hooking postgres to Web pages?
For web integration, PHP/FI is an excellent interface. The URL for
that is http://www.vex.net/php/
PHP is great for simple stuff, but for more complex stuff, some
still use the perl interface and CGI.pm.
An example of using WWW with C to talk to Postgres is can be
tried at:
http://www.ki.net/~mlc
3.37) What is the time-warp feature and how does it relate to vacuum?
Postgres95 handles data changes differently than most database
systems. When a row is changed in a table, the original row
is marked with the time it was changed, and a new row is created
with the current data. By default, only current rows are used
in a table. If you specify a date/time after the table name in
a FROM clause, you can access the data that was current at that
time, i.e.
SELECT *
FROM employees ['July 24, 1996 09:00:00']
displays employee rows in the table at the specified time.
You can specify intervals like [date,date], [date,], [,date],
or [,]. This last option accesses all rows that ever existed.
INSERTed rows get a timestamp too, so rows that were not in
the table at the desired time will not appear.
Vacuum removes rows that are no longer current. This time-warp
feature is used by the engine for rollback and crash recovery.
3.38) How do I tune the database engine for better performace?
There are two things that can be done. You can use Openlink's
option to disable fsync() by starting the postmaster with a
'-o -F' option. This will prevent fsync()'s from flushing to
disk after every transaction.
You can also use the postmaster -B option to increase the number
of shared memory buffers shared among the backend processes. If
you make this parameter too high, the process will not start or
crash unexpectedly. Each buffer is 8K and the defualt is 64
buffers.
----------------------------------------------------------------------
Section 4: Extending Postgres95
----------------------------------------------------------------------
4.1) I wrote a user-defined function and when I run it in psql, it
dumps core.
The problem could be a number of things. Try testing your
user-defined function in a stand alone test program first.
Also, make sure you are not sending elog NOTICES when the front-end
is expecting data, such as during a type_in() or type_out()
functions
4.2) I get messages of the type
NOTICE:PortalHeapMemoryFree: 0x402251d0 not in alloc set!
You are pfree'ing something that was not palloc'ed. When writing
user-defined functions, do not include the file
"libpq-fe.h". Doing so will cause your palloc to be a malloc
instead of a free. Then, when the backend pfrees the storage,
you get the notice message.
4.3) I've written some nifty new types and functions for Postgres95.
Please share them with other postgres95 users. Send your
extensions to mailing list, and they will eventually end up in
the contrib/ subdirectory.
4.4) How do I write a C function to return a tuple?
This requires extreme wizardry, so extreme that the authors
have not ever tried it, though in principle it can be done.
The short answer is ... you can't. This capability is
forthcoming in the future.
----------------------------------------------------------------------
Section 5: Bugs
----------------------------------------------------------------------
5.1) How do I find out about bug fixes?
The directory ftp.ki.net:/pub/postgres95 contains patches for
the latest release.
5.2) How do I make a bug report?
First, check to see that your bug is not one that has already
been fixed (question 5.1). Then, fill out the "bug-template"
file and send it to:
pg95-dev@ki.net
This is the address of the developers mailing list.

50
doc/MIGRATION_from_1.0_to_1.01 Normal file
View File

@ -0,0 +1,50 @@
The following notes are for the benefit of users who want to migrate
databases from postgres95 1.0 to postgres95 1.01.
If you are starting afresh with postgres95 1.01 and do not need
to migrate old databases, you do not need to read any further.
----------------------------------------------------------------------
In order to postgres95 version 1.01 with databases created with
postgres95 version 1.0, the following steps are required:
1) Set the definition of NAMEDATALEN in src/Makefile.global to 16
and OIDNAMELEN to 20.
2) Decide whether you want to use Host based authentication.
A) If you do, you must create a file name "pg_hba" in your top-level data
directory (typically the value of your $PGDATA). src/libpq/pg_hba
shows an example syntax.
B) If you do not want host-based authentication, you can comment out
the line
HBA = 1
in src/Makefile.global
Note that host-based authentication is turned on by default, and if
you do not take steps A or B above, the out-of-the-box 1.01 will
not allow you to connect to 1.0 databases.
3) compile and install 1.01, but DO NOT do the initdb step.
4) before doing anything else, terminate your 1.0 postmaster, and
backup your existing $PGDATA directory.
5) set your PGDATA environment variable to your 1.0 databases, but set up
path up so that 1.01 binaries are being used.
6) modify the file $PGDATA/PG_VERSION from 5.0 to 5.1
7) start up a new 1.01 postmaster
5) Add the new built-in functions and operators of 1.01 to 1.0
databases. This is done by running the new 1.01 server against
your own 1.0 database and applying the queries in the file
1.0_to_1.01.sql. This can be done easily through psql. If your
1.0 database is name "testdb":
% psql testdb -f 1.0_to_1.01.sql

32
doc/Makefile Normal file
View File

@ -0,0 +1,32 @@
#-------------------------------------------------------------------------
#
# Makefile
# Makefile for doc directory to install man pages
#
# Copyright (c) 1994, Regents of the University of California
# Copyright (c) 1996, Dr George D Detlefsen
#
#
# IDENTIFICATION
# $Header: /cvsroot/pgsql/doc/Makefile,v 1.1.1.1 1996/08/18 22:14:17 scrappy Exp $
#
#-------------------------------------------------------------------------
MKDIR= ../src/mk
include $(MKDIR)/postgres.mk
CLEANFILES=*
install-man:
-mkdir -p $(POSTMANDIR)
-mkdir $(POSTMANDIR)/man1
-mkdir $(POSTMANDIR)/man3
-mkdir $(POSTMANDIR)/man5
-mkdir $(POSTMANDIR)/manl
cp man/*.1* $(POSTMANDIR)/man1
cp man/*.3* $(POSTMANDIR)/man3
cp man/*.5* $(POSTMANDIR)/man5
cp man/*.l* $(POSTMANDIR)/manl
install:: install-man

28
doc/README.OPENLINK Normal file
View File

@ -0,0 +1,28 @@
varchar.diff
------------
This patch was necessary for the OpenLink Postgres Database Agent.
I think this fixes a bug anyway.
The following query demonstrates this bug:
create table foo (bar varchar);
insert into foo values (''); -- no problem
select * from foo where bar = ''; -- fails
fsync.diff
----------
This patch adds an option to disable synchronous writes.
It adds an extra option to postgres: -F
When started with -F, all fsync() calls will be no-ops,
so you'll be in big trouble when your machine suddenly crashes and your disk
cache is not flushed.
Use at your own risk (but it is *much* faster with large inserts)
This also speeds up initdb for initial database bootstrapping
To start postmaster with this "feature" enabled, type
postmaster -o -F -S

147
doc/README.flex Normal file
View File

@ -0,0 +1,147 @@
From: ernst.molitor@uni-bonn.de
Hi,
thank you for the latest Postgres95 distribution!
>does the createuser bug still persist, or have
>we finally worked that one out?
As has been indication by Bruce Momjian, the createuser problem was
caused by a bug in flex 2.5.3 (which has been confirmed by Vern
Paxson, the flex maintainer - many thanks to them); the bug will be
fixed in flex 2.5.4. Vern Paxson has been so kind as to supply me with
a patch that will be part of the 2.5.4 release; I'm including it below
in case someone has installed flex 2.5.3 and doesn't want to go
back to 2.5.2...
Regards,
Ernst
---
*** flex-2.5.3/flex.skl Sat May 25 21:02:33 1996
--- flex.skl Tue Jul 2 16:35:49 1996
***************
*** 1,7 ****
/* A lexical scanner generated by flex */
/* Scanner skeleton version:
! * $Header: /cvsroot/pgsql/doc/Attic/README.flex,v 1.1.1.1 1996/08/18 22:14:17 scrappy Exp $
*/
#define FLEX_SCANNER
--- 1,7 ----
/* A lexical scanner generated by flex */
/* Scanner skeleton version:
! * $Header: /cvsroot/pgsql/doc/Attic/README.flex,v 1.1.1.1 1996/08/18 22:14:17 scrappy Exp $
*/
#define FLEX_SCANNER
***************
*** 783,789 ****
/* don't do the read, it's not guaranteed to return an EOF,
* just force an EOF
*/
! yy_n_chars = 0;
else
{
--- 783,789 ----
/* don't do the read, it's not guaranteed to return an EOF,
* just force an EOF
*/
! yy_current_buffer->yy_n_chars = yy_n_chars = 0;
else
{
***************
*** 838,843 ****
--- 838,845 ----
/* Read in more data. */
YY_INPUT( (&yy_current_buffer->yy_ch_buf[number_to_move]),
yy_n_chars, num_to_read );
+
+ yy_current_buffer->yy_n_chars = yy_n_chars;
}
if ( yy_n_chars == 0 )
***************
*** 947,953 ****
yy_cp += (int) (dest - source);
yy_bp += (int) (dest - source);
! yy_n_chars = yy_current_buffer->yy_buf_size;
if ( yy_cp < yy_current_buffer->yy_ch_buf + 2 )
YY_FATAL_ERROR( "flex scanner push-back overflow" );
--- 949,956 ----
yy_cp += (int) (dest - source);
yy_bp += (int) (dest - source);
! yy_current_buffer->yy_n_chars =
! yy_n_chars = yy_current_buffer->yy_buf_size;
if ( yy_cp < yy_current_buffer->yy_ch_buf + 2 )
YY_FATAL_ERROR( "flex scanner push-back overflow" );
***************
*** 997,1009 ****
switch ( yy_get_next_buffer() )
{
case EOB_ACT_END_OF_FILE:
{
if ( yywrap() )
- {
- yy_c_buf_p = yytext_ptr + offset;
return EOF;
- }
if ( ! yy_did_buffer_switch_on_eof )
YY_NEW_FILE;
--- 1000,1025 ----
switch ( yy_get_next_buffer() )
{
+ case EOB_ACT_LAST_MATCH:
+ /* This happens because yy_g_n_b()
+ * sees that we've accumulated a
+ * token and flags that we need to
+ * try matching the token before
+ * proceeding. But for input(),
+ * there's no matching to consider.
+ * So convert the EOB_ACT_LAST_MATCH
+ * to EOB_ACT_END_OF_FILE.
+ */
+
+ /* Reset buffer status. */
+ yyrestart( yyin );
+
+ /* fall through */
+
case EOB_ACT_END_OF_FILE:
{
if ( yywrap() )
return EOF;
if ( ! yy_did_buffer_switch_on_eof )
YY_NEW_FILE;
***************
*** 1017,1031 ****
case EOB_ACT_CONTINUE_SCAN:
yy_c_buf_p = yytext_ptr + offset;
break;
-
- case EOB_ACT_LAST_MATCH:
- #ifdef __cplusplus
- YY_FATAL_ERROR(
- "unexpected last match in yyinput()" );
- #else
- YY_FATAL_ERROR(
- "unexpected last match in input()" );
- #endif
}
}
}
--- 1033,1038 ----

35
doc/README.support Normal file
View File

@ -0,0 +1,35 @@
In order to co-ordinate both usage and development of Postgres95,
there are currently two mailing lists available:
General Discussion
- mainly geared towards usage of PostGres95 and associated
support & third-party software
- send a message of subscribe to postgres95-request@postgres95.vnet.net
- a digest version of this list is available. To subscribe, send
a message of subscribe to:
postgres95-digest-request@postgres95.vnet.net
- archives and back issues of these lists are stored on:
ftp://postgres95.vnet.net/pub/postgres95/archives
ftp://postgres95.vnet.net/pub/postgres95/digests
Developers Mailling List
- those wishing to help improve Postgres95 and further develop it
- send a message of subscribe to pg95-dev-request@ki.net
WWW: http://www.ki.net/postgres95
FTP: ftp://ftp.ki.net/pub/postgres95
The current source tree, with all patches installed, is available
via sup @ sup.ki.net, or in a .tar.gz file available at:
ftp://ftp.ki.net/pub/postgres95

24
doc/RELEASE.patchlevel Normal file
View File

@ -0,0 +1,24 @@
From scrappy@ki.net Thu Aug 1 13:39:58 1996
Status: RO
X-Status:
Received: from daemun.ilt.com ([204.247.102.21]) by ki.net (8.7.5/8.7.5) with ESMTP id NAA16984 for <scrappy@ki.net>; Thu, 1 Aug 1996 13:39:51 -0400 (EDT)
From: postgres@madmax.ilt.com
Received: from madmax.ilt.com (madmax [199.26.203.43]) by daemun.ilt.com (8.7.5/8.7.3) with SMTP id KAA02799 for <scrappy@ki.net>; Thu, 1 Aug 1996 10:39:31 -0700 (PDT)
Received: by madmax.ilt.com (SMI-8.6/ILT-SVR4-1.1)
id KAA19226; Thu, 1 Aug 1996 10:34:46 -0700
Date: Thu, 1 Aug 1996 10:34:46 -0700
Message-Id: <199608011734.KAA19226@madmax.ilt.com>
To: scrappy@ki.net
Subject: RELEASE.patchlevel
## Postgres95
##
## This file is used to maintain sequencing of patches
version: 1.02
patch level: 0
patch date: Thu Aug 1 18:00:00 EDT 1996

121
doc/TODO Normal file
View File

@ -0,0 +1,121 @@
From scrappy@ki.net Tue Aug 6 19:57:11 1996
Status: RO
X-Status:
Received: from candle.pha.pa.us (maillist@s1-03.ppp.op.net [206.84.209.132]) by quagmire.ki.net (8.7.5/8.7.5) with ESMTP id TAA01576 for <scrappy@ki.net>; Tue, 6 Aug 1996 19:57:08 -0400 (EDT)
Received: (from maillist@localhost) by candle.pha.pa.us (8.7.4/8.7.3) id TAA11618 for scrappy@ki.net; Tue, 6 Aug 1996 19:57:37 -0400 (EDT)
From: Bruce Momjian <maillist@candle.pha.pa.us>
Message-Id: <199608062357.TAA11618@candle.pha.pa.us>
Subject: add TODO to distribution
To: scrappy@ki.net (Marc G. Fournier)
Date: Tue, 6 Aug 1996 19:57:36 -0400 (EDT)
X-Mailer: ELM [version 2.4 PL25]
MIME-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Here is the current TODO list. Let's add it to the next distribution.
This was not ready at the time of the 1.02 release.
---------------------------------------------------------------------------
=================================================
TODO list (FAQ) for Postgres95
==================================================
last updated: Mon Aug 5 21:00:12 EDT 1996
current maintainer: Bruce Momjian (maillist@candle.pha.pa.us)
original author: Jolly Chen (jolly@cs.berkeley.edu)
RELIABILITY
-----------
Overhaul mdmgr/smgr to fix double unlinking and double opens, cleanup
Memory leaks (hunt and destroy with tools like Purify)
fix unitialized reads of memory
fix array over-runs of memory writes
Re-visit and fix vacuum
can't vacuum large objects
can't shrink tables, pg_time and pg_log
Fix all NULL features
DROP AGGREGATE should take in basetype as an arg
Add other language types for built-in functions
expand to allow tcl, perl, java,
generalize the function manager switch to pass
function sources to interpreter engines.
Fix large object mapping scheme
not to stuff everything as files in a single directory
Fix CLUSTER
Prevent improper index creation
Starting quote in insert string errors
Change default decimal constant representation from float4 to float8
ALTER TABLE bug - running postgress process needs to re-read table definition
Allow libpq to distinguish between text value '' and null
Allow non-postgres users with createdb privs to destroydb's
PERFORMANCE
-----------
Optimizing disjunctive queries
Other optimizer bugs
Is fsync use optimized?
Multi-representational types, a la Illustra. For example, have a
text type that is stored in-tuple when less than 8K and in large
objects, when greater than 8K.
ENHANCEMENTS
------------
Add full ANSI SQL capabilities ( a vendor has offered to help)
add subselects
column constraints (using rules), esp. primary keys
add DEFAULT, UNIQUE, RESTRAINT, and CHECK capabilities
report "Not implemented" if valid syntax is supplied
add OUTER joins
make VIEWs updateable where possible
add UNIONS, INTERSECTS, SUBTRACTS
add temporary tables
add assertions
add domains
add sql3 recursive unions
add the concept of dataspaces
Implement HAVING clause
Implement IN qualifier
Add a way to preserve oid's when doing dump and load
if not, make oid's accessable in insert rules
Add word index for text fields, maybe with trigrams, i.e.:
' (cat | dog) & ! fox ' meaning text has cat or dog, but not fox
Allow compression of large fields or a compressed field type
Fix the rules system
robust
making INSTEAD rules work
Full set of text operations and functions
word searches, concat, upper/lower(), max() on text, char
Replace table-level locking with row or page-level locking
Large objects
overwriting blocks has problems
there are other problems, too.
Better interface for adding to pg_group
Make multi-field indexes easier to create
allow optimizer to effectively use parameters without accessing table
Improve debugging output
Add int8 type
Add table comments
Add support for tables >2G
Incorporate the PERL PG95 interface library into source tree
Threaded version of the server or libpq
Add REGEX internationalization
DOCUMENTATION
-------------
Better documentation. Write a real book on postgres, perhaps?
Document OPENLINK fsync patch
Update usermanual source
Reduce size of regression diffs
PORTABILITY
-----------
Windows NT port
Mariposa project at Berkeley has a person who's working on this
Binary distributions for linux
Merge bsdi_2_1 to bsdi
Merge i386_solaris and sparc_solaris into solaris

41
doc/bug.template Normal file
View File

@ -0,0 +1,41 @@
To report a bug, please complete the following form and send it by
email to pg95-dev@ki.net
============================================================================
POSTGRES95 BUG REPORT TEMPLATE
============================================================================
Your name :
Your email address :
System Configuration
---------------------
Architecture (example: Intel Pentium) :
Operating System (example: Linux 1.3.42 ELF) :
Postgres95 version (example: Postgres95-1.01) : Postgres95-1.02
Compiler used (example: gcc 2.7.0) :
Please enter a FULL description of your problem:
------------------------------------------------
Please describe a way to repeat the problem. Please try to provide a
concise reproducible example, if at all possible:
----------------------------------------------------------------------
If you know how this problem might be fixed, list the solution below:
---------------------------------------------------------------------

181
doc/libpgtcl.doc Normal file
View File

@ -0,0 +1,181 @@
pgtcl is a tcl package for front-end programs to interface with Postgres95
backends. PgTcl does not use the libpq library but communicates to
the backend directly via the frontend-backend protocol. Thus, it is
more efficient than previous postgres->tcl bindings which are layered
on top of libpq. In addition, pgtcl can handle multiple backend
connections from a single frontend application.
If you have any questions or bug reports, please send them to
Jolly Chen at jolly@cs.berkeley.edu.
-------------------------------------------------------------------
The pgtcl package provides the following commands.
pg_connect - opens a connection to the backend server
pg_disconnect - closes a connection
pg_exec - send a query to the backend
pg_result - manipulate the results of a query
pg_lo_creat - create a large object
pg_lo_open - open a large object
pg_lo_close - close a large object
pg_lo_read - read a large object
pg_lo_write - write a large object
pg_lo_lseek - seek to a position on a large object
pg_lo_tell - return the current seek position of a large object
pg_lo_unlink - delete a large object
pg_lo_import - import a Unix file into a large object
pg_lo_export - export a large object into a Unix file
1) pg_connect: opens a connection to the backend
syntax:
pg_connect dbName [-host hostName] [-port portNumber] [-tty pqtty] [-options optionalBackendArgs]]
the return result is either an error message or a handle for a database
connection. Handles start with the prefix "pgp"
2) pg_disconnect: closes a connection
syntax:
pg_disconnect connection
The argument passed in must be a connection pointer.
3) pg_exec: send a query string to the backend
syntax:
pg_exec connection query
the return result is either an error message or a handle for a query
result. Handles start with the prefix "pgp"
4) pg_result: get information about a query result
syntax:
pg_result result ?option?
the options are:
-status
the status of the result
-oid
if the last query was an insert, returns the oid of the
inserted tuple
-conn
the connection that produced the result
-assign arrayName
assign the results to an array
-numTuples
the number of tuples in the query
-attributes
returns a list of the name/type pairs of the tuple attributes
-getTuple tupleNumber
returns the values of the tuple in a list
-clear
clear the result buffer. Do not reuse after this
----------------------------------------------------------------------------
The pg_lo* routines are interfaces to the Inversion large objects in postgres.
The functions are designed to mimic the analogous file system functions in
the standard Unix file system interface.
The pg_lo* routines should typically be used within a BEGIN/END transaction
block becaus the file descriptor returned by pg_lo_open is only valid for
the current transaction. pg_lo_import and pg_lo_export MUST be used
in a BEGIN/END transaction block.
* pg_lo_creat: create a large object
syntax:
g_lo_creat conn mode
mode can be any OR'ing together of INV_READ, INV_WRITE, and INV_ARCHIVE.
The OR delimiter character is "|".
e.g. [pg_lo_creat $conn "INV_READ|INV_WRITE"]
returns the oid of the large object created.
* pg_lo_open: open a large object
syntax:
pg_lo_open conn objOid mode
where mode can be either "r", "w", or "rw"
returns a file descriptor for use in later pg_lo* routines
* pg_lo_close: close a large object
syntax:
pg_lo_close conn fd
* pg_lo_read: read a large object
syntax:
pg_lo_read conn fd bufVar len
reads at most len bytes from a large object into a variable named bufVar.
Note that the third argument should be a variable name.
* pg_lo_write: write a large object
syntax:
pg_lo_write conn fd buf len
write at most len bytes to a large object.
The third argument should be the actual string to write, not a variable name.
* pg_lo_lseek: seek to a position on a large object
syntax:
pg_lo_lseek conn fd offset whence
whence can be "SEEK_CUR", "SEEK_END", or "SEEK_SET"
* pg_lo_tell: return the current seek position of a large object
syntax:
pg_lo_tell conn fd
* pg_lo_unlink: delete a large object
syntax:
pg_lo_unlink conn lobjId
* pg_lo_import: import a Unix file into a large object
syntax:
pg_lo_import conn filename
pg_lo_import must be called within a BEGIN/END transaction block
* pg_lo_export: export a large object into a Unix file
syntax:
pg_lo_export conn lobjId filename
pg_lo_export must be called within a BEGIN/END transaction block
------------------------------------------------------------------
Here's a small example of how to use the routines:
# getDBs :
# get the names of all the databases at a given host and port number
# with the defaults being the localhost and port 5432
# return them in alphabetical order
proc getDBs { {host "localhost"} {port "5432"} } {
# datnames is the list to be result
set conn [pg_connect template1 -host $host -port $port]
set res [pg_exec $conn "SELECT datname FROM pg_database ORDER BY datname"]
set ntups [pg_result $res -numTuples]
for {set i 0} {$i < $ntups} {incr i} {
lappend datnames [pg_result $res -getTuple $i]
}
pg_disconnect $conn
return $datnames
}

3
doc/man/README Normal file
View File

@ -0,0 +1,3 @@
The page.5 source should be run through pic when generating troff
output. nroff doesn't handle pic.

23
doc/man/abort.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/abort.l,v 1.1.1.1 1996/08/18 22:14:19 scrappy Exp $
.TH ABORT SQL 01/23/93 Postgres95 Postgres95
.\" XXX This .XA has to go after the .TH so that the index page number goes
.\" in the right place...
.SH Abort
.SH NAME
abort \(em abort the current transaction
.SH SYNOPSIS
.nf
\fBabort\fP \fB[transaction]\fR
.fi
.SH DESCRIPTION
This command aborts the current transaction and causes all the
updates made by the transaction to be discarded.
.IR "abort"
is functionally equivalent to
.IR "rollback".
.SH "SEE ALSO"
begin(l),
end(l),
rollback(l).

61
doc/man/alter_table.l Normal file
View File

@ -0,0 +1,61 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/alter_table.l,v 1.1.1.1 1996/08/18 22:14:19 scrappy Exp $
.TH "ALTER TABLE" SQL 11/5/95 Postgres95 Postgres95
.SH NAME
alter table \(em add attributes to a class
.SH SYNOPSIS
.nf
\fBalter table\fR classname [*]
\fBadd column\fR attname type
.fi
.SH DESCRIPTION
The
.BR "alter table"
command
causes a new attribute to be added to an existing class,
.IR classname .
The new attributes and their types are specified
in the same style and with the the same restrictions as in
.IR create table (l).
.PP
In order to add an attribute to each class in an entire inheritance
hierarchy, use the
.IR classname
of the superclass and append a \*(lq*\*(rq. (By default, the
attribute will not be added to any of the subclasses.) This should
.BR always
be done when adding an attribute to a superclass. If it is not,
queries on the inheritance hierarchy such as
.nf
select * from super* s
.fi
will not work because the subclasses will be missing an attribute
found in the superclass.
.PP
For efficiency reasons, default values for added attributes are not
placed in existing instances of a class. That is, existing instances
will have NULL values in the new attributes. If non-NULL values are
desired, a subsequent
.IR update (l)
query should be run.
.PP
You must own the class in order to change its schema.
.SH EXAMPLE
.nf
--
-- add the date of hire to the emp class
--
alter table emp add column hiredate abstime
.fi
.nf
--
-- add a health-care number to all persons
-- (including employees, students, ...)
--
alter table person * add column health_care_id int4
.fi
.SH "SEE ALSO"
create table (l),
update (l).

20
doc/man/begin.l Normal file
View File

@ -0,0 +1,20 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/begin.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH BEGIN SQL 11/05/95 Postgres95 Postgres95
.SH NAME
begin \(em begins a transaction
.SH SYNOPSIS
.nf
\fBbegin\fP \fB[transaction|work]\fR
.fi
.SH DESCRIPTION
This command begins a user transaction which Postgres will guarantee is
serializable with respect to all concurrently executing transactions.
Postgres uses two-phase locking to perform this task. If the transaction
is committed, Postgres will ensure that all updates are done or none of
them are done. Transactions have the standard ACID (atomic,
consistent, isolatable, and durable) property.
.SH "SEE ALSO"
abort(l),
end(l).

224
doc/man/bki.5 Normal file
View File

@ -0,0 +1,224 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/bki.5,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH BKI FILES 01/23/93 Postgres95 Postgres95
.SH NAME
\&.../src/backend/obj/{local,dbdb}.bki \(em template scripts
.SH DESCRIPTION
Backend Interface (BKI) files are scripts that describe the contents
of the initial Postgres database. This database is constructed during
system installation, by the
.IR initdb
command.
.IR Initdb
executes the Postgres backend with a special set of flags, that cause it
to consume the BKI scripts and bootstrap a database.
.PP
These files are automatically generated from system header files
during installation. They are not intended for use by humans, and you
do not need to understand their contents in order to use Postgres. These
files are copied to
.nf
\&.../files/{global1,local1_XXX}.bki
.fi
during system installation.
.PP
All new user databases will be created by copying the template
database that Postgres constructs from the BKI files. Thus, a simple way
to customize the template database is to let the Postgres initialization
script create it for you, and then to run the terminal monitor to make
the changes you want.
.PP
The Postgres backend interprets BKI files as described below. This
description will be easier to understand if the example in
\*(lq.../files/global1.bki\*(rq is at hand.
.PP
Commands are composed of a command name followed by space separated
arguments. Arguments to a command which begin with a \*(lq$\*(rq are
treated specially. If \*(lq$$\*(rq are the first two characters, then
the first \*(lq$\*(rq is ignored and the argument is then processed
normally. If the \*(lq$\*(rq is followed by space, then it is treated
as a
.SM NULL
value. Otherwise, the characters following the \*(lq$\*(rq are
interpreted as the name of a macro causing the argument to be replaced
with the macro's value. It is an error for this macro to be
undefined.
.PP
Macros are defined using
.nf
define macro macro_name = macro_value
.fi
and are undefined using
.nf
undefine macro macro_name
.fi
and redefined using the same syntax as define.
.PP
Lists of general commands and macro commands
follow.
.SH "GENERAL COMMANDS"
.TP 5n
.BR "open" " classname"
Open the class called
.IR classname
for further manipulation.
.TP
.BR "close" " [classname]"
Close the open class called
.IR classname.
It is an error if
.IR classname
is not already opened. If no
.IR classname
is given, then the currently open class is closed.
.TP
.BR print
Print the currently open class.
.TP
.BR "insert" " [oid=oid_value] " "(" " value1 value2 ... " ")"
Insert a new instance to the open class using
.IR value1 ,
.IR value2 ,
etc., for its attribute values and
.IR oid_value
for its OID. If
.IR oid_value
is not \*(lq0\*(rq, then this value will be used as the instance's
object identifier. Otherwise, it is an error.
.TP
.BR "insert (" " value1 value2 ... " ")"
As above, but the system generates a unique object identifier.
.TP
.BR "create" " classname " "(" " name1 = type1, name2 = type2, ... " ")"
Create a class named
.IR classname
with the attributes given in parentheses.
.TP
.BR "open (" " name1 = type1, name2 = type2,... " ") as" " classname"
Open a class named
.IR classname
for writing but do not record its existence in the system catalogs.
(This is primarily to aid in bootstrapping.)
.TP
.BR "destroy" " classname"
Destroy the class named
.IR classname .
.TP
.BR "define index" " index-name " "on" " class-name " "using" " amname "
( opclass attr | function({attr}) )
.br
Create an index named
.IR index_name
on the class named
.IR classname
using the
.IR amname
access method. The fields to index are called
.IR name1 ,
.IR name2 ,
etc., and the operator collections to use are
.IR collection_1 ,
.IR collection_2 ,
etc., respectively.
.SH "MACRO COMMANDS"
.TP
.BR "define function" " macro_name " "as" " rettype function_name ( args )"
Define a function prototype for a function named
.IR macro_name
which has its value of type
.IR rettype
computed from the execution
.IR function_name
with the arguments
.IR args
declared in a C-like manner.
.TP
.BR "define macro" " macro_name " "from file" " filename"
Define a macro named
.IR macname
which has its value
read from the file called
.IR filename .
.\" .uh "DEBUGGING COMMANDS"
.\" .sp
.\" .in .5i
.\" r
.\" .br
.\" Randomly print the open class.
.\" .sp
.\" m -1
.\" .br
.\" Toggle display of time information.
.\" .sp
.\" m 0
.\" .br
.\" Set retrievals to now.
.\" .sp
.\" m 1 Jan 1 01:00:00 1988
.\" .br
.\" Set retrievals to snapshots of the specfied time.
.\" .sp
.\" m 2 Jan 1 01:00:00 1988, Feb 1 01:00:00 1988
.\" .br
.\" Set retrievals to ranges of the specified times.
.\" Either time may be replaced with space
.\" if an unbounded time range is desired.
.\" .sp
.\" \&.A classname natts name1 type1 name2 type2 ...
.\" .br
.\" Add attributes named
.\" .ul
.\" name1,
.\" .ul
.\" name2,
.\" etc. of
.\" types
.\" .ul
.\" type1,
.\" .ul
.\" type2,
.\" etc. to the
.\" .ul
.\" class
.\" classname.
.\" .sp
.\" \&.RR oldclassname newclassname
.\" .br
.\" Rename the
.\" .ul
.\" oldclassname
.\" class to
.\" .ul
.\" newclassname.
.\" .sp
.\" \&.RA classname oldattname newattname
.\" .br
.\" Rename the
.\" .ul
.\" oldattname
.\" attribute in the class named
.\" .ul
.\" classname
.\" to
.\" .ul
.\" newattname.
.SH EXAMPLE
The following set of commands will create the \*(lqpg_opclass\*(rq
class containing the
.IR int_ops
collection as object
.IR 421,
print out the class, and then close it.
.nf
create pg_opclass (opcname=char16)
open pg_opclass
insert oid=421 (int_ops)
print
close pg_opclass
.fi
.SH "SEE ALSO"
initdb(1),
createdb(1),
createdb(l),
template(files).

700
doc/man/built-in.3 Normal file
View File

@ -0,0 +1,700 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/built-in.3,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH BUILT-INS INTRO 11/05/95 Postgres95 Postgres95
.SH "DESCRIPTION"
This section describes the data types, functions and operators
available to users in Postgres as it is distributed.
.SH "Built-in and System Types"
.SH "BUILT-IN TYPES"
This section describes both
.BR built-in
data types.
These Built-in types are
are installed in every database.
.PP
Users may add new types to Postgres using the
.IR "define type"
command described in this manual. User-defined types are not
described in this section.
.SH "List of built-in types"
.PP
.if n .ta 5 +15 +40
.if t .ta 0.5i +1.5i +3.0i
.in 0
.nf
\fBPOSTGRES Type\fP \fBMeaning\fP
abstime absolute date and time
aclitem access control list item
bool boolean
box 2-dimensional rectangle
bpchar blank-padded characters
bytea variable length array of bytes
char character
char2 array of 2 characters
char4 array of 4 characters
char8 array of 8 characters
char16 array of 16 characters
cid command identifier type
date ANSI SQL date type
filename large object filename
int alias for int4
integer alias for int4
int2 two-byte signed integer
int28 array of 8 int2
int4 four-byte signed integer
float alias for float4
float4 single-precision floating-point number
float8 double-precision floating-point number
lseg 2-dimensional line segment
name a multi-character type for storing system identifiers
oid object identifier type
oid8 array of 8 oid
oidchar16 oid and char16 composed
oidint2 oid and int2 composed
oidint4 oid and int4 composed
path variable-length array of lseg
point 2-dimensional geometric point
polygon 2-dimensional polygon
real alias for float4
regproc registered procedure
reltime relative date and time
smgr storage manager
smallint alias for int2
text variable length array of characters
tid tuple identifier type
time ANSI SQL time type
tinterval time interval
varchar variable-length characters
xid transaction identifier type
.fi
.in
.PP
As a rule, the built-in types are all either (1) internal types, in
which case the user should not worry about their external format, or
(2) have obvious formats. The exceptions to this rule are the three
time types.
.SH "Syntax of date and time types"
.SH "ABSOLUTE TIME"
Absolute time is specified using the following syntax:
.nf
Month Day [ Hour : Minute : Second ] Year [ Timezone ]
.sp
where
Month is Jan, Feb, ..., Dec
Day is 1, 2, ..., 31
Hour is 01, 02, ..., 24
Minute is 00, 01, ..., 59
Second is 00, 01, ..., 59
Year is 1901, 1902, ..., 2038
.fi
Valid dates are from Dec 13 20:45:53 1901 GMT to Jan 19 03:14:04
2038 GMT. As of Version 3.0, times are no longer read and written
using Greenwich Mean Time; the input and output routines default to
the local time zone.
.PP
The special absolute time values \*(lqcurrent\*(rq,
\*(lqinfinity\*(rq and \*(lq-infinity\*(rq are also provided.
\*(lqinfinity\*(rq specifies a time later than any valid time, and
\*(lq-infinity\*(rq specifies a time earlier than any valid time.
\*(lqcurrent\*(rq indicates that the current time should be
substituted whenever this value appears in a computation.
.PP
The strings \*(lqnow\*(rq and \*(lqepoch\*(rq can be used to specify
time values. \*(lqnow\*(rq means the current time, and differs from
\*(lqcurrent\*(rq in that the current time is immediately substituted
for it. \*(lqepoch\*(rq means Jan 1 00:00:00 1970 GMT.
.SH "RELATIVE TIME"
Relative time is specified with the following syntax:
.nf
@ Quantity Unit [Direction]
.sp
where
Quantity is `1', `2', ...
Unit is ``second'', ``minute'', ``hour'', ``day'', ``week'',
``month'' (30-days), or ``year'' (365-days),
or PLURAL of these units.
Direction is ``ago''
.fi
.PP
.RB ( Note :
Valid relative times are less than or equal to 68 years.)
In addition, the special relative time \*(lqUndefined RelTime\*(rq is
provided.
.SH "TIME RANGES"
Time ranges are specified as:
.nf
[ 'abstime' 'abstime']
.fi
where
.IR abstime
is a time in the absolute time format. Special abstime values such as
\*(lqcurrent\*(rq, \*(lqinfinity\*(rq and \*(lq-infinity\*(rq can be used.
.SH "Built-in operators and functions"
.SH OPERATORS
Postgres provides a large number of built-in operators on system types.
These operators are declared in the system catalog
\*(lqpg_operator\*(rq. Every entry in \*(lqpg_operator\*(rq includes
the object ID of the procedure that implements the operator.
.PP
Users may invoke operators using the operator name, as in
.nf
select * from emp where salary < 40000;
.fi
Alternatively, users may call the functions that implement the
operators directly. In this case, the query above would be expressed
as
.nf
select * from emp where int4lt(salary, 40000);
.fi
The rest of this section provides a list of the built-in operators and
the functions that implement them. Binary operators are listed first,
followed by unary operators.
.SH "BINARY OPERATORS"
This list was generated from the Postgres system catalogs with the
query:
.nf
SELECT
t0.typname AS result,
t1.typname AS left_type,
t2.typname AS right_type,
o.oprname AS operatr,
p.proname AS func_name
FROM pg_proc p, pg_type t0,
pg_type t1, pg_type t2,
pg_operator o
WHERE p.prorettype = t0.oid AND
RegprocToOid(o.oprcode) = p.oid AND
p.pronargs = 2 AND
o.oprleft = t1.oid AND
o.oprright = t2.oid
ORDER BY result, left_type, right_type, operatr;
.fi
These operations are cast in terms of SQL types and so are
.BR not
directly usable as C function prototypes.
.nf
Operators:
general
<\(eq less or equal
<> inequality
< less than
<\(eq greater or equal
>\(eq greater or equal
> greater than
\(eq equality
~ A matches regular expression B, case-sensitive
!~ A does not match regular expression B, case-sensitive
~* A matches regular expression B, case-insensitive.
!~* A does not match regular expression B, case-insensitive
~~ A matches LIKE expression B, case-sensitive
!~~ A does not match LIKE expression B, case-sensitive
+ addition
\(mi subtraction
* multiplication
/ division
% modulus
@ absolute value
float8
^ exponentiation
% truncate to integer
|/ square root
||/ cube root
: exponential function
; natural logarithm
point
!< A is left of B
!> A is right of B
!^ A is above B
!| A is below B
\(eq|\(eq equality
===> point inside box
===` point on path
<===> distance between points
box
&& boxes overlap
&< box A overlaps box B, but does not extend to right of box B
&> box A overlaps box B, but does not extend to left of box B
<< A is left of B
\(eq area equal
< area less than
<\(eq area less or equal
>\(eq area greater or equal
> area greater than
>> A is right of B
@ A is contained in B
~\(eq box equality
~= A same as B
~ A contains B
@@ center of box
polygon
&& polygons overlap
&< A overlaps B but does not extend to right of B
&> A overlaps B but does not extend to left of B
<< A is left of B
>> A is right of B
@ A is contained by B
~\(eq equality
~= A same as B
~ A contains B
tinterval
#<\(eq interval length less or equal reltime
#<> interval length not equal to reltime.
#< interval length less than reltime
#\(eq interval length equal to reltime
#>\(eq interval length greater or equal reltime
#> interval length greater than reltime
&& intervals overlap
<< A contains B
\(eq equality
<> interval bounded by two abstimes
<?> abstime in tinterval
| start of interval
<#> convert to interval
result |left_type |right_type|operatr|func_name
---------+----------+----------+-------+---------------
_aclitem |_aclitem |aclitem |+ |aclinsert
_aclitem |_aclitem |aclitem |- |aclremove
abstime |abstime |reltime |+ |timepl
abstime |abstime |reltime |- |timemi
bool |_abstime |_abstime |= |array_eq
bool |_aclitem |_aclitem |= |array_eq
bool |_aclitem |aclitem |~ |aclcontains
bool |_bool |_bool |= |array_eq
bool |_box |_box |= |array_eq
bool |_bytea |_bytea |= |array_eq
bool |_char |_char |= |array_eq
bool |_char16 |_char16 |= |array_eq
bool |_cid |_cid |= |array_eq
bool |_filename |_filename |= |array_eq
bool |_float4 |_float4 |= |array_eq
bool |_float8 |_float8 |= |array_eq
bool |_int2 |_int2 |= |array_eq
bool |_int28 |_int28 |= |array_eq
bool |_int4 |_int4 |= |array_eq
bool |_lseg |_lseg |= |array_eq
bool |_name |_name |= |array_eq
bool |_oid |_oid |= |array_eq
bool |_oid8 |_oid8 |= |array_eq
bool |_path |_path |= |array_eq
bool |_point |_point |= |array_eq
bool |_polygon |_polygon |= |array_eq
bool |_ref |_ref |= |array_eq
bool |_regproc |_regproc |= |array_eq
bool |_reltime |_reltime |= |array_eq
bool |_stub |_stub |= |array_eq
bool |_text |_text |= |array_eq
bool |_tid |_tid |= |array_eq
bool |_tinterval|_tinterval|= |array_eq
bool |_xid |_xid |= |array_eq
bool |abstime |abstime |< |abstimelt
bool |abstime |abstime |<= |abstimele
bool |abstime |abstime |<> |abstimene
bool |abstime |abstime |= |abstimeeq
bool |abstime |abstime |> |abstimegt
bool |abstime |abstime |>= |abstimege
bool |abstime |tinterval |<?> |ininterval
bool |bool |bool |<> |boolne
bool |bool |bool |= |booleq
bool |box |box |&& |box_overlap
bool |box |box |&< |box_overleft
bool |box |box |&> |box_overright
bool |box |box |< |box_lt
bool |box |box |<< |box_left
bool |box |box |<= |box_le
bool |box |box |= |box_eq
bool |box |box |> |box_gt
bool |box |box |>= |box_ge
bool |box |box |>> |box_right
bool |box |box |@ |box_contained
bool |box |box |~ |box_contain
bool |box |box |~= |box_same
bool |bpchar |bpchar |< |bpcharlt
bool |bpchar |bpchar |<= |bpcharle
bool |bpchar |bpchar |<> |bpcharne
bool |bpchar |bpchar |= |bpchareq
bool |bpchar |bpchar |> |bpchargt
bool |bpchar |bpchar |>= |bpcharge
bool |bpchar |text |!~ |textregexne
bool |bpchar |text |!~* |texticregexne
bool |bpchar |text |!~~ |textnlike
bool |bpchar |text |~ |textregexeq
bool |bpchar |text |~* |texticregexeq
bool |bpchar |text |~~ |textlike
bool |char |char |< |charlt
bool |char |char |<= |charle
bool |char |char |<> |charne
bool |char |char |= |chareq
bool |char |char |> |chargt
bool |char |char |>= |charge
bool |char16 |char16 |< |char16lt
bool |char16 |char16 |<= |char16le
bool |char16 |char16 |<> |char16ne
bool |char16 |char16 |= |char16eq
bool |char16 |char16 |> |char16gt
bool |char16 |char16 |>= |char16ge
bool |char16 |text |!~ |char16regexne
bool |char16 |text |!~* |char16icregexne
bool |char16 |text |!~~ |char16nlike
bool |char16 |text |!~~ |char16nlike
bool |char16 |text |~ |char16regexeq
bool |char16 |text |~* |char16icregexeq
bool |char16 |text |~~ |char16like
bool |char16 |text |~~ |char16like
bool |char2 |char2 |< |char2lt
bool |char2 |char2 |<= |char2le
bool |char2 |char2 |<> |char2ne
bool |char2 |char2 |= |char2eq
bool |char2 |char2 |> |char2gt
bool |char2 |char2 |>= |char2ge
bool |char2 |text |!~ |char2regexne
bool |char2 |text |!~* |char2icregexne
bool |char2 |text |!~~ |char2nlike
bool |char2 |text |~ |char2regexeq
bool |char2 |text |~* |char2icregexeq
bool |char2 |text |~~ |char2like
bool |char4 |char4 |< |char4lt
bool |char4 |char4 |<= |char4le
bool |char4 |char4 |<> |char4ne
bool |char4 |char4 |= |char4eq
bool |char4 |char4 |> |char4gt
bool |char4 |char4 |>= |char4ge
bool |char4 |text |!~ |char4regexne
bool |char4 |text |!~* |char4icregexne
bool |char4 |text |!~~ |char4nlike
bool |char4 |text |~ |char4regexeq
bool |char4 |text |~* |char4icregexeq
bool |char4 |text |~~ |char4like
bool |char8 |char8 |< |char8lt
bool |char8 |char8 |<= |char8le
bool |char8 |char8 |<> |char8ne
bool |char8 |char8 |= |char8eq
bool |char8 |char8 |> |char8gt
bool |char8 |char8 |>= |char8ge
bool |char8 |text |!~ |char8regexne
bool |char8 |text |!~* |char8icregexne
bool |char8 |text |!~~ |char8nlike
bool |char8 |text |~ |char8regexeq
bool |char8 |text |~* |char8icregexeq
bool |char8 |text |~~ |char8like
bool |date |date |< |date_lt
bool |date |date |<= |date_le
bool |date |date |<> |date_ne
bool |date |date |= |date_eq
bool |date |date |> |date_gt
bool |date |date |>= |date_ge
bool |float4 |float4 |< |float4lt
bool |float4 |float4 |<= |float4le
bool |float4 |float4 |<> |float4ne
bool |float4 |float4 |= |float4eq
bool |float4 |float4 |> |float4gt
bool |float4 |float4 |>= |float4ge
bool |float4 |float8 |< |float48lt
bool |float4 |float8 |<= |float48le
bool |float4 |float8 |<> |float48ne
bool |float4 |float8 |= |float48eq
bool |float4 |float8 |> |float48gt
bool |float4 |float8 |>= |float48ge
bool |float8 |float4 |< |float84lt
bool |float8 |float4 |<= |float84le
bool |float8 |float4 |<> |float84ne
bool |float8 |float4 |= |float84eq
bool |float8 |float4 |> |float84gt
bool |float8 |float4 |>= |float84ge
bool |float8 |float8 |< |float8lt
bool |float8 |float8 |<= |float8le
bool |float8 |float8 |<> |float8ne
bool |float8 |float8 |= |float8eq
bool |float8 |float8 |> |float8gt
bool |float8 |float8 |>= |float8ge
bool |int2 |int2 |< |int2lt
bool |int2 |int2 |<= |int2le
bool |int2 |int2 |<> |int2ne
bool |int2 |int2 |= |int2eq
bool |int2 |int2 |> |int2gt
bool |int2 |int2 |>= |int2ge
bool |int4 |int4 |< |int4lt
bool |int4 |int4 |<= |int4le
bool |int4 |int4 |<> |int4ne
bool |int4 |int4 |= |int4eq
bool |int4 |int4 |> |int4gt
bool |int4 |int4 |>= |int4ge
bool |int4 |name |!!= |int4notin
bool |int4 |oid |= |int4eqoid
bool |name |name |< |namelt
bool |name |name |<= |namele
bool |name |name |<> |namene
bool |name |name |= |nameeq
bool |name |name |> |namegt
bool |name |name |>= |namege
bool |name |text |!~ |nameregexne
bool |name |text |!~* |nameicregexne
bool |name |text |!~~ |namenlike
bool |name |text |~ |nameregexeq
bool |name |text |~* |nameicregexeq
bool |name |text |~~ |namelike
bool |oid |int4 |= |oideqint4
bool |oid |name |!!= |oidnotin
bool |oid |oid |< |int4lt
bool |oid |oid |<= |int4le
bool |oid |oid |<> |oidne
bool |oid |oid |= |oideq
bool |oid |oid |> |int4gt
bool |oid |oid |>= |int4ge
bool |oidint2 |oidint2 |< |oidint2lt
bool |oidint2 |oidint2 |<= |oidint2le
bool |oidint2 |oidint2 |<> |oidint2ne
bool |oidint2 |oidint2 |= |oidint2eq
bool |oidint2 |oidint2 |> |oidint2gt
bool |oidint2 |oidint2 |>= |oidint2ge
bool |oidint4 |oidint4 |< |oidint4lt
bool |oidint4 |oidint4 |<= |oidint4le
bool |oidint4 |oidint4 |<> |oidint4ne
bool |oidint4 |oidint4 |= |oidint4eq
bool |oidint4 |oidint4 |> |oidint4gt
bool |oidint4 |oidint4 |>= |oidint4ge
bool |oidname |oidname |< |oidnamelt
bool |oidname |oidname |<= |oidnamele
bool |oidname |oidname |<> |oidnamene
bool |oidname |oidname |= |oidnameeq
bool |oidname |oidname |> |oidnamegt
bool |oidname |oidname |>= |oidnamege
bool |point |box |===> |on_pb
bool |point |path |===` |on_ppath
bool |point |point |!< |point_left
bool |point |point |!> |point_right
bool |point |point |!^ |point_above
bool |point |point |!\| |point_below
bool |point |point |=\|= |point_eq
bool |polygon |polygon |&& |poly_overlap
bool |polygon |polygon |&< |poly_overleft
bool |polygon |polygon |&> |poly_overright
bool |polygon |polygon |<< |poly_left
bool |polygon |polygon |>> |poly_right
bool |polygon |polygon |@ |poly_contained
bool |polygon |polygon |~ |poly_contain
bool |polygon |polygon |~= |poly_same
bool |reltime |reltime |< |reltimelt
bool |reltime |reltime |<= |reltimele
bool |reltime |reltime |<> |reltimene
bool |reltime |reltime |= |reltimeeq
bool |reltime |reltime |> |reltimegt
bool |reltime |reltime |>= |reltimege
bool |text |text |!~ |textregexne
bool |text |text |!~* |texticregexne
bool |text |text |!~~ |textnlike
bool |text |text |< |text_lt
bool |text |text |<= |text_le
bool |text |text |<> |textne
bool |text |text |= |texteq
bool |text |text |> |text_gt
bool |text |text |>= |text_ge
bool |text |text |~ |textregexeq
bool |text |text |~* |texticregexeq
bool |text |text |~~ |textlike
bool |time |time |< |time_lt
bool |time |time |<= |time_le
bool |time |time |<> |time_ne
bool |time |time |= |time_eq
bool |time |time |> |time_gt
bool |time |time |>= |time_ge
bool |tinterval |reltime |#< |intervallenlt
bool |tinterval |reltime |#<= |intervallenle
bool |tinterval |reltime |#<> |intervallenne
bool |tinterval |reltime |#= |intervalleneq
bool |tinterval |reltime |#> |intervallengt
bool |tinterval |reltime |#>= |intervallenge
bool |tinterval |tinterval |&& |intervalov
bool |tinterval |tinterval |<< |intervalct
bool |tinterval |tinterval |= |intervaleq
bool |varchar |text |!~ |textregexne
bool |varchar |text |!~* |texticregexne
bool |varchar |text |!~~ |textnlike
bool |varchar |text |~ |textregexeq
bool |varchar |text |~* |texticregexeq
bool |varchar |text |~~ |textlike
bool |varchar |varchar |< |varcharlt
bool |varchar |varchar |<= |varcharle
bool |varchar |varchar |<> |varcharne
bool |varchar |varchar |= |varchareq
bool |varchar |varchar |> |varchargt
bool |varchar |varchar |>= |varcharge
char |char |char |* |charmul
char |char |char |+ |charpl
char |char |char |- |charmi
char |char |char |/ |chardiv
float4 |float4 |float4 |* |float4mul
float4 |float4 |float4 |+ |float4pl
float4 |float4 |float4 |- |float4mi
float4 |float4 |float4 |/ |float4div
float8 |float4 |float8 |* |float48mul
float8 |float4 |float8 |+ |float48pl
float8 |float4 |float8 |- |float48mi
float8 |float4 |float8 |/ |float48div
float8 |float8 |float4 |* |float84mul
float8 |float8 |float4 |+ |float84pl
float8 |float8 |float4 |- |float84mi
float8 |float8 |float4 |/ |float84div
float8 |float8 |float8 |* |float8mul
float8 |float8 |float8 |+ |float8pl
float8 |float8 |float8 |- |float8mi
float8 |float8 |float8 |/ |float8div
float8 |float8 |float8 |^ |dpow
int2 |int2 |int2 |% |int2mod
int2 |int2 |int2 |* |int2mul
int2 |int2 |int2 |+ |int2pl
int2 |int2 |int2 |- |int2mi
int2 |int2 |int2 |/ |int2div
int4 |int2 |int4 |% |int24mod
int4 |int2 |int4 |* |int24mul
int4 |int2 |int4 |+ |int24pl
int4 |int2 |int4 |- |int24mi
int4 |int2 |int4 |/ |int24div
int4 |int2 |int4 |< |int24lt
int4 |int2 |int4 |<= |int24le
int4 |int2 |int4 |<> |int24ne
int4 |int2 |int4 |= |int24eq
int4 |int2 |int4 |> |int24gt
int4 |int2 |int4 |>= |int24ge
int4 |int4 |int2 |% |int42mod
int4 |int4 |int2 |* |int42mul
int4 |int4 |int2 |+ |int42pl
int4 |int4 |int2 |- |int42mi
int4 |int4 |int2 |/ |int42div
int4 |int4 |int2 |< |int42lt
int4 |int4 |int2 |<= |int42le
int4 |int4 |int2 |<> |int42ne
int4 |int4 |int2 |= |int42eq
int4 |int4 |int2 |> |int42gt
int4 |int4 |int2 |>= |int42ge
int4 |int4 |int4 |% |int4mod
int4 |int4 |int4 |* |int4mul
int4 |int4 |int4 |+ |int4pl
int4 |int4 |int4 |- |int4mi
int4 |int4 |int4 |/ |int4div
int4 |point |point |<===> |pointdist
tinterval|abstime |abstime |<#> |mktinterval
.fi
.SH "LEFT UNARY OPERATORS"
The table below gives the left unary operators that are
registered in the system catalogs.
This list was generated from the Postgres system catalogs with the query:
.nf
SELECT o.oprname AS left_unary,
right.typname AS operand,
result.typname AS return_type
FROM pg_operator o, pg_type right, pg_type result
WHERE o.oprkind = 'l' AND -- left unary
o.oprright = right.oid AND
o.oprresult = result.oid
ORDER BY operand;
left_unary|operand |return_type
----------+---------+-----------
@@ |box |point
@ |float4 |float4
- |float4 |float4
; |float8 |float8
: |float8 |float8
% |float8 |float8
\|\|/ |float8 |float8
\|/ |float8 |float8
@ |float8 |float8
- |float8 |float8
- |int2 |int2
- |int4 |int4
!! |int4 |int4
\| |tinterval|abstime
.fi
.in
.SH "RIGHT UNARY OPERATORS"
The table below gives the right unary operators that are
registered in the system catalogs.
This list was generated from the Postgres system catalogs with the query:
.nf
SELECT o.oprname AS right_unary,
left.typname AS operand,
result.typname AS return_type
FROM pg_operator o, pg_type left, pg_type result
WHERE o.oprkind = 'r' AND -- right unary
o.oprleft = left.oid AND
o.oprresult = result.oid
ORDER BY operand;
right_unary|operand|return_type
-----------+-------+-----------
% |float8 |float8
! |int4 |int4
.fi
.in
.SH "AGGREGATE FUNCTIONS"
The table below gives the aggregate functions that are
registered in the system catalogs.
This list was generated from the Postgres system catalogs with the query:
.nf
SELECT a.aggname, t.typname
FROM pg_aggregate a, pg_type t
WHERE a.aggbasetype = t.oid
ORDER BY aggname, typname;
aggname|typname
-------+-------
avg |float4
avg |float8
avg |int2
avg |int4
max |float4
max |float8
max |int2
max |int4
min |float4
min |float8
min |int2
min |int4
sum |float4
sum |float8
sum |int2
sum |int4
\fBcount\fR is also available.
.fi
.in
.SH "SEE ALSO"
For examples on specifying literals of built-in types, see
.IR SQL(l).
.SH BUGS
.PP
Although most of the input and output functions correponding to the
base types (e.g., integers and floating point numbers) do some
error-checking, none of them are particularly rigorous about it. More
importantly, almost none of the operators and functions (e.g.,
addition and multiplication) perform any error-checking at all.
Consequently, many of the numeric operations will (for example)
silently underflow or overflow.
.PP
Some of the input and output functions are not invertible. That is,
the result of an output function may lose precision when compared to
the original input.

446
doc/man/catalogs.3 Normal file
View File

@ -0,0 +1,446 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/catalogs.3,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH "SYSTEM CATALOGS" INTRO 03/13/94 Postgres95 Postgres95
.SH "Section 7 \(em System Catalogs"
.de LS
.PP
.if n .ta 5 +13 +13
.if t .ta 0.5i +1.3i +1.3i
.in 0
.nf
..
.de LE
.fi
.in
..
.SH "DESCRIPTION"
In this
section we list each of the attributes of the system catalogs and
define their meanings.
.SH "CLASS/TYPE SYSTEM CATALOGS"
These catalogs form the core of the extensibility system:
.LS
\fBname\fP \fBshared/local\fP \fBdescription\fP
pg_aggregate local aggregate functions
pg_am local access methods
pg_amop local operators usable with specific access methods
pg_amproc local procedures used with specific access methods
pg_attribute local class attributes
pg_class local classes
pg_index local secondary indices
pg_inherits local class inheritance hierarchy
pg_language local procedure implementation languages
pg_opclass local operator classes
pg_operator local query language operators
pg_proc local procedures (functions)
pg_type local data types
.LE
.SH "ENTITIES"
These catalogs deal with identification of entities known throughout
the site:
.LS
\fBname\fP \fBshared/local\fP \fBdescription\fP
pg_database shared current databases
pg_group shared user groups
pg_user shared valid users
.LE
.SH "RULE SYSTEM CATALOGS"
.LS
\fBname\fP \fBshared/local\fP \fBdescription\fP
pg_listener local processes waiting on alerters
pg_prs2plans local instance system procedures
pg_prs2rule local instance system rules
pg_prs2stub local instance system ``stubs''
pg_rewrite local rewrite system information
.LE
.SH "LARGE OBJECT CATALOGS"
.PP
These catalogs are specific to the Inversion file system and large
objects in general:
.LS
\fBname\fP \fBshared/local\fP \fBdescription\fP
pg_lobj local description of a large object
pg_naming local Inversion name space mapping
pg_platter local jukebox platter inventory
pg_plmap local jukebox platter extent map
.LE
.SH "INTERNAL CATALOGS"
.PP
These catalogs are internal classes that are not stored as normal
heaps and cannot be accessed through normal means (attempting to do so
causes an error).
.LS
\fBname\fP \fBshared/local\fP \fBdescription\fP
pg_log shared transaction commit/abort log
pg_magic shared magic constant
pg_time shared commit/abort times
pg_variable shared special variable values
.LE
.PP
There are several other classes defined with \*(lqpg_\*(rq names.
Aside from those that end in \*(lqind\*(rq (secondary indices), these
are all obsolete or otherwise deprecated.
.SH "CLASS/TYPE SYSTEM CATALOGS"
.PP
The following catalogs relate to the class/type system.
.nf M
/*
* aggregates
*
* see DEFINE AGGREGATE for an explanation of transition functions
*/
pg_aggregate
NameData aggname /* aggregate name (e.g., "count") */
oid aggowner /* usesysid of creator */
regproc aggtransfn1 /* first transition function */
regproc aggtransfn2 /* second transition function */
regproc aggfinalfn /* final function */
oid aggbasetype /* type of data on which aggregate
operates */
oid aggtranstype1 /* type returned by aggtransfn1 */
oid aggtranstype2 /* type returned by aggtransfn2 */
oid aggfinaltype /* type returned by aggfinalfn */
text agginitval1 /* external format of initial
(starting) value of aggtransfn1 */
text agginitval2 /* external format of initial
(starting) value of aggtransfn2 */
.fi
.nf M
pg_am
NameData amname /* access method name */
oid amowner /* usesysid of creator */
char amkind /* - deprecated */
/* originally:
h=hashed
o=ordered
s=special */
int2 amstrategies /* total NUMBER of strategies by which
we can traverse/search this AM */
int2 amsupport /* total NUMBER of support functions
that this AM uses */
regproc amgettuple /* "next valid tuple" function */
regproc aminsert /* "insert this tuple" function */
regproc amdelete /* "delete this tuple" function */
regproc amgetattr /* - deprecated */
regproc amsetlock /* - deprecated */
regproc amsettid /* - deprecated */
regproc amfreetuple /* - deprecated */
regproc ambeginscan /* "start new scan" function */
regproc amrescan /* "restart this scan" function */
regproc amendscan /* "end this scan" function */
regproc ammarkpos /* "mark current scan position"
function */
regproc amrestrpos /* "restore marked scan position"
function */
regproc amopen /* - deprecated */
regproc amclose /* - deprecated */
regproc ambuild /* "build new index" function */
regproc amcreate /* - deprecated */
regproc amdestroy /* - deprecated */
.fi
.nf M
pg_amop
oid amopid /* access method with which this
operator be used */
oid amopclaid /* operator class with which this
operator can be used */
oid amopopr /* the operator */
int2 amopstrategy /* traversal/search strategy number
to which this operator applies */
regproc amopselect /* function to calculate the operator
selectivity */
regproc amopnpages /* function to calculate the number of
pages that will be examined */
.fi
.nf M
pg_amproc
oid amid /* access method with which this
procedure is associated */
oid amopclaid /* operator class with which this
operator can be used */
oid amproc /* the procedure */
int2 amprocnum /* support function number to which
this operator applies */
.fi
.nf M
pg_class
NameData relname /* class name */
oid relowner /* usesysid of owner */
oid relam /* access method */
int4 relpages /* # of 8KB pages */
int4 reltuples /* # of instances */
abstime relexpires /* time after which instances are
deleted from non-archival storage */
reltime relpreserved /* timespan after which instances are
deleted from non-archival storage */
bool relhasindex /* does the class have a secondary
index? */
bool relisshared /* is the class shared or local? */
char relkind /* type of relation:
i=index
r=relation (heap)
s=special
u=uncatalogued (temporary) */
char relarch /* archive mode:
h=heavy
l=light
n=none */
int2 relnatts /* current # of non-system
attributes */
int2 relsmgr /* storage manager:
0=magnetic disk
1=sony WORM jukebox
2=main memory */
int28 relkey /* - unused */
oid8 relkeyop /* - unused */
aclitem relacl[1] /* access control lists */
.fi
.nf M
pg_attribute
oid attrelid /* class containing this attribute */
NameData attname /* attribute name */
oid atttypid /* attribute type */
oid attdefrel /* - deprecated */
int4 attnvals /* - deprecated */
oid atttyparg /* - deprecated */
int2 attlen /* attribute length, in bytes
-1=variable */
int2 attnum /* attribute number
>0=user attribute
<0=system attribute */
int2 attbound /* - deprecated */
bool attbyval /* type passed by value? */
bool attcanindex /* - deprecated */
oid attproc /* - deprecated */
int4 attnelems /* # of array dimensions */
int4 attcacheoff /* cached offset into tuple */
bool attisset /* is attribute set-valued? */
.fi
.nf M
pg_inherits
oid inhrel /* child class */
oid inhparent /* parent class */
int4 inhseqno /* - deprecated */
.fi
.nf M
oid indexrelid /* oid of secondary index class */
oid indrelid /* oid of indexed heap class */
oid indproc /* function to compute index key from
attribute(s) in heap
0=not a functional index */
int28 indkey /* attribute numbers of key
attribute(s) */
oid8 indclass /* opclass of each key */
bool indisclustered /* is the index clustered?
- unused */
bool indisarchived /* is the index archival?
- unused */
text indpred /* query plan for partial index
predicate */
.fi
.nf M
pg_type
NameData typname /* type name */
oid typowner /* usesysid of owner */
int2 typlen /* length in internal form
-1=variable-length */
int2 typprtlen /* length in external form */
bool typbyval /* type passed by value? */
char typtype /* kind of type:
c=catalog (composite)
b=base */
bool typisdefined /* defined or still a shell? */
char typdelim /* delimiter for array external form */
oid typrelid /* class (if composite) */
oid typelem /* type of each array element */
regproc typinput /* external-internal conversion
function */
regproc typoutput /* internal-external conversion
function */
regproc typreceive /* client-server conversion function */
regproc typsend /* server-client conversion function */
text typdefault /* default value */
.fi
.nf M
pg_operator
NameData oprname /* operator name */
oid oprowner /* usesysid of owner */
int2 oprprec /* - deprecated */
char oprkind /* kind of operator:
b=binary
l=left unary
r=right unary */
bool oprisleft /* is operator left/right associative? */
bool oprcanhash /* is operator usable for hashjoin? */
oid oprleft /* left operand type */
oid oprright /* right operand type */
oid oprresult /* result type */
oid oprcom /* commutator operator */
oid oprnegate /* negator operator */
oid oprlsortop /* sort operator for left operand */
oid oprrsortop /* sort operator for right operand */
regproc oprcode /* function implementing this operator */
regproc oprrest /* function to calculate operator
restriction selectivity */
regproc oprjoin /* function to calculate operator
join selectivity */
.fi
.nf M
pg_opclass
NameData opcname /* operator class name */
.fi
.nf M
pg_proc
NameData proname /* function name */
oid proowner /* usesysid of owner */
oid prolang /* function implementation language */
bool proisinh /* - deprecated */
bool proistrusted /* run in server or untrusted function
process? */
bool proiscachable /* can the function return values be
cached? */
int2 pronargs /* # of arguments */
bool proretset /* does the function return a set?
- unused */
oid prorettype /* return type */
oid8 proargtypes /* argument types */
int4 probyte_pct /* % of argument size (in bytes) that
needs to be examined in order to
compute the function */
int4 properbyte_cpu /* sensitivity of the function's
running time to the size of its
inputs */
int4 propercall_cpu /* overhead of the function's
invocation (regardless of input
size) */
int4 prooutin_ratio /* size of the function's output as a
percentage of the size of the input */
text prosrc /* function definition (postquel only) */
bytea probin /* path to object file (C only) */
.fi
.nf M
pg_language
NameData lanname /* language name */
text lancompiler /* - deprecated */
.fi
.SH "ENTITIES"
.nf M
pg_database
NameData datname /* database name */
oid datdba /* usesysid of database administrator */
text datpath /* directory of database under
$PGDATA */
.fi
.nf M
pg_group
NameData groname /* group name */
int2 grosysid /* group's UNIX group id */
int2 grolist[1] /* list of usesysids of group members */
.fi
.nf M
pg_user
NameData usename /* user's name */
int2 usesysid /* user's UNIX user id */
bool usecreatedb /* can user create databases? */
bool usetrace /* can user set trace flags? */
bool usesuper /* can user be POSTGRES superuser? */
bool usecatupd /* can user update catalogs? */
.fi
.SH "RULE SYSTEM CATALOGS"
.nf M
pg_listener
NameData relname /* class for which asynchronous
notification is desired */
int4 listenerpid /* process id of server corresponding
to a frontend program waiting for
asynchronous notification */
int4 notification /* whether an event notification for
this process id still pending */
.fi
.nf M
pg_prs2rule
NameData prs2name /* rule name */
char prs2eventtype /* rule event type:
R=retrieve
U=update (replace)
A=append
D=delete */
oid prs2eventrel /* class to which event applies */
int2 prs2eventattr /* attribute to which event applies */
float8 necessary /* - deprecated */
float8 sufficient /* - deprecated */
text prs2text /* text of original rule definition */
.fi
.nf M
pg_prs2plans
oid prs2ruleid /* prs2rule instance for which this
plan is used */
int2 prs2planno /* plan number (one rule may invoke
multiple plans) */
text prs2code /* external representation of the plan */
.fi
.nf M
pg_prs2stub
oid prs2relid /* class to which this rule applies */
bool prs2islast /* is this the last stub fragment? */
int4 prs2no /* stub fragment number */
stub prs2stub /* stub fragment */
.fi
.nf M
pg_rewrite
NameData rulename /* rule name */
char ev_type /* event type:
RETRIEVE, REPLACE, APPEND, DELETE
codes are parser-dependent (!?) */
oid ev_class /* class to which this rule applies */
int2 ev_attr /* attribute to which this rule applies */
bool is_instead /* is this an "instead" rule? */
text ev_qual /* qualification with which to modify
(rewrite) the plan that triggered this
rule */
text action /* parse tree of action */
.fi
.SH "LARGE OBJECT CATALOGS"
.nf M
pg_lobj
oid ourid /* 'ourid' from pg_naming that
identifies this object in the
Inversion file system namespace */
int4 objtype /* storage type code:
0=Inversion
1=Unix
2=External
3=Jaquith */
bytea object_descripto/* opaque object-handle structure */
.fi
.nf M
pg_naming
NameData filename /* filename component */
oid ourid /* random oid used to identify this
instance in other instances (can't
use the actual oid for obscure
reasons */
oid parentid /* pg_naming instance of parent
Inversion file system directory */
.fi
.nf M
pg_platter
NameData plname /* platter name */
int4 plstart /* the highest OCCUPIED extent */
.fi
.nf M
pg_plmap
oid plid /* platter (in pg_platter) on which
this extent (of blocks) resides */
oid pldbid /* database of the class to which this
extent (of blocks) belongs */
oid plrelid /* class to which this extend (of
blocks) belongs */
int4 plblkno /* starting block number within the
class */
int4 ploffset /* offset within the platter at which
this extent begins */
int4 plextentsz /* length of this extent */
.fi

23
doc/man/cleardbdir.1 Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/cleardbdir.1,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH CLEARDBDIR UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
cleardbdir \(em completely destroys all database files
.SH SYNOPSIS
.BR "cleardbdir"
.SH DESCRIPTION
.IR cleardbdir
destroys all the database files. It is used only by the
Postgres super-user
before re-initializing the entire installation for a particular site. Normal
database users should never use this command.
.PP
The
Postgres super-user
should ensure the
.IR postmaster
process is not running before running cleardbdir.
.SH "SEE ALSO"
initdb(1)

28
doc/man/close.l Normal file
View File

@ -0,0 +1,28 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/close.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH CLOSE SQL 11/05/95 Postgres95 Postgres95
.SH NAME
close \(em close a cursor
.SH SYNOPSIS
.nf
\fBclose\fP [cursor_name]
.fi
.SH DESCRIPTION
.BR Close
frees the resources associated with a cursor,
.IR cursor_name.
After this cursor is closed, no subsequent operations are allowed on
it. A cursor should be closed when it is no longer needed. If
.IR cursor_name.
is not specified, then the blank cursor is closed.
.SH EXAMPLE
.nf
/*
* close the cursor FOO
*/
close FOO
.fi
.SH "SEE ALSO"
fetch(l),
select(l).

33
doc/man/cluster.l Normal file
View File

@ -0,0 +1,33 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/cluster.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH CLUSTER SQL 01/23/93 Postgres95 Postgres95
.SH NAME
cluster \(em give storage clustering advice to Postgres
.SH SYNOPSIS
.nf
\fBcluster\fR indexname \fBon\fR attname
.fi
.SH DESCRIPTION
This command instructs Postgres to cluster the class specified by
.IR classname
approximately based on the index specified by
.IR indexname.
The index must already have been defined on
.IR classname.
.PP
When a class is clustered, it is physically reordered based on the index
information. The clustering is static. In other words, if the class is
updated, it may become unclustered. No attempt is made to keep new
instances or updated tuples clustered. If desired, the user can
recluster manually by issuing the command again.
.SH EXAMPLE
.nf
/*
* cluster employees in based on its salary attribute
*/
create index emp_ind on emp using btree (salary int4_ops);
cluster emp_ind on emp
.fi

23
doc/man/commit.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/commit.l,v 1.1.1.1 1996/08/18 22:14:20 scrappy Exp $
.TH COMMIT SQL 01/23/93 Postgres95 Postgres95
.SH NAME
commit \(em commit the current transaction
.SH SYNOPSIS
.nf
\fBcommit [transaction|work]\fR
.fi
.SH DESCRIPTION
This commands commits the current transaction. All changes made by
the transaction become visible to others and are guaranteed to be
durable if a crash occurs.
.IR "commit"
is functionally equivalent to the
.IR "end"
command
.SH "SEE ALSO"
abort(l),
begin(l),
end(l),
rollback(l).

162
doc/man/copy.l Normal file
View File

@ -0,0 +1,162 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/copy.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH COPY SQL 11/05/95 Postgres95 Postgres95
.SH NAME
copy \(em copy data to or from a class from or to a Unix file.
.SH SYNOPSIS
.nf
\fBcopy\fP [\fBbinary\fP] [\fBnonulls\fP] classname
\fBto\fP|\fBfrom\fP "filename"|\fBstdin\fR|\fBstdout\fR
[\fBUSING DELIMITERS\fP delim]
.fi
.SH DESCRIPTION
.BR Copy
moves data between Postgres classes and standard Unix files. The
keyword
.BR binary
changes the behavior of field formatting, as described below.
.IR Classname
is the name of an existing class.
.IR Filename
is the Unix pathname of the file. In place of a filename, the
keywords
.BR "stdin" " and " "stdout"
can be used so that input to
.BR copy
can be written by a Libpq application and output from the
.BR copy
command can be read by a Libpq application. The
.BR binary
keyword will force all data to be stored/read as binary objects rather
than as ASCII text. It is somewhat faster than the normal
.BR copy
command, but is not generally portable, and the files generated are
somewhat larger, although this factor is highly dependent on the data
itself.
.PP
By default,
.BR copy
uses a tab (\\t) character as a delimiter. The delimiter may also be changed
to any other single-character with the use of
.BR "USING DELIMITERS" .
Characters in data fields which happen to match the delimiter character
will be quoted.
.PP
You must have read access on any class whose values are read by the
.BR copy
command, and either write or append access to a class to which values
are being appended by the
.BR copy
command.
.SH FORMAT OF OUTPUT FILES
.SS "ASCII COPY FORMAT"
When
.BR copy
is used without the
.BR binary
keyword, the file generated will have each instance on a line, with
each attribute separated by the delimiter character. Embedded delimiter
characters will be preceeded by a backslash character (\\). The
attribute values themselves are strings generated by the output function
associated with each attribute type. The output function for a type
should not try to generate the backslash character; this will be handled
by
.BR copy
itself.
.PP
The actual format for each instance is
.nf
<attr1><tab><attr2><tab>...<tab><attrn><newline>
.fi
.PP
If
.BR copy
is sending its output to standard output instead of a file, it will
send a backslash(\\) and a period (.) followed immediately by a newline,
on a line by themselves, when it is done. Similarly, if
.BR copy
is reading from standard input, it will expect a backslash (\\) and
a period (.) followed
by a newline, as the first three characters on a line, to denote
end-of-file. However,
.BR copy
will terminate (followed by the backend itself) if a true EOF is
encountered.
.PP
The backslash character has special meaning.
.BR NULL
attributes are output as \\N.
A literal backslash character is output as two consecutive backslashes.
A literal tab character is represented as a backslash and a tab.
A literal newline character is represented as a backslash and a newline.
When loading ASCII data not generated by Postgres95, you will need to
convert backslash characters (\\) to double-backslashes (\\\\) so
they are loaded properly.
.SS "BINARY COPY FORMAT"
In the case of
.BR "copy binary" ,
the first four bytes in the file will be the number of instances in
the file. If this number is
.IR zero,
the
.BR "copy binary"
command will read until end of file is encountered. Otherwise, it
will stop reading when this number of instances has been read.
Remaining data in the file will be ignored.
.PP
The format for each instance in the file is as follows. Note that
this format must be followed
.BR EXACTLY .
Unsigned four-byte integer quantities are called uint32 in the below
description.
.nf
uint32 totallength (not including itself),
uint32 number of null attributes
[uint32 attribute number of first null attribute
...
uint32 attribute number of nth null attribute],
<data>
.fi
.bp
.SS "ALIGNMENT OF BINARY DATA"
On Sun-3s, 2-byte attributes are aligned on two-byte boundaries, and
all larger attributes are aligned on four-byte boundaries. Character
attributes are aligned on single-byte boundaries. On other machines,
all attributes larger than 1 byte are aligned on four-byte boundaries.
Note that variable length attributes are preceded by the attribute's
length; arrays are simply contiguous streams of the array element
type.
.SH "SEE ALSO"
insert(l), create table(l), vacuum(l), libpq.
.SH BUGS
Files used as arguments to the
.BR copy
command must reside on or be accessible to the the database server
machine by being either on local disks or a networked file system.
.PP
.BR Copy
stops operation at the first error. This should not lead to problems
in the event of a
.BR "copy from" ,
but the target relation will, of course, be partially modified in a
.BR "copy to" .
The
.IR vacuum (l)
query should be used to clean up after a failed
.BR "copy" .
.PP
Because Postgres operates out of a different directory than the user's
working directory at the time Postgres is invoked, the result of copying
to a file \*(lqfoo\*(rq (without additional path information) may
yield unexpected results for the naive user. In this case,
\*(lqfoo\*(rq will wind up in
.SM $PGDATA\c
/foo. In general, the full pathname should be used when specifying
files to be copied.
.PP
.BR Copy
has virtually no error checking, and a malformed input file will
likely cause the backend to crash. You should avoid using
.BR copy
for input whenever possible.

94
doc/man/create_aggregate.l Normal file
View File

@ -0,0 +1,94 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_aggregate.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH "CREATE AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create aggregate \(em define a new aggregate
.SH SYNOPSIS
.nf
\fBcreate aggregate\fR agg-name [\fBas\fR]
\fB(\fP[\fBsfunc1\fR \fB=\fR state-transition-function-1
,\fP \fBbasetype\fR \fB=\fR data-type
,\fP \fBstype1\fR \fB=\fR sfunc1-return-type]
[\fB,\fP \fBsfunc2\fR \fB=\fR state-transition-function-2
,\fP \fBstype2\fR \fB=\fR sfunc2-return-type]
[\fB,\fP \fBfinalfunc\fR \fB=\fR final-function]
[\fB,\fP \fBinitcond1\fR \fB=\fR initial-condition-1]
[\fB,\fP \fBinitcond2\fR \fB=\fR initial-condition-2]\fB)\fR
.fi
.SH DESCRIPTION
An aggregate function can use up to three functions, two
.IR "state transition"
functions, X1 and X2:
.nf
X1( internal-state1, next-data_item ) ---> next-internal-state1
X2( internal-state2 ) ---> next-internal-state2
.fi
and a
.BR "final calculation"
function, F:
.nf
F(internal-state1, internal-state2) ---> aggregate-value
.fi
These functions are required to have the following properties:
.IP
The arguments to state-transition-function-1 must be
.BR ( stype1 , basetype ) ,
and its return value must be stype1.
.IP
The argument and return value of state-transition-function-2 must be
.BR stype2 .
.IP
The arguments to the final-calculation-function must be
.BR ( stype1 , stype2 ) ,
and its return value must be a POSTGRES base type (not
necessarily the same as basetype.
.IP
The final-calculation-function should be specified if and only if both
state-transition functions are specified.
.PP
Note that it is possible to specify aggregate functions that have
varying combinations of state and final functions. For example, the
\*(lqcount\*(rq aggregate requires
.BR sfunc2
(an incrementing function) but not
.BR sfunc1 " or " finalfunc ,
whereas the \*(lqsum\*(rq aggregate requires
.BR sfunc1
(an addition function) but not
.BR sfunc2 " or " finalfunc
and the \*(lqaverage\*(rq aggregate requires both of the above state
functions as well as a
.BR finalfunc
(a division function) to produce its answer. In any case, at least
one state function must be defined, and any
.BR sfunc2
must have a corresponding
.BR initcond2 .
.PP
Aggregates also require two initial conditions, one for each
transition function. These are specified and stored in the database
as fields of type
.IR text .
.SH EXAMPLE
This
.IR avg
aggregate consists of two state transition functions, a addition
function and a incrementing function. These modify the internal state
of the aggregate through a running sum and and the number of values
seen so far. It accepts a new employee salary, increments the count,
and adds the new salary to produce the next state. The state
transition functions must be passed correct initialization values.
The final calculation then divides the sum by the count to produce the
final answer.
.nf
--
--Create an aggregate for int4 average
--
create aggregate avg (sfunc1 = int4add, basetype = int4,
stype1 = int4, sfunc2 = int4inc, stype2 = int4,
finalfunc = int4div, initcond1 = "0", initcond2 = "0")
.fi
.SH "SEE ALSO"
create function(l),
remove aggregate(l).

417
doc/man/create_function.l Normal file
View File

@ -0,0 +1,417 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_function.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH "CREATE FUNCTION" SQL 11/05/95 Postgres95 Postgres95
.SH "NAME"
create function \(em define a new function
.SH "SYNOPSIS"
.nf
\fBcreate function\fP function_name \fB(\fP
([type1 {, type-n}])
\fBreturns\fP type-r
\fBas\fP {'/full/path/to/objectfile' | 'sql-queries'}
\fBlanguage\fP {'c' \ 'sql' \ 'internal'}
.fi
.SH "DESCRIPTION"
With this command, a Postgres user can register a function with Postgres.
Subsequently, this user is treated as the owner of the function.
.PP
When defining a function with arguments, the input data types,
.IR type-1 ,
.IR type-2 ,
\&...,
.IR type-n ,
and the return data type,
.IR type-r
must be specified, along with the language, which may be
.IR "\*(lqc\*(rq"
or
.IR "\*(lqsql\*(rq" .
or
.IR "\*(lqinternal\*(rq" .
(The
.IR "arg is"
clause may be left out if the function has no arguments, or
alternatively the argument list may be left empty.)
The input types may be base or complex types, or
.IR opaque .
.IR Opaque
indicates that the function accepts arguments of an
invalid type such as (char *).
The output type may be specified as a base type, complex type,
.IR "setof <type>",
or
.IR opaque .
The
.IR setof
modifier indicates that the function will return a set of items,
rather than a single item.
The
.IR as
clause of the command is treated differently for C and SQL
functions, as explained below.
.SH "C FUNCTIONS"
Functions written in C can be defined to Postgres, which will dynamically
load them into its address space. The loading happens either using
.IR load (l)
or automatically the first time the function is necessary for
execution. Repeated execution of a function will cause negligible
additional overhead, as the function will remain in a main memory
cache.
.PP
Internal functions are functions written in C which have been statically
linked into the postgres backend process. The
.BR as
clause must still be specified when defining an internal function but
the contents are ignored.
.SH "Writing C Functions"
The body of a C function following
.BR as
should be the
.BR "FULL PATH"
of the object code (.o file) for the function, bracketed by quotation
marks. (Postgres will not compile a function automatically \(em it must
be compiled before it is used in a
.BR "define function"
command.)
.PP
C functions with base type arguments can be written in a
straightforward fashion. The C equivalents of built-in Postgres types
are accessible in a C file if
.nf
\&.../src/backend/utils/builtins.h
.fi
is included as a header file. This can be achieved by having
.nf
\&#include <utils/builtins.h>
.fi
at the top of the C source file and by compiling all C files with the
following include options:
.nf
-I.../src/backend
-I.../src/backend/port/<portname>
-I.../src/backend/obj
.fi
before any \*(lq.c\*(rq programs in the
.IR cc
command line, e.g.:
.nf
cc -I.../src/backend \e
-I.../src/backend/port/<portname> \e
-I.../src/backend/obj \e
-c progname.c
.fi
where \*(lq...\*(rq is the path to the installed Postgres source tree and
\*(lq<portname>\*(rq is the name of the port for which the source tree
has been built.
.PP
The convention for passing arguments to and from the user's C
functions is to use pass-by-value for data types that are 32 bits (4
bytes) or smaller, and pass-by-reference for data types that require
more than 32 bits.
.if t \{
The following table gives the C type required for parameters in the C
functions that will be loaded into Postgres. The \*(lqDefined In\*(rq
column gives the actual header file (in the
.nf
\&.../src/backend
.fi
directory) that the equivalent C type is defined. However, if you
include \*(lqutils/builtins.h\*(rq, these files will automatically be
included.
.SH "Equivalent C Types for Built-In Postgres Types"
.PP
.TS
center;
l l l
l l l.
\fBBuilt-In Type\fP \fBC Type\fP \fBDefined In\fP
_
abstime AbsoluteTime utils/nabstime.h
bool bool include/c.h
box (BOX *) utils/geo-decls.h
bytea (bytea *) include/postgres.h
char char N/A
char16 Char16 or (char16 *) include/postgres.h
cid CID include/postgres.h
int2 int2 include/postgres.h
int28 (int28 *) include/postgres.h
int4 int4 include/postgres.h
float4 float32 or (float4 *) include/c.h or include/postgres.h
float8 float64 or (float8 *) include/c.h or include/postgres.h
lseg (LSEG *) include/geo-decls.h
name (Name) include/postgres.h
oid oid include/postgres.h
oid8 (oid8 *) include/postgres.h
path (PATH *) utils/geo-decls.h
point (POINT *) utils/geo-decls.h
regproc regproc or REGPROC include/postgres.h
reltime RelativeTime utils/nabstime.h
text (text *) include/postgres.h
tid ItemPointer storage/itemptr.h
tinterval TimeInterval utils/nabstime.h
uint2 uint16 include/c.h
uint4 uint32 include/c.h
xid (XID *) include/postgres.h
.TE
\}
.PP
Complex arguments to C functions are passed into the C function as a
special C type, TUPLE, defined in
.nf
\&.../src/libpq/libpq-fe.h.
.fi
Given a variable
.IR t
of this type, the C function may extract attributes from the function
using the function call:
.nf
GetAttributeByName(t, "fieldname", &isnull)
.fi
where
.IR isnull
is a pointer to a
.IR bool ,
which the function sets to
.IR true
if the field is null. The result of this function should be cast
appropriately as shown in the examples below.
.SH "Compiling Dynamically-Loaded C Functions"
.PP
Different operating systems require different procedures for compiling
C source files so that Postgres can load them dynamically. This section
discusses the required compiler and loader options on each system.
.PP
Under Linux ELF, object files can be generated by specifing the compiler
flag -fpic.
.PP
Under Ultrix, all object files that Postgres is expected to load
dynamically must be compiled using
.IR /bin/cc
with the \*(lq-G 0\*(rq option turned on. The object file name in the
.IR as
clause should end in \*(lq.o\*(rq.
.PP
Under HP-UX, DEC OSF/1, AIX and SunOS 4, all object files must be
turned into
.IR "shared libraries"
using the operating system's native object file loader,
.IR ld (1).
.PP
Under HP-UX, an object file must be compiled using the native HP-UX C
compiler,
.IR /bin/cc ,
with both the \*(lq+z\*(rq and \*(lq+u\*(rq flags turned on. The
first flag turns the object file into \*(lqposition-independent
code\*(rq (PIC); the second flag removes some alignment restrictions
that the PA-RISC architecture normally enforces. The object file must
then be turned into a shared library using the HP-UX loader,
.IR /bin/ld .
The command lines to compile a C source file, \*(lqfoo.c\*(rq, look
like:
.nf
cc <other flags> +z +u -c foo.c
ld <other flags> -b -o foo.sl foo.o
.fi
The object file name in the
.BR as
clause should end in \*(lq.sl\*(rq.
.PP
An extra step is required under versions of HP-UX prior to 9.00. If
the Postgres header file
.nf
include/c.h
.fi
is not included in the source file, then the following line must also
be added at the top of every source file:
.nf
#pragma HP_ALIGN HPUX_NATURAL_S500
.fi
However, this line must not appear in programs compiled under HP-UX
9.00 or later.
.PP
Under DEC OSF/1, an object file must be compiled and then turned
into a shared library using the OSF/1 loader,
.IR /bin/ld .
In this case, the command lines look like:
.nf
cc <other flags> -c foo.c
ld <other flags> -shared -expect_unresolved '*' -o foo.so foo.o
.fi
The object file name in the
.BR as
clause should end in \*(lq.so\*(rq.
.PP
Under SunOS 4, an object file must be compiled and then turned into a
shared library using the SunOS 4 loader,
.IR /bin/ld .
The command lines look like:
.nf
cc <other flags> -PIC -c foo.c
ld <other flags> -dc -dp -Bdynamic -o foo.so foo.o
.fi
The object file name in the
.BR as
clause should end in \*(lq.so\*(rq.
.PP
Under AIX, object files are compiled normally but building the shared
library requires a couple of steps. First, create the object file:
.nf
cc <other flags> -c foo.c
.fi
You must then create a symbol \*(lqexports\*(rq file for the object
file:
.nf
mkldexport foo.o `pwd` > foo.exp
.fi
Finally, you can create the shared library:
.nf
ld <other flags> -H512 -T512 -o foo.so -e _nostart \e
-bI:.../lib/postgres.exp -bE:foo.exp foo.o \e
-lm -lc 2>/dev/null
.fi
You should look at the Postgres User's Manual for an explanation of this
procedure.
.SH "SQL FUNCTIONS"
SQL functions execute an arbitrary list of SQL queries, returning
the results of the last query in the list. SQL functions in general
return sets. If their returntype is not specified as a
.IR setof ,
then an arbitrary element of the last query's result will be returned.
.PP
The body of a SQL function following
.BR as
should be a list of queries separated by whitespace characters and
bracketed within quotation marks. Note that quotation marks used in
the queries must be escaped, by preceding them with two backslashes
(i.e. \e\e").
.PP
Arguments to the SQL function may be referenced in the queries using
a $n syntax: $1 refers to the first argument, $2 to the second, and so
on. If an argument is complex, then a \*(lqdot\*(rq notation may be
used to access attributes of the argument (e.g. \*(lq$1.emp\*(rq), or
to invoke functions via a nested-dot syntax.
.SH "EXAMPLES: C Functions"
The following command defines a C function, overpaid, of two basetype
arguments.
.nf
create function overpaid (float8, int4) returns bool
as '/usr/postgres/src/adt/overpaid.o'
language 'c'
.fi
The C file "overpaid.c" might look something like:
.nf
#include <utils/builtins.h>
bool overpaid(salary, age)
float8 *salary;
int4 age;
{
if (*salary > 200000.00)
return(TRUE);
if ((age < 30) & (*salary > 100000.00))
return(TRUE);
return(FALSE);
}
.fi
The overpaid function can be used in a query, e.g:
.nf
select name from EMP where overpaid(salary, age)
.fi
One can also write this as a function of a single argument of type
EMP:
.nf
create function overpaid_2 (EMP)
returns bool
as '/usr/postgres/src/adt/overpaid_2.o'
language 'c'
.fi
The following query is now accepted:
.nf
select name from EMP where overpaid_2(EMP)
.fi
In this case, in the body of the overpaid_2 function, the fields in the EMP
record must be extracted. The C file "overpaid_2.c" might look
something like:
.nf
#include <utils/builtins.h>
#include <libpq-fe.h>
bool overpaid_2(t)
TUPLE t;
{
float8 *salary;
int4 age;
bool salnull, agenull;
salary = (float8 *)GetAttributeByName(t, "salary",
&salnull);
age = (int4)GetAttributeByName(t, "age", &agenull);
if (!salnull && *salary > 200000.00)
return(TRUE);
if (!agenull && (age<30) && (*salary > 100000.00))
return(TRUE);
return(FALSE)
}
.fi
.SH "EXAMPLES: SQL Functions"
To illustrate a simple SQL function, consider the following,
which might be used to debit a bank account:
.nf
create function TP1 (int4, float8) returns int4
as 'update BANK set balance = BANK.balance - $2
where BANK.acctountno = $1
select(x = 1)'
language 'sql'
.fi
A user could execute this function to debit account 17 by $100.00 as
follows:
.nf
select (x = TP1( 17,100.0))
.fi
The following more interesting examples take a single argument of type
EMP, and retrieve multiple results:
.nf
select function hobbies (EMP) returns set of HOBBIES
as 'select (HOBBIES.all) from HOBBIES
where $1.name = HOBBIES.person'
language 'sql'
.SH "SEE ALSO"
.PP
information(1), load(l), drop function(l).
.SH "NOTES"
.SH "Name Space Conflicts"
More than one function may be defined with the same name, as long as
the arguments they take are different. In other words, function names
can be
.IR overloaded .
A function may also have the same name as an attribute. In the case
that there is an ambiguity between a function on a complex type and
an attribute of the complex type, the attribute will always be used.
.SH "RESTRICTIONS"
The name of the C function must be a legal C function name, and the
name of the function in C code must be exactly the same as the name
used in
.BR "create function" .
There is a subtle implication of this restriction: while the
dynamic loading routines in most operating systems are more than
happy to allow you to load any number of shared libraries that
contain conflicting (identically-named) function names, they may
in fact botch the load in interesting ways. For example, if you
define a dynamically-loaded function that happens to have the
same name as a function built into Postgres, the DEC OSF/1 dynamic
loader causes Postgres to call the function within itself rather than
allowing Postgres to call your function. Hence, if you want your
function to be used on different architectures, we recommend that
you do not overload C function names.
.PP
There is a clever trick to get around the problem just described.
Since there is no problem overloading SQL functions, you can
define a set of C functions with different names and then define
a set of identically-named SQL function wrappers that take the
appropriate argument types and call the matching C function.
.PP
.IR opaque
cannot be given as an argument to a SQL function.
.SH "BUGS"
C functions cannot return a set of values.

314
doc/man/create_index.l Normal file
View File

@ -0,0 +1,314 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_index.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH "CREATE INDEX" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create index \(em construct a secondary index
.SH SYNOPSIS
.nf
\fBcreate\fR \fBindex\fR index-name
\fBon\fR classname \fBusing\fR am-name
\fB(\fR attname type_class \fB)\fR
\fBcreate\fR \fBindex\fR index-name
\fBon\fR classname \fBusing\fR am-name
\fB(\fR funcname \fB(\fR attname\-1 { , attname\-i } \fB)\fR type_class \fB)\fR
.fi
.SH DESCRIPTION
This command constructs an index called
.IR index-name.
.PP
.IR Am-name
is the name of the access method which is used for the index.
.PP
In the first syntax shown above, the key field for the index is
specified as an attribute name and an associated
.IR "operator class" .
An operator class is used to specify the operators to be used for a
particular index. For example, a btree index on four-byte integers
would use the
.IR int4_ops
class; this operator class includes comparison functions for four-byte
integers.
.PP
In the second syntax shown above, an index can be defined on the
result of a user-defined function
.IR funcname
applied to one or more attributes of a single class. These
.IR "functional indices"
are primarily useful in two situations. First, functional indices can
be used to simulate multikey indices. That is, the user can define a
new base type (a simple combination of, say, \*(lqoid\*(rq and
\*(lqint2\*(rq) and the associated functions and operators on this new
type such that the access method can use it. Once this has been done,
the standard techniques for interfacing new types to access methods
(described in the Postgres user manual) can be applied. Second,
functional indices can be used to obtain fast access to data based on
operators that would normally require some transformation to be
applied to the base data. For example, say you have an attribute in
class \*(lqmyclass\*(rq called \*(lqpt\*(rq that consists of a 2D
point type. Now, suppose that you would like to index this attribute
but you only have index operator classes for 2D polygon types. You
can define an index on the point attribute using a function that you
write (call it \*(lqpoint_to_polygon\*(rq) and your existing polygon
operator class; after that, queries using existing polygon operators
that reference \*(lqpoint_to_polygon(myclass.pt)\*(rq on one side will
use the precomputed polygons stored in the functional index instead of
computing a polygon for each and every instance in \*(lqmyclass\*(rq
and then comparing it to the value on the other side of the operator.
Obviously, the decision to build a functional index represents a
tradeoff between space (for the index) and execution time.
.PP
Postgres provides btree, rtree and hash access methods for
secondary indices. The btree access method is an implementation of
the Lehman-Yao high-concurrency btrees. The rtree access method
implements standard rtrees using Guttman's quadratic split algorithm.
The hash access method is an implementation of Litwin's linear
hashing. We mention the algorithms used solely to indicate that all
of these access methods are fully dynamic and do not have to be
optimized periodically (as is the case with, for example, static hash
access methods).
.PP
This list was generated from the Postgres system catalogs with the query:
.nf
SELECT am.amname AS acc_name,
opc.opcname AS ops_name,
opr.oprname AS ops_comp
FROM pg_am am, pg_amop amop, pg_opclass opc, pg_operator opr
WHERE amop.amopid = am.oid AND
amop.amopclaid = opc.oid AND
amop.amopopr = opr.oid
ORDER BY acc_name, ops_name, ops_comp;
acc_name|ops_name |ops_comp
--------+-----------+--------
btree |abstime_ops|<
btree |abstime_ops|<=
btree |abstime_ops|=
btree |abstime_ops|>
btree |abstime_ops|>=
btree |bpchar_ops |<
btree |bpchar_ops |<=
btree |bpchar_ops |=
btree |bpchar_ops |>
btree |bpchar_ops |>=
btree |char16_ops |<
btree |char16_ops |<=
btree |char16_ops |=
btree |char16_ops |>
btree |char16_ops |>=
btree |char2_ops |<
btree |char2_ops |<=
btree |char2_ops |=
btree |char2_ops |>
btree |char2_ops |>=
btree |char4_ops |<
btree |char4_ops |<=
btree |char4_ops |=
btree |char4_ops |>
btree |char4_ops |>=
btree |char8_ops |<
btree |char8_ops |<=
btree |char8_ops |=
btree |char8_ops |>
btree |char8_ops |>=
btree |char_ops |<
btree |char_ops |<=
btree |char_ops |=
btree |char_ops |>
btree |char_ops |>=
btree |date_ops |<
btree |date_ops |<=
btree |date_ops |=
btree |date_ops |>
btree |date_ops |>=
btree |float4_ops |<
btree |float4_ops |<=
btree |float4_ops |=
btree |float4_ops |>
btree |float4_ops |>=
btree |float8_ops |<
btree |float8_ops |<=
btree |float8_ops |=
btree |float8_ops |>
btree |float8_ops |>=
btree |int24_ops |<
btree |int24_ops |<=
btree |int24_ops |=
btree |int24_ops |>
btree |int24_ops |>=
btree |int2_ops |<
btree |int2_ops |<=
btree |int2_ops |=
btree |int2_ops |>
btree |int2_ops |>=
btree |int42_ops |<
btree |int42_ops |<=
btree |int42_ops |=
btree |int42_ops |>
btree |int42_ops |>=
btree |int4_ops |<
btree |int4_ops |<=
btree |int4_ops |=
btree |int4_ops |>
btree |int4_ops |>=
btree |name_ops |<
btree |name_ops |<=
btree |name_ops |=
btree |name_ops |>
btree |name_ops |>=
btree |oid_ops |<
btree |oid_ops |<=
btree |oid_ops |=
btree |oid_ops |>
btree |oid_ops |>=
btree |oidint2_ops|<
btree |oidint2_ops|<=
btree |oidint2_ops|=
btree |oidint2_ops|>
btree |oidint2_ops|>=
btree |oidint4_ops|<
btree |oidint4_ops|<=
btree |oidint4_ops|=
btree |oidint4_ops|>
btree |oidint4_ops|>=
btree |oidname_ops|<
btree |oidname_ops|<=
btree |oidname_ops|=
btree |oidname_ops|>
btree |oidname_ops|>=
btree |text_ops |<
btree |text_ops |<=
btree |text_ops |=
btree |text_ops |>
btree |text_ops |>=
btree |time_ops |<
btree |time_ops |<=
btree |time_ops |=
btree |time_ops |>
btree |time_ops |>=
btree |varchar_ops|<
btree |varchar_ops|<=
btree |varchar_ops|=
btree |varchar_ops|>
btree |varchar_ops|>=
hash |bpchar_ops |=
hash |char16_ops |=
hash |char2_ops |=
hash |char4_ops |=
hash |char8_ops |=
hash |char_ops |=
hash |date_ops |=
hash |float4_ops |=
hash |float8_ops |=
hash |int2_ops |=
hash |int4_ops |=
hash |name_ops |=
hash |oid_ops |=
hash |text_ops |=
hash |time_ops |=
hash |varchar_ops|=
rtree |bigbox_ops |&&
rtree |bigbox_ops |&<
rtree |bigbox_ops |&>
rtree |bigbox_ops |<<
rtree |bigbox_ops |>>
rtree |bigbox_ops |@
rtree |bigbox_ops |~
rtree |bigbox_ops |~=
rtree |box_ops |&&
rtree |box_ops |&<
rtree |box_ops |&>
rtree |box_ops |<<
rtree |box_ops |>>
rtree |box_ops |@
rtree |box_ops |~
rtree |box_ops |~=
rtree |poly_ops |&&
rtree |poly_ops |&<
rtree |poly_ops |&>
rtree |poly_ops |<<
rtree |poly_ops |>>
rtree |poly_ops |@
rtree |poly_ops |~
rtree |poly_ops |~=
.fi
The
.IR int24_ops
operator class is useful for constructing indices on int2 data, and
doing comparisons against int4 data in query qualifications.
Similarly,
.IR int42_ops
support indices on int4 data that is to be compared against int2 data
in queries.
.PP
The operator classes
.IR oidint2_ops ,
.IR oidint4_ops ,
and
.IR oidchar16_ops
represent the use of
.IR "functional indices"
to simulate multi-key indices.
.PP
The Postgres query optimizer will consider using btree indices in a scan
whenever an indexed attribute is involved in a comparison using one of:
.nf
< <= = >= >
.fi
Both box classes support indices on the \*(lqbox\*(rq datatype in
Postgres. The difference between them is that
.IR bigbox_ops
scales box coordinates down, to avoid floating point exceptions from
doing multiplication, addition, and subtraction on very large
floating-point coordinates. If the field on which your rectangles lie
is about 20,000 units square or larger, you should use
.IR bigbox_ops .
The
.IR poly_ops
operator class supports rtree indices on \*(lqpolygon\*(rq data.
.PP
The Postgres query optimizer will consider using an rtree index whenever
an indexed attribute is involved in a comparison using one of:
.nf
<< &< &> >> @ ~= &&
.fi
The Postgres query optimizer will consider using a hash index whenever
an indexed attribute is involved in a comparison using the \fB=\fR operator.
.SH EXAMPLES
.nf
--
--Create a btree index on the emp class using the age attribute.
--
create index empindex on emp using btree (age int4_ops)
.fi
.nf
--
--Create a btree index on employee name.
--
create index empname
on emp using btree (name char16_ops)
.fi
.nf
--
--Create an rtree index on the bounding rectangle of cities.
--
create index cityrect
on city using rtree (boundbox box_ops)
.fi
.nf
--
--Create a rtree index on a point attribute such that we
--can efficiently use box operators on the result of the
--conversion function. Such a qualification might look
--like "where point2box(points.pointloc) = boxes.box".
--
create index pointloc
on points using rtree (point2box(location) box_ops)
.nf

219
doc/man/create_operator.l Normal file
View File

@ -0,0 +1,219 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_operator.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH "CREATE OPERATOR" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create operator \(em define a new user operator
.SH SYNOPSIS
.nf
\fBcreate operator\fR operator_name
\fB(\fR[ \fBleftarg\fR \fB=\fR type-1 ]
[ \fB,\fR \fBrightarg\fR \fB=\fR type-2 ]
, \fBprocedure =\fR func_name
[\fB, commutator =\fR com_op ]
[\fB, negator =\fR neg_op ]
[\fB, restrict =\fR res_proc ]
[\fB, hashes\fR]
[\fB, join =\fR join_proc ]
[\fB, sort =\fR sor_op1 {\fB,\fR sor_op2 } ]
\fB)\fR
.\" \fB"arg is ("
.\" type [
.\" \fB,
.\" type ]
.\" \fB)
.fi
.SH DESCRIPTION
This command defines a new user operator,
.IR "operator_name" .
The user who defines an operator becomes its owner.
.PP
The
.IR "operator_name"
is a sequence of up to sixteen punctuation characters. The following
characters are valid for single-character operator names:
.nf
~ ! @ # % ^ & ` ?
.fi
If the operator name is more than one character long, it may consist
of any combination of the above characters or the following additional
characters:
.nf
| $ : + - * / < > =
.fi
.PP
At least one of
.IR leftarg
and
.IR rightarg
must be defined. For binary operators, both should be defined. For
right unary operators, only
.IR arg1
should be defined, while for left unary operators only
.IR arg2
should be defined.
.PP
The name of the operator,
.IR operator_name ,
can be composed of symbols only. Also, the
.IR func_name
procedure must have been previously defined using
.IR "create function" (l)
and must have one or two arguments.
.PP
.\" that multiple instances of the
.\" operator must be be evaluated
.\" For example, consider the area-intersection operator,
.\" .q A,
.\" and the following expression:
.\" .(l
.\" MYBOXES2.description A \*(lq0,0,1,1\*(rq A MYBOXES.description
.\" .)l
.\" .in .5i
.\" The associativity flag indicates that
.\" .(l
.\" (MYBOXES2.description A \*(lq0,0,1,1\*(rq) A MYBOXES.description
.\" .)l
.\" .in .5i
.\" is the same as
.\" .(l
.\" MYBOXES2.description A (\*(lq0,0,1,1\*(rq A MYBOXES.description).
.\" .)l
The commutator operator is present so that Postgres can reverse the order
of the operands if it wishes. For example, the operator
area-less-than, >>>, would have a commutator operator,
area-greater-than, <<<. Suppose that an operator, area-equal, ===,
exists, as well as an area not equal, !==. Hence, the query optimizer
could freely convert:
.nf
"0,0,1,1"::box >>> MYBOXES.description
.fi
to
.nf
MYBOXES.description <<< "0,0,1,1"::box
.fi
This allows the execution code to always use the latter representation
and simplifies the query optimizer somewhat.
.PP
The negator operator allows the query optimizer to convert
.nf
not MYBOXES.description === "0,0,1,1"::box
.fi
to
.nf
MYBOXES.description !== "0,0,1,1"::box
.fi
If a commutator operator name is supplied, Postgres searches for it in
the catalog. If it is found and it does not yet have a commutator
itself, then the commutator's entry is updated to have the current
(new) operator as its commutator. This applies to the negator, as
well.
.PP
This is to allow the definition of two operators that are the
commutators or the negators of each other. The first operator should
be defined without a commutator or negator (as appropriate). When the
second operator is defined, name the first as the commutator or
negator. The first will be updated as a side effect.
.PP
The next two specifications are present to support the query optimizer
in performing joins. Postgres can always evaluate a join (i.e.,
processing a clause with two tuple variables separated by an operator
that returns a boolean) by iterative substitution [WONG76]. In
addition, Postgres is planning on implementing a hash-join algorithm
along the lines of [SHAP86]; however, it must know whether this
strategy is applicable. For example, a hash-join algorithm is usable
for a clause of the form:
.nf
MYBOXES.description === MYBOXES2.description
.fi
but not for a clause of the form:
.nf
MYBOXES.description <<< MYBOXES2.description.
.fi
The
.BR hashes
flag gives the needed information to the query optimizer concerning
whether a hash join strategy is usable for the operator in question.
.PP
Similarly, the two sort operators indicate to the query optimizer
whether merge-sort is a usable join strategy and what operators should
be used to sort the two operand classes. For the === clause above,
the optimizer must sort both relations using the operator, <<<. On
the other hand, merge-sort is not usable with the clause:
.nf
MYBOXES.description <<< MYBOXES2.description
.fi
If other join strategies are found to be practical, Postgres will change
the optimizer and run-time system to use them and will require
additional specification when an operator is defined. Fortunately,
the research community invents new join strategies infrequently, and
the added generality of user-defined join strategies was not felt to
be worth the complexity involved.
.PP
The last two pieces of the specification are present so the query
optimizer can estimate result sizes. If a clause of the form:
.nf
MYBOXES.description <<< "0,0,1,1"::box
.fi
is present in the qualification, then Postgres may have to estimate the
fraction of the instances in MYBOXES that satisfy the clause. The
function res_proc must be a registered function (meaning it is already
defined using
.IR "define function" (l))
which accepts one argument of the correct data type and returns a
floating point number. The query optimizer simply calls this
function, passing the parameter
.nf
"0,0,1,1"
.fi
and multiplies the result by the relation size to get the desired
expected number of instances.
.PP
Similarly, when the operands of the operator both contain instance
variables, the query optimizer must estimate the size of the resulting
join. The function join_proc will return another floating point
number which will be multiplied by the cardinalities of the two
classes involved to compute the desired expected result size.
.PP
The difference between the function
.nf
my_procedure_1 (MYBOXES.description, "0,0,1,1"::box)
.fi
and the operator
.nf
MYBOXES.description === "0,0,1,1"::box
.fi
is that Postgres attempts to optimize operators and can decide to use an
index to restrict the search space when operators are involved.
However, there is no attempt to optimize functions, and they are
performed by brute force. Moreover, functions can have any number of
arguments while operators are restricted to one or two.
.SH EXAMPLE
.nf
--
--The following command defines a new operator,
--area-equality, for the BOX data type.
--
create operator === (
leftarg = box,
rightarg = box,
procedure = area_equal_procedure,
commutator = ===,
negator = !==,
restrict = area_restriction_procedure,
hashes,
join = area-join-procedure,
sort = <<<, <<<)
.\" arg is (box, box)
.fi
.SH "SEE ALSO"
create function(l),
drop operator(l).
.SH BUGS
Operator names cannot be composed of alphabetic characters in
Postgres.
.PP
If an operator is defined before its commuting operator has been defined
(a case specifically warned against above), a dummy operator with invalid
fields will be placed in the system catalogs. This may interfere with
the definition of later operators.

221
doc/man/create_rule.l Normal file
View File

@ -0,0 +1,221 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_rule.l,v 1.1.1.1 1996/08/18 22:14:21 scrappy Exp $
.TH "CREATE RULE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create rule \(em define a new rule
.SH SYNOPSIS
.nf
\fBcreate\fR \fBrule\fR rule_name
\fBas\fR \fBon\fR event
\fBto\fR object [\fBwhere\fR clause]
\fBdo\fR [\fBinstead\fR]
[action | nothing | \fB[\fPactions...\fB]\fP]
.fi
.SH DESCRIPTION
.IR "The current rule system implementation is very brittle and is unstable. Users are discouraged from using rules at this time."
.PP
.BR "Create rule"
is used to define a new rule.
.PP
Here,
.IR event
is one of
.IR select ,
.IR update ,
.IR delete
or
.IR insert .
.IR Object
is either:
.nf
a class name
\fIor\fR
class.column
.fi
The
.BR "from"
clause, the
.BR "where"
clause, and the
.IR action
are respectively normal SQL
.BR "from"
clauses,
.BR "where"
clauses and collections of SQL commands with the following change:
.IP
.BR new
or
.BR current
can appear instead of
an instance variable whenever an instance
variable is permissible in SQL.
.PP
The semantics of a rule is that at the time an individual instance is
accessed, updated, inserted or deleted, there is a
.BR current
instance
(for retrieves, updates and deletes) and a
.BR new
instance (for updates and appends). If the event specified in the
.BR "on"
clause and the condition specified in the
.BR "where"
clause are true for the current instance, then the
.IR action
part of the rule is executed. First, however, values from fields in
the current instance and/or the new instance are substituted for:
.nf
current.attribute-name
new.attribute-name
.fi
The
.IR action
part of the rule executes with same command and transaction identifier
as the user command that caused activation.
.PP
A note of caution about SQL rules is in order. If the same class
name or instance variable appears in the event,
.BR where
clause and the
.IR action
parts of a rule, they are all considered different tuple variables.
More accurately,
.BR new
and
.BR current
are the only tuple variables that are shared between these clauses.
For example, the following two rules have the same semantics:
.nf
on update to EMP.salary where EMP.name = "Joe"
do update EMP ( ... ) where ...
on update to EMP-1.salary where EMP-2.name = "Joe"
do update EMP-3 ( ... ) where ...
.fi
Each rule can have the optional tag
.BR "instead" .
Without this tag
.IR action
will be performed in addition to the user command when the event in
the condition part of the rule occurs. Alternately, the
.IR action
part will be done instead of the user command.
In this later case, the action can be the keyword
.BR nothing .
.PP
When choosing between the rewrite and instance rule systems for a
particular rule application, remember that in the rewrite system
.BR current
refers to a relation and some qualifiers whereas in the instance
system it refers to an instance (tuple).
.PP
It is very important to note that the
.BR rewrite
rule system will
neither detect nor process circular
rules. For example, though each of the following two rule
definitions are accepted by Postgres, the
.IR retrieve
command will cause
Postgres to
.IR crash :
.nf
--
--Example of a circular rewrite rule combination.
--
create rule bad_rule_combination_1 is
on select to EMP
do instead select to TOYEMP
create rule bad_rule_combination_2 is
on select to TOYEMP
do instead select to EMP
--
--This attempt to retrieve from EMP will cause Postgres to crash.
--
select * from EMP
.fi
.PP
You must have
.IR "rule definition"
access to a class in order to define a rule on it (see
.IR "change acl" (l).
.SH EXAMPLES
.nf
--
--Make Sam get the same salary adjustment as Joe
--
create rule example_1 is
on update EMP.salary where current.name = "Joe"
do update EMP (salary = new.salary)
where EMP.name = "Sam"
.fi
At the time Joe receives a salary adjustment, the event will become
true and Joe's current instance and proposed new instance are available
to the execution routines. Hence, his new salary is substituted into the
.IR action
part of the rule which is subsequently executed. This propagates
Joe's salary on to Sam.
.nf
--
--Make Bill get Joe's salary when it is accessed
--
create rule example_2 is
on select to EMP.salary
where current.name = "Bill"
do instead
select (EMP.salary) from EMP where EMP.name = "Joe"
.fi
.nf
--
--Deny Joe access to the salary of employees in the shoe
--department. (pg_username() returns the name of the current user)
--
create rule example_3 is
on select to EMP.salary
where current.dept = "shoe"
and pg_username() = "Joe"
do instead nothing
.fi
.nf
--
--Create a view of the employees working in the toy department.
--
create TOYEMP(name = char16, salary = int4)
create rule example_4 is
on select to TOYEMP
do instead select (EMP.name, EMP.salary) from EMP
where EMP.dept = "toy"
.fi
.nf
--
--All new employees must make 5,000 or less
--
create rule example_5 is
on insert to EMP where new.salary > 5000
do update newset salary = 5000
.fi
.SH "SEE ALSO"
drop rule(l),
create view(l).
.SH BUGS
.PP
.BR "instead"
rules do not work properly.
.PP
The object in a SQL rule cannot be an array reference and cannot
have parameters.
.PP
Aside from the \*(lqoid\*(rq field, system attributes cannot be
referenced anywhere in a rule. Among other things, this means that
functions of instances (e.g., \*(lqfoo(emp)\*(rq where \*(lqemp\*(rq
is a class) cannot be called anywhere in a rule.
.PP
The rule system store the rule text and query plans as text
attributes. This implies that creation of rules may fail if the
rule plus its various internal representations exceed some value
that is on the order of one page (8KB).

145
doc/man/create_table.l Normal file
View File

@ -0,0 +1,145 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_table.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH "CREATE TABLE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create table \(em create a new class
.SH SYNOPSIS
.nf
\fBcreate table \fR classname \fB(\fPattname-1 type-1 {\fB,\fP attname-i type-i}\fB)\fP
[\fBinherits\fR \fB(\fR classname-1 {\fB,\fR classname-i} \fB)\fR]
[\fBarchive\fR \fB=\fR archive_mode]
[\fBstore\fR \fB=\fR \*(lqsmgr_name\*(rq]
[\fBarch_store\fR \fB=\fR \*(lqsmgr_name\*(rq]
.fi
.SH DESCRIPTION
.BR "Create table"
will enter a new class into the current data base. The class will be
\*(lqowned\*(rq by the user issuing the command. The name of the
class is
.IR classname
and the attributes are as specified in the list of
.IR attname s.
The
.IR i th
attribute is created with the type specified by
.IR type "-i."
Each type may be a simple type, a complex type (set) or an array type.
.PP
Each array attribute stores arrays that must have the same number of
dimensions but may have different sizes and array index bounds. An
array of dimension
.IR n
is specified by appending
.IR n
pairs of square brackets:
.nf
att_name = type[][]..[]
.fi
.PP
The optional
.BR inherits
clause specifies a collection of class names from which this class
automatically inherits all fields. If any inherited field name
appears more than once, Postgres reports an error. Postgres automatically
allows the created class to inherit functions on classes above it in
the inheritance hierarchy. Inheritance of functions is done according
to the conventions of the Common Lisp Object System (CLOS).
.PP
Each new class
.IR classname
is automatically created as a type. Therefore, one or more instances
from the class are automatically a type and can be used in
.IR alter table(l)
or other
.BR "create table"
statements. See
.IR introduction (l)
for a further discussion of this point.
.PP
The optional
.BR store
and
.BR arch_store
keywords may be used to specify a storage manager to use for the new
class. The released version of Postgres supports only \*(lqmagnetic
disk\*(rq as a storage manager name; the research system at UC Berkeley
provides additional storage managers.
.BR Store
controls the location of current data,
and
.BR arch_store
controls the location of historical data.
.BR Arch_store
may only be specified if
.BR archive
is also specified. If either
.BR store
or
.BR arch_store
is not declared, it defaults to \*(lqmagnetic disk\*(rq.
.PP
The new class is created as a heap with no initial data. A class can
have no more than 1600 attributes (realistically, this is limited by the
fact that tuple sizes must be less than 8192 bytes), but this limit
may be configured lower at some sites. A class cannot have the same
name as a system catalog class.
.PP
The
.BR archive
keyword specifies whether historical data is to be saved or discarded.
.IR Arch_mode
may be one of:
.TP 10n
.IR none
No historical access is supported.
.TP 10n
.IR light
Historical access is allowed and optimized for light update activity.
.TP 10n
.IR heavy
Historical access is allowed and optimized for heavy update activity.
.PP
.IR Arch_mode
defaults to \*(lqnone\*(rq. Once the archive status is set, there is
no way to change it. For details of the optimization, see [STON87].
.SH EXAMPLES
.nf
--
-- Create class emp with attributes name, sal and bdate
--
create table emp (name char16, salary float4, bdate abstime)
.fi
.nf
--
--Create class permemp with pension information that
--inherits all fields of emp
--
create table permemp (plan char16) inherits (emp)
.fi
.nf
--
--Create class foo on magnetic disk and archive historical data
--
create table foo (bar int4) archive = heavy
store = "magnetic disk"
.fi
.nf
--
--Create class tictactoe to store noughts-and-crosses
--boards as a 2-dimensional array
--
create table tictactoe (game int4, board = char[][])
.fi
.nf
--
--Create a class newemp with a set attribute "manager". A
--set (complex) attribute may be of the same type as the
--relation being defined (as here) or of a different complex
--type. The type must exist in the "pg_type" catalog or be
--the one currently being defined.
--
create table newemp (name text, manager = newemp)
.fi
.SH "SEE ALSO"
drop table(l).

161
doc/man/create_type.l Normal file
View File

@ -0,0 +1,161 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_type.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH "CREATE TYPE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create type \(em define a new base data type
.SH SYNOPSIS
.nf
\fBcreate type\fP typename \fB(\fR\fBinternallength\fR = (number | \fBvariable\fR),
[ \fBexternallength\fR = (number | \fBvariable\fR)\fB,\fR ]
\fBinput\fR = input_function,
\fBoutput\fR = output_function
[\fB,\fR \fBelement\fR = typename]
[\fB,\fR \fBdelimiter\fR = <character>]
[\fB,\fR \fBdefault\fR = "string" ]
[\fB,\fR \fBsend\fR = send_function ]
[\fB,\fR \fBreceive\fR = receive_function ]
[\fB,\fR \fBpassedbyvalue\fR]\fB)\fR
.fi
.\" \fBcreate type\fP typename as sql_commands
.SH DESCRIPTION
.BR "Create type"
allows the user to register a new user data type with Postgres for use in
the current data base. The user who defines a type becomes its owner.
.IR Typename
is the name of the new type and must be unique within the types
defined for this database.
.PP
.BR "Create type"
requires the registration of two functions (using
.IR "create function" (l))
before defining the type. The representation of a new base type is
determined by
.IR input_function ,
which converts the type's external representation to an internal
representation usable by the operators and functions defined for the
type. Naturally,
.IR "output_function"
performs the reverse transformation. Both the input and output
functions must be declared to take one or two arguments of type
\*(lqopaque\*(rq.
.PP
New base data types can be fixed length, in which case
.BR "internallength"
is a positive integer, or variable length, in which case Postgres assumes
that the new type has the same format as the Postgres-supplied data type,
\*(lqtext\*(rq. To indicate that a type is variable-length, set
.BR "internallength"
to
.IR "variable" .
The external representation is similarly specified using the
.IR "externallength"
keyword.
.PP
To indicate that a type is an array and to indicate that a type has
array elements, indicate the type of the array element using the
.BR "element"
keyword. For example, to define an array of 4 byte integers
(\*(lqint4\*(rq), specify
.nf
element = int4
.fi
.PP
To indicate the delimiter to be used on arrays of this type,
.BR "delimiter"
can be set to a specific character. The default delimiter is the
comma (\*(lq,\*(rq) character.
.PP
A
.BR "default"
value is optionally available in case a user wants some specific bit
pattern to mean \*(lqdata not present.\*(rq
.PP
The optional functions
.IR "send_function"
and
.IR "receive_function"
are used when the application program requesting Postgres services
resides on a different machine. In this case, the machine on which
Postgres runs may use a different format for the data type than used on
the remote machine. In this case it is appropriate to convert data
items to a standard form when
.BR send ing
from the server to the client and converting from the standard format
to the machine specific format when the server
.BR receive s
the data from the client. If these functions are not specified, then
it is assumed that the internal format of the type is acceptable on
all relevant machine architectures. For example, single characters do
not have to be converted if passed from a Sun-4 to a DECstation, but
many other types do.
.PP
The optional
.BR "passedbyvalue"
flag indicates that operators and functions which use this data type
should be passed an argument by value rather than by reference. Note
that only types whose internal representation is at most four bytes
may be passed by value.
.PP
For new base types, a user can define operators, functions and
aggregates using the appropriate facilities described in this section.
.SH "ARRAY TYPES"
Two generalized built-in functions,
.BR array_in
and
.BR array_out,
exist for quick creation of variable-length array types. These
functions operate on arrays of any existing Postgres type.
.SH "LARGE OBJECT TYPES"
A \*(lqregular\*(rq Postgres type can only be 8192 bytes in length. If
you need a larger type you must create a Large Object type. The
interface for these types is discussed at length in Section 7, the
large object interface. The length of all large object types
is always
.IR variable,
meaning the
.BR internallength
for large objects is always -1.
.SH EXAMPLES
.nf
--
--This command creates the box data type and then uses the
--type in a class definition
--
create type box (internallength = 8,
input = my_procedure_1, output = my_procedure_2)
create table MYBOXES (id = int4, description = box)
.fi
.nf
--
--This command creates a variable length array type with
--integer elements.
--
create type int4array
(input = array_in, output = array_out,
internallength = variable, element = int4)
create table MYARRAYS (id = int4, numbers = int4array)
.fi
.nf
--
--This command creates a large object type and uses it in
--a class definition.
--
create type bigobj
(input = lo_filein, output = lo_fileout,
internallength = variable)
create table BIG_OBJS (id = int4, obj = bigobj)
.fi
.SH "RESTRICTIONS"
Type names cannot begin with the underscore character (\*(lq_\*(rq)
and can only be 15 characters long. This is because Postgres silently
creates an array type for each base type with a name consisting of the
base type's name prepended with an underscore.
.SH "SEE ALSO"
create function(l),
create operator(l),
drop type(l),
introduction(large objects).

69
doc/man/create_version.l Normal file
View File

@ -0,0 +1,69 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_version.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH "CREATE VERSION" SQL 01/23/93 Postgres95 Postgres95
.SH NAME
create version \(em construct a version class
.SH SYNOPSIS
.nf
\fBcreate version\fP classname1 \fBfrom\fP classname2 [\fB[\fPabstime\fB]\fP]
.fi
.SH DESCRIPTION
.IR "Currently, the versioning facility is not working."
.PP
This command creates a version class
.IR classname1
which is related
to its parent class,
.IR classname2 .
Initially,
.IR classname1
has the same contents as
.IR classname2.
As updates to
.IR classname1
occur, however,
the content of
.IR classname1
diverges from
.IR classname2.
On the other hand, any updates to
.IR classname2
show transparently through to
.IR classname1 ,
unless the instance in question has already been updated in
.IR classname1 .
.PP
If the optional
.IR abstime
clause is specified, then the version is constructed relative to a
.BR snapshot
of
.IR classname2
as of the time specified.
.PP
Postgres uses the query rewrite rule system to ensure that
.IR classname1
is differentially encoded relative to
.IR classname2.
Moreover,
.IR classname1
is automatically constructed to have the same indexes as
.IR classname2 .
It is legal to cascade versions arbitrarily, so a tree of versions can
ultimately result. The algorithms that control versions are explained
in [ONG90].
.SH EXAMPLE
.nf
--
--create a version foobar from a snapshot of
--barfoo as of January 17, 1990
--
create version foobar from barfoo [ "Jan 17 1990" ]
.fi
.SH "SEE ALSO"
create view(l), merge(l).
.SH "BUGS"
Snapshots (i.e., the optional
.IR abstime
clause) are not implemented in Postgres.

45
doc/man/create_view.l Normal file
View File

@ -0,0 +1,45 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/create_view.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH "CREATE VIEW" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create view \(em construct a virtual class
.SH SYNOPSIS
.nf
\fBcreate view\fR view_name \fBas\fR
\fBselect\fR expression1 [\fBas\fR attr_name1]
{, expression_i [\fBas\fR attr_namei]}
[\fBfrom\fR from.last]
[\fBwhere\fR qual]
.fi
.SH DESCRIPTION
.BR "create view"
will define a view of a class. This view is not physically
materialized; instead the rule system is used to support view
processing as in [STON90]. Specifically, a query rewrite retrieve
rule is automatically generated to support retrieve operations on
views. Then, the user can add as many update rules as desired to
specify the processing of update operations to views. See [STON90]
for a detailed discussion of this point.
.SH EXAMPLE
.nf
--
--create a view consisting of toy department employees
--
create view toyemp as
select e.name
from emp e
where e.dept = 'toy'
.fi
.nf
--
--Specify deletion semantics for toyemp
--
create rule example1 as
on delete to toyemp
do instead delete emp
where emp.oid = current.oid
.fi
.SH "SEE ALSO"
create table(l),
create rule(l),

127
doc/man/createdb.1 Normal file
View File

@ -0,0 +1,127 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/createdb.1,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH CREATEDB UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
createdb \(em create a database
.SH SYNOPSIS
.BR createdb
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[dbname]
.SH DESCRIPTION
.IR Createdb
creates a new database. The person who executes this command becomes
the database administrator, or DBA, for this database and is the only
person, other than the Postgres super-user, who can destroy it.
.PP
.IR Createdb
is a shell script that invokes
.IR psql .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR createdb
is executed. In addition, the
.SM PGOPTION
and
.SM PGREALM
environment variables will be passed on to
.IR psql
and processed as described in
.IR psql (1).
.PP
The optional argument
.IR dbname
specifies the name of the database to be created. The name must be
unique among all Postgres databases.
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
.IR Createdb
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.SH EXAMPLES
.nf
# create 5432 demo database
createdb demo
.fi
.nf
# create the demo database using the postmaster on host eden,
# port using the Kerberos authentication system.
createdb -a kerberos -p 5432 -h eden demo
.fi
.SH FILES
.TP 5n
\&$PGDATA/base/\fIdbname\fP
The location of the files corresponding to the database
.IR dbname .
.SH "SEE ALSO"
createdb(l),
destroydb(1),
initdb(1),
psql(1),
postmaster(1).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Createdb
could not attach to the
.IR postmaster
process on the specified host and port. If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
You do not have a valid entry in the relation \*(lqpg_user\*(rq and
cannot do anything with Postgres at all; contact your Postgres site
administrator.
.TP
.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
You do not have permission to create new databases; contact your Postgres
site administrator.
.TP
.IB "dbname" " already exists"
The database already exists.
.TP
.BI "database creation failed on" " dbname"
An internal error occurred in
.IR psql
or the backend server. Ensure that your Postgres site administrator has
properly installed Postgres and initialized the site with
.IR initdb .

25
doc/man/createdb.l Normal file
View File

@ -0,0 +1,25 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/createdb.l,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH "CREATE DATABASE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
create database \(em create a new database
.SH SYNOPSIS
.nf
\fBcreate database\fP dbname
.fi
.SH DESCRIPTION
.BR "Create database"
creates a new Postgres database. The creator becomes the administrator
of the new database.
.SH "SEE ALSO"
createdb(1),
drop database(l),
destroydb(1),
initdb(1).
.SH BUGS
This command should
.BR NOT
be executed interactively. The
.IR createdb (1)
script should be used instead.

122
doc/man/createuser.1 Normal file
View File

@ -0,0 +1,122 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/createuser.1,v 1.1.1.1 1996/08/18 22:14:22 scrappy Exp $
.TH CREATEUSER UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
createuser \(em create a Postgres user
.SH SYNOPSIS
.BR createuser
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[username]
.SH DESCRIPTION
.IR Createuser
creates a new Postgres user. Only users with \*(lqusesuper\*(rq set in
the \*(lqpg_user\*(rq class can create new Postgres users. As shipped,
the user \*(lqpostgres\*(rq can create users.
.PP
.IR Createuser
is a shell script that invokes
.IR psql .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR createuser
is executed. In addition, the
.SM PGOPTION
and
.SM PGREALM
environment
variables will be passed on to
.IR psql
and processed as described in
.IR psql (1).
.PP
The optional argument
.IR username
specifies the name of the Postgres user to be created. (The invoker will
be prompted for a name if none is specified on the command line.)
This name must be unique among all Postgres users.
.PP
.IR Createuser
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.SH "INTERACTIVE QUESTIONS"
Once invoked with the above options,
.IR createuser
will ask a series of questions. The new users's login name (if not
given on the command line) and user-id must be specified. (Note that
the Postgres user-id must be the same as the user's Unix user-id.) In
addition, you must describe the security capabilities of the new user.
Specifically, you will be asked whether the new user should be able to
act as Postgres super-user, create new databases and update the system
catalogs manually.
.SH "SEE ALSO"
destroyuser(1),
psql(1),
postmaster(1).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Createuser
could not attach to the
.IR postmaster
process on the specified host and port. If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
You do not have a valid entry in the relation \*(lqpg_user\*(rq and
cannot do anything with Postgres at all; contact your Postgres site
administrator.
.TP
.IB "username" " cannot create users."
You do not have permission to create new users; contact your Postgres
site administrator.
.TP
.BI "user \*(lq" "username" "\*(rq already exists"
The user to be added already has an entry in the \*(lqpg_user\*(rq
class.
.TP
.BR "database access failed"
An internal error occurred in
.IR psql
or the backend server. Ensure that your Postgres site administrator has
properly installed Postgres and initialized the site with
.IR initdb .
.SH BUGS
Postgres user-ids and user names should not have anything to do with the
constraints of Unix.

41
doc/man/delete.l Normal file
View File

@ -0,0 +1,41 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/delete.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH DELETE SQL 11/05/95 Postgres95 Postgres95
.SH NAME
delete \(em delete instances from a class
.SH SYNOPSIS
.nf
\fBdelete\fR instance_variable [ \fBfrom\fR from_list ] [ \fBwhere\fR qual ]
.fi
.SH DESCRIPTION
.BR Delete
removes instances which satisfy the qualification,
.IR qual ,
from the class specified by
.IR instance_variable .
.IR Instance_variable
is either a class name or a variable assigned by
.IR from_list .
If the qualification is absent, the effect is to delete all instances
in the class. The result is a valid, but empty class.
.PP
You must have write access to the class in order to modify it, as well
as read access to any class whose values are read in the qualification
(see
.IR "change acl" (l).
.SH EXAMPLE
.nf
--
--Remove all employees who make over $30,000
--
delete from emp where emp.sal > 30000
.fi
.nf
--
--Clear the hobbies class
--
delete from hobbies
.fi
.SH "SEE ALSO"
drop(l).

134
doc/man/destroydb.1 Normal file
View File

@ -0,0 +1,134 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.1,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH DESTROYDB UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
destroydb \(em destroy an existing database
.SH SYNOPSIS
.BR destroydb
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[dbname]
.SH DESCRIPTION
.IR Destroydb
destroys an existing database. To execute this command, the user must
be the database administrator, or DBA, for this database.
The program runs silently; no confirmation message will be displayed.
After the database is destroyed, a Unix shell prompt will reappear.
.PP
.IR Destroydb
is a shell script that invokes
.IR psql .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR destroydb
is executed. In addition, the
.SM PGOPTION
and
.SM PGREALM
environment
variables will be passed on to
.IR psql
and processed as described in
.IR psql (1).
.PP
The optional argument
.IR dbname
specifies the name of the database to be destroyed. All references to
the database are removed, including the directory containing this
database and its associated files.
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
.IR Destroydb
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.SH EXAMPLES
.nf
# destroy the demo database
destroydb demo
.fi
.nf
# destroy 5432 demo database using the postmaster on host eden,
# port using the Kerberos authentication system.
destroydb -a kerberos -p 5432 -h eden demo
.fi
.SH FILES
.TP 5n
\&$PGDATA/base/\fIdbname\fP
The location of the files corresponding to the database
.IR dbname .
.SH "SEE ALSO"
destroydb(l),
createdb(1),
initdb(1),
psql(1).
postmaster(1).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Destroydb
could not attach to the
.IR postmaster
process on the specified host and port. If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
You do not have a valid entry in the relation \*(lqpg_user\*(rq and
cannot do anything with Postgres at all; contact your Postgres site
administrator.
.TP
.BI "user \*(lq" "username" "\*(rq is not allowed to create/destroy databases"
You do not have permission to destroy databases; contact your Postgres
site administrator.
.TP
.BR "database \*(lqdbname\*(rq does not exist"
The database to be removed does not have an entry in the
\*(lqpg_database\*(rq class.
.TP
.BI "database \*(lq" "dbname" "\*(rq is not owned by you"
You are not DBA for the specified database.
.TP
.BI "database destroy failed on" " dbname"
An internal error occurred in
.IR psql
or the backend server. Contact your Postgres site administrator to
ensure that ensure that the files and database entries associated with
the database are completely removed.

26
doc/man/destroydb.l Normal file
View File

@ -0,0 +1,26 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroydb.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH DESTROYDB SQL 01/23/93 Postgres95 Postgres95
.SH NAME
drop database \(em destroy an existing database
.SH SYNOPSIS
.nf
\fBdrop database\fR dbname
.fi
.SH DESCRIPTION
.BR "Drop database"
removes the catalog entries for an existing database and deletes the
directory containing the data. It can only be executed by the
database administrator (see
.IR createdb (l)
for details).
.SH "SEE ALSO"
create database(l),
destroydb(1).
.SH BUGS
This query should
.BR NOT
be executed interactively. The
.IR destroydb (1)
script should be used instead.

119
doc/man/destroyuser.1 Normal file
View File

@ -0,0 +1,119 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/destroyuser.1,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH DESTROYUSER UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
destroyuser \(em destroy a Postgres user and associated databases
.SH SYNOPSIS
.BR destroyuser
[\c
.BR -a
system]
[\c
.BR -h
host]
[\c
.BR -p
port]
[username]
.SH DESCRIPTION
.PP
.IR Destroyuser
destroys an existing Postgres user and the databases for which that user
is database administrator. Only users with \*(lqusesuper\*(rq set in
the \*(lqpg_user\*(rq class can destroy new Postgres users. As shipped,
the user \*(lqpostgres\*(rq can destroy users.
.PP
.IR Destroyuser
is a shell script that invokes
.IR psql .
Hence, a
.IR postmaster
process must be running on the database server host before
.IR destroyuser
is executed. In addition, the
.SM PGOPTION
and
.SM PGREALM
environment variables will be passed on to
.IR psql
and processed as described in
.IR psql (1).
.PP
The optional argument
.IR username
specifies the name of the Postgres user to be destroyed. (The invoker will
be prompted for a name if none is specified on the command line.)
.PP
.IR Destroyuser
understands the following command-line options:
.TP 5n
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-h" " host"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.SH "INTERACTIVE QUESTIONS"
.PP
Once invoked with the above options,
.IR destroyuser
will warn you about the databases that will be destroyed in the
process and permit you to abort the removal of the user if desired.
.SH "SEE ALSO"
createuser(1),
psql(1),
postmaster(1).
.SH DIAGNOSTICS
.TP 5n
.BI "Error: Failed to connect to backend (host=" "xxx" ", port=" "xxx" ")"
.IR Destroyuser
could not attach to the
.IR postmaster
process on the specified host and port. If you see this message,
ensure that the
.IR postmaster
is running on the proper host and that you have specified the proper
port. If your site uses an authentication system, ensure that you
have obtained the required authentication credentials.
.TP
.BI "user \*(lq" "username" "\*(rq is not in \*(lqpg_user\*(rq"
You do not have a valid entry in the relation \*(lqpg_user\*(rq and
cannot do anything with Postgres at all; contact your Postgres site
administrator.
.TP
.IB "username" " cannot delete users."
You do not have permission to delete users; contact your Postgres site
administrator.
.TP
.BI "user \*(lq" "username" "\*(rq does not exist"
The user to be removed does not have an entry in the \*(lqpg_user\*(rq
class.
.TP
.BR "database access failed"
.TP
.BI "destroydb on" " dbname" " failed - exiting"
.TP
.BI "delete of user" " username" " was UNSUCCESSFUL"
An internal error occurred in
.IR psql
or the backend server. Contact your Postgres site administrator to
ensure that the files and database entries associated with the user
and his/her associated databases are completely removed.

41
doc/man/drop.l Normal file
View File

@ -0,0 +1,41 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH "DROP TABLE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop table \(em destroy existing classes
.SH SYNOPSIS
.nf
\fBdrop table\fR classname-1 { \fB,\fR classname-i }
.fi
.SH DESCRIPTION
.BR "Drop Table"
removes classes from the data base. Only its owner may destroy a
class. A class may be emptied of instances, but not destroyed, by
using
.IR delete (l).
.PP
If a class being destroyed has secondary indices on it, then they will
be removed first. The removal of just a secondary index will not
affect the indexed class.
.PP
The destruction of classes is not reversable. Thus, a destroyed class
will not be recovered if a transaction which destroys this class fails
to commit. In addition, historical access to instances in a destroyed
class is not possible.
.SH EXAMPLE
.nf
--
--Destroy the emp class
--
drop table emp
.fi
.nf
--
--Destroy the emp and parts classes
--
drop table emp, parts
.fi
.SH "SEE ALSO"
delete(l),
drop index(l).

24
doc/man/drop_aggregate.l Normal file
View File

@ -0,0 +1,24 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_aggregate.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH "DROP AGGREGATE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop aggregate \(em remove the definition of an aggregate
.SH SYNOPSIS
.nf
\fBdrop aggregate\fR aggname
.fi
.SH DESCRIPTION
.BR "drop aggregate"
will remove all reference to an existing aggregate definition. To
execute this command the current user must be the the owner of the
aggregate.
.SH EXAMPLE
.nf
--
--Remove the average aggregate
--
drop aggregate avg
.fi
.SH "SEE ALSO"
create aggregate(l).

28
doc/man/drop_function.l Normal file
View File

@ -0,0 +1,28 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_function.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH "DROP FUNCTION" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop function \(em remove a user-defined C function
.SH SYNOPSIS
.nf
\fBdrop function \fRfunction_name ( \fP[ type-1 { \fB,\fP type-n } ] \fB)
.fi
.SH DESCRIPTION
.BR "drop function"
will remove references to an existing C function. To execute this
command the user must be the owner of the function. The input
argument types to the function must be specified, as only the
function with the given name and argument types will be removed.
.SH EXAMPLE
.nf
--
--this command removes the square root function
--
drop function sqrt(int4)
.fi
.SH "SEE ALSO"
create function(l).
.SH BUGS
No checks are made to ensure that types, operators or access methods
that rely on the function have been removed first.

22
doc/man/drop_index.l Normal file
View File

@ -0,0 +1,22 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_index.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH "DROP INDEX" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop index \(em removes an index from Postgres
.SH SYNOPSIS
.nf
\fBdrop index\fR index_name
.fi
.SH DESCRIPTION
This command drops an existing index from the Postgres system. To
execute this command you must be the owner of the index.
.SH EXAMPLE
.nf
--
--this command will remove the "emp_index" index
--
drop index emp_index
.fi
.SH "SEE ALSO"
create index(l).

44
doc/man/drop_operator.l Normal file
View File

@ -0,0 +1,44 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_operator.l,v 1.1.1.1 1996/08/18 22:14:23 scrappy Exp $
.TH "DROP OPERATOR" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop operator \(em remove an operator from the system
.SH SYNOPSIS
.nf
\fBdrop operator\fR opr_desc
.fi
.SH DESCRIPTION
This command drops an existing operator from the database. To execute
this command you must be the owner of the operator.
.PP
.IR Opr_desc
is the name of the operator to be removed followed by a parenthesized
list of the operand types for the operator. The left or right type
of a left or right unary operator, respectively, may be specified
as
.IR none .
.PP
It is the user's responsibility to remove any access methods, operator
classes, etc. that rely on the deleted operator.
.SH EXAMPLE
.nf
--
--Remove power operator a^n for int4
--
drop operator ^ (int4, int4)
.fi
.nf
--
--Remove left unary operator !a for booleans
--
drop operator ! (none, bool)
.fi
.nf
--
--Remove right unary factorial operator a! for int4
--
drop operator ! (int4, none)
.fi
.SH "SEE ALSO"
create operator(l).

27
doc/man/drop_rule.l Normal file
View File

@ -0,0 +1,27 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_rule.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH "DROP RULE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop rule \- removes a current rule from Postgres
.SH SYNOPSIS
.nf
\fBdrop rule\fR rule_name
.fi
.SH DESCRIPTION
This command drops the rule named rule_name from the specified Postgres
rule system. Postgres will immediately cease enforcing it and will purge
its definition from the system catalogs.
.SH EXAMPLE
.nf
--
--This example drops the rewrite rule example_1
--
drop rule example_1
.fi
.SH "SEE ALSO"
create rule(l),
drop view(l).
.SH BUGS
Once a rule is dropped, access to historical information the rule has
written may disappear.

30
doc/man/drop_type.l Normal file
View File

@ -0,0 +1,30 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/drop_type.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH "DROP TYPE" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
drop type \(em remove a user-defined type from the system catalogs
.SH SYNOPSIS
.nf
\fBdrop type\fR typename
.fi
.SH DESCRIPTION
This command removes a user type from the system catalogs. Only the
owner of a type can remove it.
.PP
It is the user's responsibility to remove any operators, functions,
aggregates, access methods, subtypes, classes, etc. that use a
deleted type.
.SH EXAMPLE
.nf
--
--remove the box type
--
drop type box
.fi
.SH "SEE ALSO"
introduction(l),
create type(l),
drop operator(l).
.SH "BUGS"
If a built-in type is removed, the behavior of the backend is unpredictable.

17
doc/man/end.l Normal file
View File

@ -0,0 +1,17 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/end.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH END SQL 01/23/93 Postgres95 Postgres95
.SH NAME
end \(em commit the current transaction
.SH SYNOPSIS
.nf
\fBend [transaction]\fR
.fi
.SH DESCRIPTION
This commands commits the current transaction. All changes made by
the transaction become visible to others and are guaranteed to be
durable if a crash occurs.
.SH "SEE ALSO"
abort(l),
begin(l).

70
doc/man/fetch.l Normal file
View File

@ -0,0 +1,70 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/fetch.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH FETCH SQL 01/23/93 Postgres95 Postgres95
.SH NAME
fetch \(em fetch instance(s) from a cursor
.SH SYNOPSIS
.nf
\fBfetch\fR [ (\fBforward\fR | \fBbackward\fR) ] [ ( number | \fBall\fR) ] [\fBin\fR cursor_name]
.fi
.SH DESCRIPTION
.BR Fetch
allows a user to retrieve instances from a cursor named
.IR cursor_name.
The number of instances retrieved is specified by
.IR number .
If the number of instances remaining in the cursor is less than
.IR number ,
then only those available are fetched. Substituting the keyword
.IR all
in place of a number will cause all remaining instances in the cursor
to be retrieved. Instances may be fetched in both
.IR forward
and
.IR backward
directions. The default direction is
.IR forward .
.PP
Updating data in a cursor is not supported by Postgres, because mapping
cursor updates back to base classes is impossible in general as with
view updates. Consequently, users must issue explicit replace
commands to update data.
.PP
Portals may only be used inside of transaction blocks marked by
.IR begin (l)
and
.IR end (l)
because the data that they store spans multiple user queries.
.SH EXAMPLE
.nf
--
--set up and use a cursor
--
begin
declare myportal cursor for
select * from pg-user
end
.fi
.nf
--
--Fetch all the instances available in the portal FOO
--
fetch all in FOO
.fi
.nf
--
--Fetch 5 instances backward in the portal FOO
--
fetch backward 5 in FOO
.fi
.SH "SEE ALSO"
begin(l),
end(l),
close(l),
move(l),
select(l).
.SH BUGS
Currently, the smallest transaction in Postgres is a single SQL
command. It should be possible for a single fetch to be a
transaction.

37
doc/man/files.5 Normal file
View File

@ -0,0 +1,37 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/files.5,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH INFORMATION FILES 01/23/93 Postgres95 Postgres95
.SH "Section 8 \(em Files"
.SH "General Information"
.SH OVERVIEW
This section describes
some of the important files used by Postgres.
.SH NOTATION
\*(lq.../\*(rq at the front of file names represents the path to the
postgres user's home directory. Anything in square brackets
.RB (\*(lq "[" \*(rq
and
.RB \*(lq "]" \*(rq)
is optional.
Anything in braces
.RB (\*(lq "{" \*(rq
and
.RB \*(lq "}" \*(rq)
can be repeated 0 or more times. Parentheses
.BR (\*(lq "(" \*(rq
and
.BR \*(lq ")" \*(rq)
are used to group boolean expressions.
.BR |
is the boolean operator
.SM OR\c
\&.
.SH BUGS
The descriptions of
.nf
.../data/PG_VERSION,
.../data/base/*/PG_VERSION,
.fi
the temporary sort files, and the database debugging trace files are
absent.

33
doc/man/grant.l Normal file
View File

@ -0,0 +1,33 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/grant.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH GRANT SQL 11/05/95 Postgres95 Postgres95
.SH NAME
grant \(em grant access control to a user or group
.SH SYNOPSIS
.nf
\fBgrant\fR <privilege[,privilege,...]>
\fBon\fR <rel1>[,...<reln>]
\fBto\fR [\fBpublic\fR | group <group> | <username>]
\fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
.fi
.SH DESCRIPTION
.PP
.B Grant
allows you to give specified permissions to all users or
a certain user or group.
By default, a table grants read-only (\fBSELECT\fR) to all Postgres users.
You must specifically revoke this privilege if this is not desired.
.SH EXAMPLES
.nf
--
--Example of a grant
--
grant insert
on mytab
to public
.fi
.SH "SEE ALSO"
revoke(l)

65
doc/man/initdb.1 Normal file
View File

@ -0,0 +1,65 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/initdb.1,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH INITDB UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
initdb \(em initalize the database templates and primary directories
.SH SYNOPSIS
.BR "initdb"
[\c
.BR "-v"
]
[\c
.BR "-d"
]
[\c
.BR "-n"
]
.SH DESCRIPTION
.IR Initdb
sets up the initial template databases and is normally executed as
part of the installation process. The template database is created
under the directory specified by the the environment variable
.SM PGDATA,
or to a default specified at compile-time. The template database
is then
.BR vacuum ed.
.PP
.IR Initdb
is a shell script that invokes the backend server directly. Hence, it
must be executed by the Postgres super-user.
.PP
.IR Initdb
understands the following command-line options:
.TP
.BR "-v"
Produce verbose output, printing messages stating where the
directories are being created, etc.
.TP
.BR "-d"
Print debugging output from the backend server. This option generates
a tremendous amount of information. This option also turns off the
final vacuuming step.
.TP
.BR "-n"
Run in \*(lqnoclean\*(rq mode. By default,
.IR initdb
cleans up (recursively unlinks) the data directory if any error
occurs, which also removes any core files left by the backend server.
This option inhibits any tidying-up.
.SH FILES
.TP
\&$PGDATA/base
The location of global (shared) classes.
.TP
\&$PGDATA/base/template1
The location of the template database.
.TP
\&$PGDATA/files/{global1,local1_template1}.bki
Command files used to generate the global and template databases,
generated and installed by the initial compilation process.
.SH "SEE ALSO"
createdb(1),
vacuum(l),
bki(files),
template(files).

113
doc/man/insert.l Normal file
View File

@ -0,0 +1,113 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/insert.l,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH INSERT SQL 11/05/95 Postgres95 Postgres95
.SH NAME
insert \(em insert tuples to a relation
.SH SYNOPSIS
.nf
\fBinsert\fR into classname
[(att.expr-1,{att_expr.i})]
{\fBvalues\fR (expression1 {,expression-i}) |
\fBselect\fR expression1,{expression-i}
[\fBfrom\fR from-list] [\fBwhere\fR qual]
.fi
.SH DESCRIPTION
.BR Insert
adds instances that satisfy the qualification,
.IR qual ,
to
.IR classname .
.IR Classname
must be the name of an existing class. The target list specifies the
values of the fields to be appended to
.IR classname .
That is, each
.IR att_expr
specifies a field (either an attribute name or an attribute name plus
an array specification) to which the corresponding
.IR expression
should be assigned. The fields in the target list may be listed in
any order. Fields of the result class which do not appear in the
target list default to NULL. If the expression for each field is not
of the correct data type, automatic type coercion will be attempted.
.PP
An array initialization may take exactly one of the following forms:
.nf
--
-- Specify a lower and upper index for each dimension
--
att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i] = array_str
--
--Specify only the upper index for each dimension
--(each lower index defaults to 1)
--
att_name[uIndex-1]..[uIndex-i] = array_str
--
--Use the upper index bounds as specified within array_str
--(each lower index defaults to 1)
--
att_name = array_str
.fi
where each
.IR lIndex
or
.IR uIndex
is an integer constant and
.IR array_str
is an array constant (see
.IR introduction (l)).
.PP
If the user does not specify any array bounds (as in the third form)
then Postgres will attempt to deduce the actual array bounds from the
contents of
.IR array_str .
If the user does specify explicit array bounds (as in the first and
second forms) then the array may be initialized partly or fully
using a C-like syntax for array initialization.
However, the uninitialized array elements will
contain garbage.
.PP
You must have write or append access to a class in order to append to
it, as well as read access on any class whose values are read in the
target list or qualification (see
.IR "change acl" (l)).
.SH EXAMPLES
.nf
--
--Make a new employee Jones work for Smith
--
insert into emp
select newemp.name, newemp.salary,
"Smith", 1990-newemp.age
from newemp
where name = "Jones"
.fi
.nf
--
--Insert into newemp class to newemp
--
insert into newemp
select * from newemp1
.fi
.nf
--
--Create an empty 3x3 gameboard for noughts-and-crosses
--(all of these queries create the same board attribute)
--
insert into tictactoe (game, board[1:3][1:3])
values(1,'{{"","",""},{},{"",""}}')
insert into tictactoe (game, board[3][3])
values (2,'{}')
insert into tictactoe (game, board)
values (3,'{{,,},{,,},{,,}}')
.fi
.SH "SEE ALSO"
create table(l),
create type(l),
update(l),
select(l)

36
doc/man/ipcclean.1 Normal file
View File

@ -0,0 +1,36 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/ipcclean.1,v 1.1.1.1 1996/08/18 22:14:24 scrappy Exp $
.TH IPCCLEAN UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
ipcclean \(em clean up shared memory and semaphores from aborted backends
.SH SYNOPSIS
.BR "ipcclean"
.SH DESCRIPTION
.IR Ipcclean
cleans up shared memory and semaphore space from aborted backends by
deleting all instances owned by user \*(lqpostgres\*(rq. Only the DBA
should execute this program as it can cause bizarre behavior (i.e.,
crashes) if run during multi-user execution. This program should be
executed if messages such as
.BR "semget: No space left on device"
are encountered when starting up the
.IR postmaster
or the backend server.
.SH BUGS
If this command is executed while a
.IR postmaster
is running, the shared memory and semaphores allocated by the
.IR postmaster
will be deleted. This will result in a general failure of the
backends servers started by that
.IR postmaster .
.PP
This script is a hack, but in the many years since it was written, no
one has come up with an equally effective and portable solution.
Suggestions are welcome.
.PP
The script makes assumption about the format of output of the
.BR ipcs
utility which may not be true across different operating systems.
Therefore, it may not work on your particular OS.

499
doc/man/large_objects.3 Normal file
View File

@ -0,0 +1,499 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /usr/local/devel/postgres/src/ref/RCS/large_objects.3pqsrc,v 1.12 1
993/08/23 09:03:16 aoki Exp $
.TH "LARGE OBJECTS" INTRO 03/18/94 Postgres95 Postgres95
.SH DESCRIPTION
.PP
In Postgres, data values are stored in tuples and individual tuples
cannot span data pages. Since the size of a data page is 8192 bytes,
the upper limit on the size of a data value is relatively low. To
support the storage of larger atomic values, Postgres provides a large
object interface. This interface provides file-oriented access to
user data that has been declared to be a large type.
.PP
This section describes the implementation and the
programmatic and query language interfaces to Postgres large object data.
.PP
.SH "Historical Note"
.SH "Historical Note"
.PP
Originally, postgres 4.2 supports three standard implementations of large
objects: as files external to Postgres, as Unix files managed by Postgres, and as
data stored within the Postgres database. It causes considerable confusion
among users. As a result, we only support large objects as data stored
within the Postgres database in Postgres. Even though is is slower to access,
it provides stricter data integrity and time travel. For historical reasons,
they are called Inversion large objects. (We will use Inversion and large
objects interchangeably to mean the same thing in this section.)
.SH "Inversion Large Objects"
.SH "Inversion Large Objects"
.PP
The Inversion large
object implementation breaks large objects up into \*(lqchunks\*(rq and
stores the chunks in tuples in the database. A B-tree index
guarantees fast searches for the correct chunk number when doing
random access reads and writes.
.SH "Large Object Interfaces"
.SH "Large Object Interfaces"
.PP
The facilities Postgres provides to access large objects, both in
the backend as part of user-defined functions or the front end
as part of an application using the \*(LQ interface, are described
below. (For users familiar with postgres 4.2, Postgres has a new set of
functions providing a more coherent interface. The interface is the same
for dynamically-loaded C functions as well as for \*(LQ.
.PP
The Postgres large object interface is modeled after the Unix file
system interface, with analogues of
.I open (2),
.I read (2),
.I write (2),
.I lseek (2),
etc. User functions call these routines to retrieve only the data of
interest from a large object. For example, if a large object type
called
.I mugshot
existed that stored photographs of faces, then a function called
.I beard
could be declared on
.I mugshot
data.
.I Beard
could look at the lower third of a photograph, and determine the color
of the beard that appeared there, if any. The entire large object
value need not be buffered, or even examined, by the
.I beard
function.
.\"As mentioned above, Postgres supports functional indices on
.\"large object data. In this example, the results of the
.\".I beard
.\"function could be stored in a B-tree index to provide fast searches
.\"for people with red beards.
.PP
Large objects may be accessed from dynamically-loaded C functions
or database client programs that link the Libpq library.
Postgres provides a set of routines that
support opening, reading, writing, closing, and seeking on large
objects.
.SH "Creating a Large Object"
.SH "Creating a Large Object"
.PP
The routine
.nf
Oid lo_creat(PGconn *conn, int mode)
.fi
creates a new large object. The
.I mode
is a bitmask describing several different attributes of the new
object. The symbolic constants listed here are defined in
.nf
/usr/local/postgres95/src/backend/libpq/libpq-fs.h
.fi
The access type (read, write, or both) is controlled by
.SM OR
ing together the bits
.SM INV_READ
and
.SM INV_WRITE .
If the large object should be archived \(em that is, if
historical versions of it should be moved periodically to a special
archive relation \(em then the
.SM INV_ARCHIVE
bit should be set. The low-order sixteen bits of
.I mask
are the storage manager number on which the large object should
reside. For sites other than Berkeley, these bits should always be
zero.
.\"At Berkeley, storage manager zero is magnetic disk, storage
.\"manager one is a Sony optical disk jukebox, and storage manager two is
.\"main memory.
.PP
The commands below create an (Inversion) large object:
.nf
inv_oid = lo_creat(INV_READ|INV_WRITE|INV_ARCHIVE);
.fi
.SH "Importing a Large Object"
.SH "Importing a Large Object"
To import a UNIX file as a large object, call
.nf
Oid
lo_import(PGconn *conn, text *filename)
.fi
The
.I filename
argument specifies the UNIX pathname of the file to be imported as
a large object.
.SH "Exporting a Large Object"
.SH "Exporting a Large Object"
To export a large object into UNIX file, call
.nf
int
lo_export(PGconn *conn, Oid lobjId, text *filename)
.fi
The
.I lobjId
argument specifies the Oid of the large object to export and
the
.I filename
argument specifies the UNIX pathname of the file.
.SH "Opening an Existing Large Object"
.SH "Opening an Existing Large Object"
.PP
To open an existing large object, call
.nf
int
lo_open(PGconn *conn, Oid lobjId, int mode, ...)
.fi
The
.I lobjId
argument specifies the Oid of the large object to open.
The mode bits control whether the object is opened for reading
.SM INV_READ ), (
writing
.SM INV_WRITE ), (
or both.
.PP
A large object cannot be opened before it is created.
.B lo_open
returns a large object descriptor for later use in
.B lo_read ,
.B lo_write ,
.B lo_lseek ,
.B lo_tell ,
and
.B lo_close .
.\"-----------
.SH "Writing Data to a Large Object"
.SH "Writing Data to a Large Object"
.PP
The routine
.nf
int
lo_write(PGconn *conn, int fd, char *buf, int len)
.fi
writes
.I len
bytes from
.I buf
to large object
.I fd .
The
.I fd
argument must have been returned by a previous
.I lo_open .
.PP
The number of bytes actually written is returned.
In the event of an error,
the return value is negative.
.SH "Seeking on a Large Object"
.SH "Seeking on a Large Object"
.PP
To change the current read or write location on a large object,
call
.nf
int
lo_lseek(PGconn *conn, int fd, int offset, int whence)
.fi
This routine moves the current location pointer for the large object
described by
.I fd
to the new location specified by
.I offset .
The valid values for .I whence are
.SM SEEK_SET
.SM SEEK_CUR
and
.SM SEEK_END.
.\"-----------
.SH "Closing a Large Object Descriptor"
.SH "Closing a Large Object Descriptor"
.PP
A large object may be closed by calling
.nf
int
lo_close(PGconn *conn, int fd)
.fi
where
.I fd
is a large object descriptor returned by
.I lo_open .
On success,
.I lo_close
returns zero. On error, the return value is negative.
.PP
.SH "Built in registered functions"
.SH "Built in registered functions"
.PP
There are two built-in registered functions,
.I lo_import
and
.I lo_export
which are convenient for use in SQL queries.
.PP
Here is an example of there use
.nf
CREATE TABLE image (
name text,
raster oid
);
INSERT INTO image (name, raster)
VALUES ('beautiful image', lo_import('/etc/motd'));
SELECT lo_export(image.raster, "/tmp/motd") from image
WHERE name = 'beautiful image';
.fi
.PP
.SH "Accessing Large Objects from LIBPQ"
.SH "Accessing Large Objects from LIBPQ"
Below is a sample program which shows how the large object interface in
\*(LP can be used. Parts of the program are commented out but are left
in the source for the readers benefit. This program can be found in
.nf
\&../src/test/examples
.fi
.PP
Frontend applications which use the large object interface in \*(LP
should include the header file
.B "libpq/libpq-fs.h"
and link with the
.B libpq
library.
.bp
.SH "Sample Program"
.SH "Sample Program"
.nf
/*-------------------------------------------------------------------------
*
* testlo.c--
* test using large objects with libpq
*
* Copyright (c) 1994, Regents of the University of California
*
*
* IDENTIFICATION
* $Header: /cvsroot/pgsql/doc/man/Attic/large_objects.3,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
*
*-------------------------------------------------------------------------
*/
#include <stdio.h>
#include "libpq-fe.h"
#include "libpq/libpq-fs.h"
#define BUFSIZE 1024
/*
* importFile -
* import file "in_filename" into database as large object "lobjOid"
*
*/
Oid importFile(PGconn *conn, char *filename)
{
Oid lobjId;
int lobj_fd;
char buf[BUFSIZE];
int nbytes, tmp;
int fd;
/*
* open the file to be read in
*/
fd = open(filename, O_RDONLY, 0666);
if (fd < 0) { /* error */
fprintf(stderr, "can't open unix file\"%s\"\n", filename);
}
/*
* create the large object
*/
lobjId = lo_creat(conn, INV_READ|INV_WRITE);
if (lobjId == 0) {
fprintf(stderr, "can't create large object");
}
lobj_fd = lo_open(conn, lobjId, INV_WRITE);
/*
* read in from the Unix file and write to the inversion file
*/
while ((nbytes = read(fd, buf, BUFSIZE)) > 0) {
tmp = lo_write(conn, lobj_fd, buf, nbytes);
if (tmp < nbytes) {
fprintf(stderr, "error while reading \"%s\"", filename);
}
}
(void) close(fd);
(void) lo_close(conn, lobj_fd);
return lobjId;
}
void pickout(PGconn *conn, Oid lobjId, int start, int len)
{
int lobj_fd;
char* buf;
int nbytes;
int nread;
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
lo_lseek(conn, lobj_fd, start, SEEK_SET);
buf = malloc(len+1);
nread = 0;
while (len - nread > 0) {
nbytes = lo_read(conn, lobj_fd, buf, len - nread);
buf[nbytes] = '\0';
fprintf(stderr,">>> %s", buf);
nread += nbytes;
}
fprintf(stderr,"\n");
lo_close(conn, lobj_fd);
}
void overwrite(PGconn *conn, Oid lobjId, int start, int len)
{
int lobj_fd;
char* buf;
int nbytes;
int nwritten;
int i;
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
lo_lseek(conn, lobj_fd, start, SEEK_SET);
buf = malloc(len+1);
for (i=0;i<len;i++)
buf[i] = 'X';
buf[i] = '\0';
nwritten = 0;
while (len - nwritten > 0) {
nbytes = lo_write(conn, lobj_fd, buf + nwritten, len - nwritten);
nwritten += nbytes;
}
fprintf(stderr,"\n");
lo_close(conn, lobj_fd);
}
/*
* exportFile -
* export large object "lobjOid" to file "out_filename"
*
*/
void exportFile(PGconn *conn, Oid lobjId, char *filename)
{
int lobj_fd;
char buf[BUFSIZE];
int nbytes, tmp;
int fd;
/*
* create an inversion "object"
*/
lobj_fd = lo_open(conn, lobjId, INV_READ);
if (lobj_fd < 0) {
fprintf(stderr,"can't open large object %d",
lobjId);
}
/*
* open the file to be written to
*/
fd = open(filename, O_CREAT|O_WRONLY, 0666);
if (fd < 0) { /* error */
fprintf(stderr, "can't open unix file\"%s\"",
filename);
}
/*
* read in from the Unix file and write to the inversion file
*/
while ((nbytes = lo_read(conn, lobj_fd, buf, BUFSIZE)) > 0) {
tmp = write(fd, buf, nbytes);
if (tmp < nbytes) {
fprintf(stderr,"error while writing \"%s\"",
filename);
}
}
(void) lo_close(conn, lobj_fd);
(void) close(fd);
return;
}
void
exit_nicely(PGconn* conn)
{
PQfinish(conn);
exit(1);
}
int
main(int argc, char **argv)
{
char *in_filename, *out_filename;
char *database;
Oid lobjOid;
PGconn *conn;
PGresult *res;
if (argc != 4) {
fprintf(stderr, "Usage: %s database_name in_filename out_filename\n",
argv[0]);
exit(1);
}
database = argv[1];
in_filename = argv[2];
out_filename = argv[3];
/*
* set up the connection
*/
conn = PQsetdb(NULL, NULL, NULL, NULL, database);
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '%s' failed.\n", database);
fprintf(stderr,"%s",PQerrorMessage(conn));
exit_nicely(conn);
}
res = PQexec(conn, "begin");
PQclear(res);
printf("importing file \"%s\" ...\n", in_filename);
/* lobjOid = importFile(conn, in_filename); */
lobjOid = lo_import(conn, in_filename);
/*
printf("\tas large object %d.\n", lobjOid);
printf("picking out bytes 1000-2000 of the large object\n");
pickout(conn, lobjOid, 1000, 1000);
printf("overwriting bytes 1000-2000 of the large object with X's\n");
overwrite(conn, lobjOid, 1000, 1000);
*/
printf("exporting large object to file \"%s\" ...\n", out_filename);
/* exportFile(conn, lobjOid, out_filename); */
lo_export(conn, lobjOid,out_filename);
res = PQexec(conn, "end");
PQclear(res);
PQfinish(conn);
exit(0);
}
.fi

962
doc/man/libpq.3 Normal file
View File

@ -0,0 +1,962 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/libpq.3,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
.TH LIBPQ INTRO 03/12/94 Postgres95 Postgres95
.SH DESCRIPTION
Libpq is the programmer's interface to Postgres. Libpq is a set of
library routines that allows queries to pass to the Postgres backend and
instances to return through an IPC channel.
.PP
This version of the documentation describes the C interface library.
Three short programs are included at the end of this section to show how
to write programs that use Libpq.
.PP
There are several examples of Libpq applications in the following
directories:
.nf
\&../src/test/regress
\&../src/test/examples
\&../src/bin/psql
.fi
.PP
Frontend programs which use Libpq must include the header file
.B "libpq-fe.h"
and must link with the
.B libpq
library.
.SH "Control and Initialization"
.PP
The following environment variables can be used to set up default
environment values to avoid hard-coding database names into
an application program:
.sp
\(bu
.B PGHOST
sets the default server name.
.sp
\(bu
.B PGOPTIONS
sets additional runtime options for the Postgres backend.
.sp
\(bu
.B PGPORT
sets the default port for communicating with the Postgres backend.
.sp
\(bu
.B PGTTY
sets the file or tty on which debugging messages from the backend server
are displayed.
.sp
\(bu
.B PGDATABASE
sets the default Postgres database name.
.sp
\(bu
.B PGREALM
sets the
.I Kerberos
realm to use with Postgres, if it is different from the local realm. If
.B PGREALM
is set, Postgres applications will attempt authentication with servers
for this realm and use separate ticket files to avoid conflicts with
local ticket files. This environment variable is only used if
.I Kerberos
authentication is enabled.
.SH "Database Connection Functions"
.PP
The following routines deal with making a connection to a backend
from a C program.
.PP
.B PQsetdb
.IP
Makes a new connection to a backend.
.nf
PGconn *PQsetdb(char *pghost,
char *pgport,
char *pgoptions,
char *pgtty,
char *dbName);
.fi
If any argument is NULL, then the corresponding environment variable
is checked. If the environment variable is also not set, then hardwired
defaults are used.
.IP
.I PQsetdb
always returns a valid PGconn pointer. The
.I PQstatus
(see below) command should be called to ensure that a connection was
properly made before queries are sent via the connection. Libpq
programmers should be careful to maintain the PGconn abstraction. Use
the accessor functions below to get at the contents of PGconn. Avoid
directly referencing the fields of the PGconn structure as they are
subject to change in the future.
.IP
.B PQdb
returns the database name of the connection.
.nf
char *PQdb(PGconn *conn)
.fi
.B PQhost
returns the host name of the connection.
.nf
char *PQhost(PGconn *conn)
.fi
.B PQoptions
returns the pgoptions used in the connection.
.nf
char *PQoptions(PGconn *conn)
.fi
.B PQport
returns the pgport of the connection.
.nf
char *PQport(PGconn *conn)
.fi
.B PQtty
returns the pgtty of the connection.
.nf
char *PQtty(PGconn *conn)
.fi
.B PQstatus
Returns the status of the connection. The status can be CONNECTION_OK or
CONNECTION_BAD.
.nf
ConnStatusType *PQstatus(PGconn *conn)
.fi
.B PQerrorMessage
returns the error message associated with the connection
.nf
char *PQerrorMessage(PGconn* conn);
.fi
.PP
.B PQfinish
.IP
Close the connection to the backend. Also frees memory used by the
PGconn structure. The PGconn pointer should not be used after PQfinish
has been called.
.nf
void PQfinish(PGconn *conn)
.fi
.PP
.B PQreset
.IP
Reset the communication port with the backend. This function will close
the IPC socket connection to the backend and attempt to reestablish a
new connection to the same backend.
.nf
void PQreset(PGconn *conn)
.fi
.PP
.B PQtrace
.IP
Enables tracing of messages passed between the frontend and the backend.
The messages are echoed to the debug_port file stream.
.nf
void PQtrace(PGconn *conn,
FILE* debug_port);
.fi
.PP
.B PQuntrace
.IP
Disables tracing of messages passed between the frontend and the backend.
.nf
void PQuntrace(PGconn *conn);
.fi
.PP
.SH "Query Execution Functions"
.PP
.B PQexec
.IP
Submit a query to Postgres. Returns a PGresult pointer if the query was
successful or a NULL otherwise. If a NULL is returned,
.I PQerrorMessage
can be used to get more information about the error.
.nf
PGresult *PQexec(PGconn *conn,
char *query);
.fi
The PGresult structure encapsulates the query result returned by the
backend. Libpq programmers should be careful to maintain the PGresult
abstraction. Use the accessor functions described below to retrieve the
results of the query. Avoid directly referencing the fields of the PGresult
structure as they are subject to change in the future.
.PP
.B PQresultStatus
.IP
Returns the result status of the query.
.I PQresultStatus
can return one of the following values:
.nf
PGRES_EMPTY_QUERY,
PGRES_COMMAND_OK, /* the query was a command */
PGRES_TUPLES_OK, /* the query successfully returned tuples */
PGRES_COPY_OUT,
PGRES_COPY_IN,
PGRES_BAD_RESPONSE, /* an unexpected response was received */
PGRES_NONFATAL_ERROR,
PGRES_FATAL_ERROR
.fi
.IP
If the result status is PGRES_TUPLES_OK, then the following routines can
be used to retrieve the tuples returned by the query.
.IP
.B PQntuples
returns the number of tuples (instances) in the query result.
.nf
int PQntuples(PGresult *res);
.fi
.B PQnfields
returns the number of fields (attributes) in the query result.
.nf
int PQnfields(PGresult *res);
.fi
.B PQfname
returns the field (attribute) name associated with the given field index.
Field indices start at 0.
.nf
char *PQfname(PGresult *res,
int field_index);
.fi
.B PQfnumber
returns the field (attribute) index associated with the given field name.
.nf
int PQfnumber(PGresult *res,
char* field_name);
.fi
.B PQftype
returns the field type associated with the given field index. The
integer returned is an internal coding of the type. Field indices start
at 0.
.nf
Oid PQftype(PGresult *res,
int field_num);
.fi
.B PQfsize
returns the size in bytes of the field associated with the given field
index. If the size returned is -1, the field is a variable length field.
Field indices start at 0.
.nf
int2 PQfsize(PGresult *res,
int field_index);
.fi
.B PQgetvalue
returns the field (attribute) value. For most queries, the value
returned by
.I PQgetvalue
is a null-terminated ASCII string representation
of the attribute value. If the query was a result of a
.B BINARY
cursor, then the value returned by
.I PQgetvalue
is the binary representation of the type in the internal format of the
backend server. It is the programmer's responsibility to cast and
convert the data to the correct C type. The value returned by
.I PQgetvalue
points to storage that is part of the PGresult structure. One must
explicitly copy the value into other storage if it is to be used past
the lifetime of the PGresult structure itself.
.nf
char* PQgetvalue(PGresult *res,
int tup_num,
int field_num);
.fi
.B PQgetlength
returns the length of a field (attribute) in bytes. If the field
is a
.I "struct varlena" ,
the length returned here does
.B not
include the size field of the varlena, i.e., it is 4 bytes less.
.nf
int PQgetlength(PGresult *res,
int tup_num,
int field_num);
.fi
.B PQgetisnull
returns the NULL status of a field.
.nf
int PQgetisnull(PGresult *res,
int tup_num,
int field_num);
.fi
.PP
.B PQcmdStatus
.IP
Returns the command status associated with the last query command.
.nf
char *PQcmdStatus(PGresult *res);
.fi
.PP
.B PQoidStatus
.IP
Returns a string with the object id of the tuple inserted if the last
query is an INSERT command. Otherwise, returns an empty string.
.nf
char* PQoidStatus(PGresult *res);
.fi
.PP
.B PQprint
.IP
+ Prints out all the tuples in an intelligent manner. The
.B psql
+ program uses this function for its output.
.nf
void PQprint(
FILE* fout, /* output stream */
PGresult* res, /* query results */
PQprintOpt *ps /* option structure */
);
.fi
.I PQprintOpt
is a typedef'ed structure as defined below.
.(C
typedef struct _PQprintOpt {
bool header; /* print table headings and row count */
bool align; /* fill align the fields */
bool standard; /* old brain dead format (needs align) */
bool html3; /* output html3+ tables */
bool expanded; /* expand tables */
bool pager; /* use pager if needed */
char *fieldSep; /* field separator */
char *caption; /* html table caption (or NULL) */
char **fieldName; /* null terminated array of field names (or NULL) */
} PQprintOpt;
.fi
.LP
.B PQclear
.IP
Frees the storage associated with the PGresult. Every query result
should be properly freed when it is no longer used. Failure to do this
will result in memory leaks in the frontend application. The PQresult*
passed in should be a value which is returned from PQexec(). Calling
PQclear() on an uninitialized PQresult pointer will very likely result
in a core dump.
.nf
void PQclear(PQresult *res);
.fi
.PP
.SH "Fast Path"
.PP
Postgres provides a
.B "fast path"
interface to send function calls to the backend. This is a trapdoor
into system internals and can be a potential security hole. Most users
will not need this feature.
.nf
PGresult* PQfn(PGconn* conn,
int fnid,
int *result_buf,
int *result_len,
int result_is_int,
PQArgBlock *args,
int nargs);
.fi
.PP
The
.I fnid
argument is the object identifier of the function to be executed.
.I result_buf
is the buffer in which to load the return value. The caller must have
allocated sufficient space to store the return value.
The result length will be returned in the storage pointed to by
.I result_len.
If the result is to be an integer value, than
.I result_is_int
should be set to 1; otherwise it should be set to 0.
.I args
and
.I nargs
specify the arguments to the function.
.nf
typedef struct {
int len;
int isint;
union {
int *ptr;
int integer;
} u;
} PQArgBlock;
.fi
.PP
.I PQfn
always returns a valid PGresult*. The resultStatus should be checked
before the result is used. The caller is responsible for freeing the
PGresult with
.I PQclear
when it is not longer needed.
.PP
.SH "Asynchronous Notification"
.PP
Postgres supports asynchronous notification via the
.I LISTEN
and
.I NOTIFY
commands. A backend registers its interest in a particular relation
with the LISTEN command. All backends listening on a particular
relation will be notified asynchronously when a NOTIFY of that relation
name is executed by another backend. No additional information is
passed from the notifier to the listener. Thus, typically, any actual
data that needs to be communicated is transferred through the relation.
.PP
Libpq applications are notified whenever a connected backend has
received an asynchronous notification. However, the communication from
the backend to the frontend is not asynchronous. Notification comes
piggy-backed on other query results. Thus, an application must submit
queries, even empty ones, in order to receive notice of backend
notification. In effect, the Libpq application must poll the backend to
see if there is any pending notification information. After the
execution of a query, a frontend may call
.I PQNotifies
to see if any notification data is available from the backend.
.PP
.B PQNotifies
.IP
returns the notification from a list of unhandled notifications from the
backend. Returns NULL if there are no pending notifications from the
backend.
.I PQNotifies
behaves like the popping of a stack. Once a notification is returned
from
.I PQnotifies,
it is considered handled and will be removed from the list of
notifications.
.nf
PGnotify* PQNotifies(PGconn *conn);
.fi
.PP
The second sample program gives an example of the use of asynchronous
notification.
.PP
.SH "Functions Associated with the COPY Command"
.PP
The
.I copy
command in Postgres has options to read from or write to the network
connection used by Libpq. Therefore, functions are necessary to
access this network connection directly so applications may take full
advantage of this capability.
.PP
.B PQgetline
.IP
Reads a newline-terminated line of characters (transmitted by the
backend server) into a buffer
.I string
of size
.I length .
Like
.I fgets (3),
this routine copies up to
.I length "-1"
characters into
.I string .
It is like
.I gets (3),
however, in that it converts the terminating newline into a null
character.
.IP
.I PQgetline
returns EOF at EOF, 0 if the entire line has been read, and 1 if the
buffer is full but the terminating newline has not yet been read.
.IP
Notice that the application must check to see if a new line consists
of the single character \*(lq.\*(rq, which indicates that the backend
server has finished sending the results of the
.I copy
command. Therefore, if the application ever expects to receive lines
that are more than
.I length "-1"
characters long, the application must be sure to check the return
value of
.I PQgetline
very carefully.
.IP
The code in
.nf
\&../src/bin/psql/psql.c
.fi
contains routines that correctly handle the copy protocol.
.nf
int PQgetline(PGconn *conn,
char *string,
int length)
.fi
.PP
.B PQputline
.IP
Sends a null-terminated
.I string
to the backend server.
.IP
The application must explicitly send the single character \*(lq.\*(rq
to indicate to the backend that it has finished sending its data.
.nf
void PQputline(PGconn *conn,
char *string);
.fi
.PP
.B PQendcopy
.IP
Syncs with the backend. This function waits until the backend has
finished the copy. It should either be issued when the
last string has been sent to the backend using
.I PQputline
or when the last string has been received from the backend using
.I PGgetline .
It must be issued or the backend may get \*(lqout of sync\*(rq with
the frontend. Upon return from this function, the backend is ready to
receive the next query.
.IP
The return value is 0 on successful completion, nonzero otherwise.
.nf
int PQendcopy(PGconn *conn);
.fi
As an example:
.nf
PQexec(conn, "create table foo (a int4, b char16, d float8)");
PQexec(conn, "copy foo from stdin");
PQputline(conn, "3<TAB>hello world<TAB>4.5\en");
PQputline(conn,"4<TAB>goodbye world<TAB>7.11\en");
\&...
PQputline(conn,".\en");
PQendcopy(conn);
.fi
.PP
.SH "LIBPQ Tracing Functions"
.PP
.B PQtrace
.IP
Enable tracing of the frontend/backend communication to a debugging file
stream.
.nf
void PQtrace(PGconn *conn
FILE *debug_port)
.fi
.PP
.B PQuntrace
.IP
Disable tracing started by
.I PQtrace
.nf
void PQuntrace(PGconn *conn)
.fi
.PP
.SH "User Authentication Functions"
.PP
If the user has generated the appropriate authentication credentials
(e.g., obtaining
.I Kerberos
tickets), the frontend/backend authentication process is handled by
.I PQexec
without any further intervention. The following routines may be
called by Libpq programs to tailor the behavior of the authentication
process.
.PP
.B fe_getauthname
.IP
Returns a pointer to static space containing whatever name the user
has authenticated. Use of this routine in place of calls to
.I getenv (3)
or
.I getpwuid (3)
by applications is highly recommended, as it is entirely possible that
the authenticated user name is
.B not
the same as value of the
.B USER
environment variable or the user's entry in
.I /etc/passwd .
.nf
char *fe_getauthname(char* errorMessage)
.fi
.PP
.B fe_setauthsvc
.IP
Specifies that Libpq should use authentication service
.I name
rather than its compiled-in default. This value is typically taken
from a command-line switch.
.nf
void fe_setauthsvc(char *name,
char* errorMessage)
.fi
Any error messages from the authentication attempts are returned in the
errorMessage argument.
.PP
.SH "BUGS"
.PP
The query buffer is 8192 bytes long, and queries over that length will
be silently truncated.
.PP
.SH "Sample Programs"
.bp
.SH "Sample Program 1"
.PP
.nf M
/*
* testlibpq.c
* Test the C version of Libpq, the Postgres frontend library.
*
*
*/
#include <stdio.h>
#include "libpq-fe.h"
void
exit_nicely(PGconn* conn)
{
PQfinish(conn);
exit(1);
}
main()
{
char *pghost, *pgport, *pgoptions, *pgtty;
char* dbName;
int nFields;
int i,j;
/* FILE *debug; */
PGconn* conn;
PGresult* res;
/* begin, by setting the parameters for a backend connection
if the parameters are null, then the system will try to use
reasonable defaults by looking up environment variables
or, failing that, using hardwired constants */
pghost = NULL; /* host name of the backend server */
pgport = NULL; /* port of the backend server */
pgoptions = NULL; /* special options to start up the backend server */
pgtty = NULL; /* debugging tty for the backend server */
dbName = "template1";
/* make a connection to the database */
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
fprintf(stderr,"%s",PQerrorMessage(conn));
exit_nicely(conn);
}
/* debug = fopen("/tmp/trace.out","w"); */
/* PQtrace(conn, debug); */
/* start a transaction block */
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
/* should PQclear PGresult whenever it is no longer needed to avoid
memory leaks */
PQclear(res);
/* fetch instances from the pg_database, the system catalog of databases*/
res = PQexec(conn,"DECLARE myportal CURSOR FOR select * from pg_database");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
PQclear(res);
res = PQexec(conn,"FETCH ALL in myportal");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
/* first, print out the attribute names */
nFields = PQnfields(res);
for (i=0; i < nFields; i++) {
printf("%-15s",PQfname(res,i));
}
printf("\n\n");
/* next, print out the instances */
for (i=0; i < PQntuples(res); i++) {
for (j=0 ; j < nFields; j++) {
printf("%-15s", PQgetvalue(res,i,j));
}
printf("\n");
}
PQclear(res);
/* close the portal */
res = PQexec(conn, "CLOSE myportal");
PQclear(res);
/* end the transaction */
res = PQexec(conn, "END");
PQclear(res);
/* close the connection to the database and cleanup */
PQfinish(conn);
/* fclose(debug); */
}
.fi
.bp
.SH "Sample Program 2"
.PP
.nf M
/*
* testlibpq2.c
* Test of the asynchronous notification interface
*
populate a database with the following:
CREATE TABLE TBL1 (i int4);
CREATE TABLE TBL2 (i int4);
CREATE RULE r1 AS ON INSERT TO TBL1 DO [INSERT INTO TBL2 values (new.i); NOTIFY TBL2];
* Then start up this program
* After the program has begun, do
INSERT INTO TBL1 values (10);
*
*
*/
#include <stdio.h>
#include "libpq-fe.h"
void exit_nicely(PGconn* conn)
{
PQfinish(conn);
exit(1);
}
main()
{
char *pghost, *pgport, *pgoptions, *pgtty;
char* dbName;
int nFields;
int i,j;
PGconn* conn;
PGresult* res;
PGnotify* notify;
/* begin, by setting the parameters for a backend connection
if the parameters are null, then the system will try to use
reasonable defaults by looking up environment variables
or, failing that, using hardwired constants */
pghost = NULL; /* host name of the backend server */
pgport = NULL; /* port of the backend server */
pgoptions = NULL; /* special options to start up the backend server */
pgtty = NULL; /* debugging tty for the backend server */
dbName = getenv("USER"); /* change this to the name of your test database*/
/* make a connection to the database */
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
fprintf(stderr,"%s",PQerrorMessage(conn));
exit_nicely(conn);
}
res = PQexec(conn, "LISTEN TBL2");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"LISTEN command failed\n");
PQclear(res);
exit_nicely(conn);
}
/* should PQclear PGresult whenever it is no longer needed to avoid
memory leaks */
PQclear(res);
while (1) {
/* async notification only come back as a result of a query*/
/* we can send empty queries */
res = PQexec(conn, " ");
/* printf("res->status = %s\n", pgresStatus[PQresultStatus(res)]); */
/* check for asynchronous returns */
notify = PQnotifies(conn);
if (notify) {
fprintf(stderr,
"ASYNC NOTIFY of '%s' from backend pid '%d' received\n",
notify->relname, notify->be_pid);
free(notify);
break;
}
PQclear(res);
}
/* close the connection to the database and cleanup */
PQfinish(conn);
}
.fi
.bp
.SH "Sample Program 3"
.PP
.nf M
/*
* testlibpq3.c
* Test the C version of Libpq, the Postgres frontend library.
* tests the binary cursor interface
*
*
*
populate a database by doing the following:
CREATE TABLE test1 (i int4, d float4, p polygon);
INSERT INTO test1 values (1, 3.567, '(3.0, 4.0, 1.0, 2.0)'::polygon);
INSERT INTO test1 values (2, 89.05, '(4.0, 3.0, 2.0, 1.0)'::polygon);
the expected output is:
tuple 0: got
i = (4 bytes) 1,
d = (4 bytes) 3.567000,
p = (4 bytes) 2 points boundbox = (hi=3.000000/4.000000, lo = 1.000000,2.000000)
tuple 1: got
i = (4 bytes) 2,
d = (4 bytes) 89.050003,
p = (4 bytes) 2 points boundbox = (hi=4.000000/3.000000, lo = 2.000000,1.000000)
*
*/
#include <stdio.h>
#include "libpq-fe.h"
#include "utils/geo-decls.h" /* for the POLYGON type */
void exit_nicely(PGconn* conn)
{
PQfinish(conn);
exit(1);
}
main()
{
char *pghost, *pgport, *pgoptions, *pgtty;
char* dbName;
int nFields;
int i,j;
int i_fnum, d_fnum, p_fnum;
PGconn* conn;
PGresult* res;
/* begin, by setting the parameters for a backend connection
if the parameters are null, then the system will try to use
reasonable defaults by looking up environment variables
or, failing that, using hardwired constants */
pghost = NULL; /* host name of the backend server */
pgport = NULL; /* port of the backend server */
pgoptions = NULL; /* special options to start up the backend server */
pgtty = NULL; /* debugging tty for the backend server */
dbName = getenv("USER"); /* change this to the name of your test database*/
/* make a connection to the database */
conn = PQsetdb(pghost, pgport, pgoptions, pgtty, dbName);
/* check to see that the backend connection was successfully made */
if (PQstatus(conn) == CONNECTION_BAD) {
fprintf(stderr,"Connection to database '%s' failed.\n", dbName);
fprintf(stderr,"%s",PQerrorMessage(conn));
exit_nicely(conn);
}
/* start a transaction block */
res = PQexec(conn,"BEGIN");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"BEGIN command failed\n");
PQclear(res);
exit_nicely(conn);
}
/* should PQclear PGresult whenever it is no longer needed to avoid
memory leaks */
PQclear(res);
/* fetch instances from the pg_database, the system catalog of databases*/
res = PQexec(conn,"DECLARE mycursor BINARY CURSOR FOR select * from test1");
if (PQresultStatus(res) != PGRES_COMMAND_OK) {
fprintf(stderr,"DECLARE CURSOR command failed\n");
PQclear(res);
exit_nicely(conn);
}
PQclear(res);
res = PQexec(conn,"FETCH ALL in mycursor");
if (PQresultStatus(res) != PGRES_TUPLES_OK) {
fprintf(stderr,"FETCH ALL command didn't return tuples properly\n");
PQclear(res);
exit_nicely(conn);
}
i_fnum = PQfnumber(res,"i");
d_fnum = PQfnumber(res,"d");
p_fnum = PQfnumber(res,"p");
for (i=0;i<3;i++) {
printf("type[%d] = %d, size[%d] = %d\n",
i, PQftype(res,i),
i, PQfsize(res,i));
}
for (i=0; i < PQntuples(res); i++) {
int *ival;
float *dval;
int plen;
POLYGON* pval;
/* we hard-wire this to the 3 fields we know about */
ival = (int*)PQgetvalue(res,i,i_fnum);
dval = (float*)PQgetvalue(res,i,d_fnum);
plen = PQgetlength(res,i,p_fnum);
/* plen doesn't include the length field so need to increment by VARHDSZ*/
pval = (POLYGON*) malloc(plen + VARHDRSZ);
pval->size = plen;
memmove((char*)&pval->npts, PQgetvalue(res,i,p_fnum), plen);
printf("tuple %d: got\n", i);
printf(" i = (%d bytes) %d,\n",
PQgetlength(res,i,i_fnum), *ival);
printf(" d = (%d bytes) %f,\n",
PQgetlength(res,i,d_fnum), *dval);
printf(" p = (%d bytes) %d points \tboundbox = (hi=%f/%f, lo = %f,%f)\n",
PQgetlength(res,i,d_fnum),
pval->npts,
pval->boundbox.xh,
pval->boundbox.yh,
pval->boundbox.xl,
pval->boundbox.yl);
}
PQclear(res);
/* close the portal */
res = PQexec(conn, "CLOSE mycursor");
PQclear(res);
/* end the transaction */
res = PQexec(conn, "END");
PQclear(res);
/* close the connection to the database and cleanup */
PQfinish(conn);
}
.fi

44
doc/man/listen.l Normal file
View File

@ -0,0 +1,44 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/listen.l,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
.TH "LISTEN" SQL 03/12/94 Postgres95 Postgres95
.SH NAME
listen \(em listen for notification on a relation
.SH SYNOPSIS
.nf
\fBlisten\fR class_name
.fi
.SH DESCRIPTION
.BR listen
is used to register the current backend as a listener on the relation
.IR class_name .
When the command
.BI notify " class_name"
is called either from within a rule or at the query level, the
frontend applications corresponding to the listening backends
are notified. When the backend process exits, this registration
is cleared.
.PP
This event notification is performed through the Libpq protocol
and frontend application interface. The application program
must explicitly poll a Libpq global variable,
.IR PQAsyncNotifyWaiting ,
and call the routine
.IR PQnotifies
in order to find out the name of the class to which a given
notification corresponds. If this code is not included in
the application, the event notification will be queued and
never be processed.
.SH "SEE ALSO"
create rule(l),
notify(l),
select(l),
libpq.
.SH BUGS
There is no way to un-\c
.BR listen
except to drop the connection (i.e., restart the backend server).
.PP
The
.IR monitor (1)
command does not poll for asynchronous events.

51
doc/man/load.l Normal file
View File

@ -0,0 +1,51 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/load.l,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
.TH LOAD SQL 01/23/93 Postgres95 Postgres95
.SH NAME
load \(em dynamically load an object file
.SH SYNOPSIS
.nf
\fBload\fR "filename"
.fi
.SH DESCRIPTION
.BR Load
loads an object (or ".o") file into Postgres's address space. Once a
file is loaded, all functions in that file can be accessed. This
function is used in support of ADT's.
.PP
If a file is not loaded using the
.BR load
command, the file will be loaded automatically the first time the
function is called by Postgres.
.BR Load
can also be used to reload an object file if it has been edited and
recompiled. Only objects created from C language files are supported
at this time.
.SH EXAMPLE
.nf
--
--Load the file /usr/postgres/demo/circle.o
--
load "/usr/postgres/demo/circle.o"
.fi
.SH CAVEATS
Functions in loaded object files should not call functions in other
object files loaded through the
.BR load
command, meaning, for example, that all functions in file A should
call each other, functions in the standard or math libraries, or in
Postgres itself. They should not call functions defined in a different
loaded file B. This is because if B is reloaded, the Postgres loader is
not \*(lqsmart\*(rq enough to relocate the calls from the functions in A into
the new address space of B. If B is not reloaded, however, there will
not be a problem.
.PP
On DECstations, you must use
.IR /bin/cc
with the \*(lq-G 0\*(rq option when compiling object files to be
loaded.
.PP
Note that if you are porting Postgres to a new platform, the
.BR load
command will have to work in order to support ADTs.

269
doc/man/monitor.1 Normal file
View File

@ -0,0 +1,269 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/monitor.1,v 1.1.1.1 1996/08/18 22:14:25 scrappy Exp $
.TH MONITOR UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
monitor \(em run the interactive terminal monitor
.SH SYNOPSIS
.BR monitor
[\c
.BR "-N"
]
[\c
.BR "-Q"
]
[\c
.BR "-T"
]
[\c
.BR "-a"
system]
[\c
.BR "-c"
query]
[\c
.BR "-d"
path]
.br
.in +5n
[\c
.BR "-h"
hostname]
[\c
.BR "-p"
port]
[\c
.BR "-q"
]
[\c
.BR "-t"
tty_device]
[dbname]
.in -5n
.SH DESCRIPTION
The interactive terminal monitor is a simple frontend to Postgres retained
for backwards compatiblity. Users are encouraged to the use the
.IR "psql"
interface instead.
.PP
.IR "monitor"
enables you to formulate, edit and review queries before issuing them
to Postgres. If changes must be made, a Unix editor may be called
to edit the
.BR "query buffer"
managed by the terminal monitor. The editor used is determined by the
value of the
.SM EDITOR
environment variable. If
.SM EDITOR
is not set, then
.BR "vi"
is used by default.
.PP
.IR "Monitor"
is a frontend application, like any other. Hence, a
.IR "postmaster"
process must be running on the database server host before
.IR "monitor"
is executed. In addition, the correct
.IR "postmaster"
port number must be specified
as described below.
.PP
The optional argument
.IR dbname
specifies the name of the database to be accessed. This database must
already have been created using
.IR createdb .
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
.IR "Monitor"
understands the following command-line options:
.TP 5n
.BR "-N"
Specifies that query results will be dumped to the screen without any
attempt at formatting. This is useful in with the
.BR -c
option in shell scripts.
.TP
.BR "-Q"
Produces extremely unverbose output.
This is useful
with the
.BR -c
option in shell scripts.
.TP
.BR "-T"
Specifies that attribute names will not be printed.
This is useful
with the
.BR -c
option in shell scripts.
.TP
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-c" " query"
Specifies that
.IR "monitor"
is to execute one query string,
.IR "query" ,
and then exit. This is useful for shell scripts, typically in
conjunction with the
.BR -N
and
.BR -T
options. Examples of shell scripts in the Postgres distribution using
.IB "monitor" " -c"
include
.IR createdb ,
.IR destroydb ,
.IR createuser ,
and
.IR destroyuser ,
.TP
.BR "-d" " path"
.IR path
specifies the path name of the file or tty to which frontend (i.e.,
.IR monitor )
debugging messages are to be written; the default is not to generate
any debugging messages.
.TP
.BR "-h" " hostname"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.TP
.BR "-q"
Specifies that the monitor should do its work quietly. By default, it
prints welcome and exit messages and the queries it sends to the
backend. If this option is used, none of this happens.
.TP
.BR "-t" " tty_device"
.IR "tty_device"
specifies the path name to the file or tty
to which backend (i.e.,
.IR postgres )
debugging messages are to be written; the default is
.IR "/dev/null" .
.TP
.BR "-s"
parses after each query (enables "single step" mode).
.TP
.BR "-S"
Turns off sending query when ";" is encountered.
.PP
You may set environment variables to avoid typing some of the above
options. See the
.SM "ENVIRONMENT VARIABLES"
section below.
.SH "MESSAGES AND PROMPTS"
The terminal monitor gives a variety of messages to keep the user
informed of the status of the monitor and the query buffer.
.PP
The terminal monitor displays two kinds of messages:
.IP go
The query buffer is empty and the terminal monitor is ready for input.
Anything typed will be added to the buffer.
.IP *
This prompt is typed at the beginning of each line when the terminal
monitor is waiting for input.
.SH "TERMINAL MONITOR COMMANDS"
.IP \ee
Enter the editor to edit the query buffer.
.IP \eg
Submit query buffer to Postgres for execution.
.IP \eh
Get on-line help.
.IP "\ei \fIfilename\fR"
Include the file
.IR filename
into the query buffer.
.IP \ep
Print the current contents of the query buffer.
.IP \eq
Exit from the terminal monitor.
.IP \er
Reset (clear) the query buffer.
.IP \es
Escape to a Unix subshell. To return to the terminal monitor, type
\*(lqexit\*(rq at the shell prompt.
.IP \et
Print the current time.
.IP "\ew \fIfilename\fR"
Store (write) the query buffer to an external file
.IR filename .
.IP \e\e
Produce a single backslash at the current location in query buffer.
.IP \e;
Produce a single semi-colon at the current location in query buffer.
.SH "ENVIRONMENT VARIABLES"
You may set any of the following environment variables to avoid
specifying command-line options:
.nf
hostname: PGHOST
port: PGPORT
tty: PGTTY
options: PGOPTION
realm: PGREALM
.fi
.PP
If
.SM PGOPTION
is specified, then the options it contains are parsed
.BR before
any command-line options.
.PP
.SM PGREALM
only applies if
.IR Kerberos
authentication is in use. If this environment variable is set, Postgres
will attempt authentication with servers for this realm and use
separate ticket files to avoid conflicts with local ticket files. See
.IR introduction (1)
for additional information on
.IR Kerberos .
.PP
See
.IR introduction (libpq)
for additional details.
.SH "RETURN VALUE"
When executed with the
.BR "-c"
option,
.IR monitor
returns 0 to the shell on successful query completion, 1 otherwise.
.SH "SEE ALSO"
introduction(libpq),
createdb(1),
createuser(1),
postgres(1),
postmaster(1).
.SH BUGS
Does not poll for asynchronous notification events generated by
.IR listen (l)
and
.IR notify (l).
.PP
Escapes (backslash characters) cannot be commented out.
.SH "SEE ALSO"
psql(1)

48
doc/man/notify.l Normal file
View File

@ -0,0 +1,48 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/notify.l,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH "NOTIFY" SQL 11/05/95 Postgres95 Postgres95
.SH NAME
notify \(em signal all frontends and backends listening on a class
.SH SYNOPSIS
.nf
\fBnotify\fR class_name
.fi
.SH DESCRIPTION
.BR notify
is used to awaken all backends and consequently all frontends
that have executed
.IR listen (l)
on
.IR class_name .
This can be used either within an instance-level rule as part of the
action body or from a normal query. When used from within a normal
query, this can be thought of as interprocess communication (IPC).
When used from within a rule, this can be thought of as an alerter
mechanism.
.PP
Notice that the mere fact that a
.BR notify
has been executed does not imply anything in particular about
the state of the class (e.g., that it has been updated), nor
does the notification protocol transmit any useful information
other than the class name. Therefore, all
.BR notify
does is indicate that some backend wishes its peers to examine
.IR class_name
in some application-specific way.
.PP
This event notification is performed through the Libpq protocol
and frontend application interface. The application program
must explicitly poll a Libpq global variable,
.IR PQAsyncNotifyWaiting ,
and call the routine
.IR PQnotifies
in order to find out the name of the class to which a given
notification corresponds. If this code is not included in
the application, the event notification will be queued and
never be processed.
.SH "SEE ALSO"
define rule(l),
listen(l),
libpq.

130
doc/man/page.5 Normal file
View File

@ -0,0 +1,130 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH PAGE FILES 01/23/93 Postgres95 Postgres95
.SH NAME
page structure \(em Postgres database file default page format
.SH DESCRIPTION
This section provides an overview of the page format used by Postgres
classes. User-defined access methods need not use this page format.
.PP
In the following explanation, a
.BR byte
is assumed to contain 8 bits. In addition, the term
.BR item
refers to data which is stored in Postgres classes.
.if t \{
Diagram 1 shows how pages in both normal Postgres classes and Postgres index
classes (e.g., a B-tree index) are structured.
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/page.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.in +0.5i
.(b M
.PS
.ps 11
box with .sw at (0.99,6.01) width 5.50 height 3.50
line from 0.988,9.012 to 6.487,9.012
line from 3.737,9.512 to 3.737,9.012
line from 5.112,9.512 to 5.112,9.012
dashwid = 0.050i
line dashed from 2.362,9.512 to 2.362,9.012
line dashed from 3.050,9.512 to 3.050,9.012
line dashed from 1.675,9.512 to 1.675,9.012
line from 3.737,6.013 to 3.737,6.513 to 6.487,6.513
line from 0.988,7.763 to 2.362,7.763 to 2.362,8.262 to 6.487,8.262
line from 0.988,7.263 to 5.112,7.263 to 5.112,7.763 to 6.487,7.763
line dashed from 2.362,7.763 to 5.112,7.763
line dashed from 5.112,8.262 to 5.112,7.763
line dashed from 4.300,8.262 to 4.300,7.763
dashwid = 0.037i
line dotted <-> from 2.425,8.325 to 6.425,8.325
line dotted <-> from 1.050,9.575 to 3.675,9.575
line dotted <-> from 3.800,9.575 to 5.050,9.575
line dotted <-> from 5.175,9.575 to 6.425,9.575
"\s10\fRitemPointerData\fP" at 2.925,7.978 ljust
"\s10\fRfiller\fP" at 4.562,7.978 ljust
"\s10\fRitemData...\fP" at 5.513,7.978 ljust
"\s10\fIUnallocated Space\fP" at 3.237,8.753 ljust
"\s10\fBItemContinuationData\fP" at 3.663,8.415 ljust
"\s10\fISpecial Space\fP" at 4.688,6.240 ljust
"\s10\fI``ItemData 2''\fP" at 2.587,7.478 ljust
"\s10\fI``ItemData 1''\fP" at 3.413,6.865 ljust
"\s10\fBItemIdData\fP" at 4.775,9.715 ljust
"\s10\fBPageHeaderData\fP" at 1.875,9.715 ljust
.PE
.ce
.BR "Diagram 1: Sample Page Layout"
.)b
.in -0.5i
\}
.\" Running
.\" .q .../bin/dumpbpages
.\" or
.\" .q .../src/support/dumpbpages
.\" as the postgres superuser
.\" with the file paths associated with
.\" (heap or B-tree index) classes,
.\" .q .../data/base/<database-name>/<class-name>,
.\" will display the page structure used by the classes.
.\" Specifying the
.\" .q -r
.\" flag will cause the classes to be
.\" treated as heap classes and for more information to be displayed.
.PP
The first 8 bytes of each page consists of a page header
.RB ( PageHeaderData ).
Within the header, the first three 2-byte integer fields,
.IR lower ,
.IR upper ,
and
.IR special ,
represent byte offsets to the start of unallocated space, to the end
of unallocated space, and to the start of \*(lqspecial space.\*(rq
Special space is a region at the end of the page which is allocated at
page initialization time and which contains information specific to an
access method. The last 2 bytes of the page header,
.IR opaque ,
encode the page size and information on the internal fragmentation of
the page. Page size is stored in each page because frames in the
buffer pool may be subdivided into equal sized pages on a frame by
frame basis within a class. The internal fragmentation information is
used to aid in determining when page reorganization should occur.
.PP
Following the page header are item identifiers
.RB ( ItemIdData ).
New item identifiers are allocated from the first four bytes of
unallocated space. Because an item identifier is never moved until it
is freed, its index may be used to indicate the location of an item on
a page. In fact, every pointer to an item
.RB ( ItemPointer )
created by Postgres consists of a frame number and an index of an item
identifier. An item identifier contains a byte-offset to the start of
an item, its length in bytes, and a set of attribute bits which affect
its interpretation.
.PP
The items, themselves, are stored in space allocated backwards from
the end of unallocated space. Usually, the items are not interpreted.
However when the item is too long to be placed on a single page or
when fragmentation of the item is desired, the item is divided and
each piece is handled as distinct items in the following manner. The
first through the next to last piece are placed in an item
continuation structure
.BR ( ItemContinuationData ).
This structure contains
.IR itemPointerData
which points to the next piece and the piece itself. The last piece
is handled normally.
.SH FILES
.TP 5n
\&.../data/...
Location of shared (global) database files.
.TP 5n
\&.../data/base/...
Location of local database files.
.SH BUGS
The page format may change in the future to provide more efficient
access to large objects.
.PP
This section contains insufficient detail to be of any assistance in
writing a new access method.

73
doc/man/pg_dump.1 Normal file
View File

@ -0,0 +1,73 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_dump.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH PG_DUMP UNIX 1/20/96 Postgres95 Postgres95
.SH NAME
pg_dump \(em dumps out a Postgres database into a script file
.SH SYNOPSIS
.BR pg_dump
[\c
.BR "-f"
filename
]
[\c
.BR "-H"
hostname
]
[\c
.BR "-p"
port]
[\c
.BR "-v"
]
[\c
.BR "-S"
help]
dbname
.in -5n
.SH DESCRIPTION
.IR "pg_dump"
is a utility for dumping out a
Postgres database into a script file containing query commands. The script
files are in a ASCII format and can be used to reconstruct the database,
even on other machines and other architectures.
.IR "pg_dump"
will produce the queries necessary to re-generate all
user-defined types, functions, tables, indices, aggregates, and
operators. In addition, all the data is copied out in ASCII format so
that it can be readily copied in again, as well, as imported into tools
for textual editing.
.PP
.IR "pg_dump"
is useful for dumping out the contents of a database to move from one
postgres95 installation to another. After running
.IR "pg_dump"
, one should examine the output script file for any warnings, especially
in light of the limitations listed below.
.SH "CAVEATS AND LIMITATIONS"
.IR pg_dump
has a few limitations.
The limitations mostly stem from
difficulty in extracting certain meta-information from the system
catalogs.
.TP
.BR "rules and views"
pg_dump does not understand user-defined rules and views and
will fail to dump them properly. (This is due to the fact that
rules are stored as plans in the catalogs and not textually)
.TP
.BR "partial indices"
pg_dump does not understand partial indices. (The reason is
the same as above. Partial index predicates are stored as plans)
.TP
.BR "large objects"
pg_dump does not handle large objects. Large objects are ignored and
must be dealt with manually.
.TP
.BR "oid preservation"
pg_dump does not preserve oid's while dumping. If you have
stored oid's explicitly in tables in user-defined attributes,
and are using them as keys, then the output scripts will not
regenerate your database correctly.
.SH "SEE ALSO"
copy(l)

43
doc/man/pg_hba.5 Normal file
View File

@ -0,0 +1,43 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/pg_hba.5,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH PG_HBA FILES 01/20/96 Postgres95 Postgres95
.SH NAME
$PGDATA/pg_hba \(em host-based access control
.SH DESCRIPTION
Postgres provides host-based access control through the file
.BR "pg_hba".
This file is stored in $PGDATA and should have proper file permissions
so that casual users cannot modify it. The file stores permissions
information about which hosts are authorized to access databases.
.PP
The file consists of lines of three columns. The first column lists the
name of the database. The second column lists the IP address of clients
machines that are authorized to connect, and the third column provides a
bit mask for the IP address. Lines which begin with '#' are considered
comments.
.PP
The keyword "all" can be used to apply to all database names. Each
column can contain strings of at most 80 characters, and each database
may have up to 255 configuration lines that apply. (80 and 255 are
constants that can be changed at Postgres compile time by altering the
#defines MAX_TOKEN and MAX_LINES in src/backend/libpq/auth.c)
.PP
Below is the default pg_hba file that is installed.
.nf
#
# Example config file for Postgres95 host based access
#
# Lines starting with "all" apply to all databases. Otherwise the first
# column has to match the name of the database being connected to. Up to
# ten config lines can apply to each database. Mask specifies bits that
# aren't counted. After those bits are taken out, the connection address
# must match the address in the middle column.
#
# <name> <address> <mask>
#
all 127.0.0.1 0.0.0.0
.fi
.SH "SEE ALSO"
introduction(1).

163
doc/man/postgres.1 Normal file
View File

@ -0,0 +1,163 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/postgres.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH POSTGRES95 UNIX 11/05/95 Postgres95 Postgres95
.SH NAME
postgres \(em the Postgres backend server
.SH SYNOPSIS
.BR "postgres"
[\c
.BR "-B"
n_buffers]
[\c
.BR "-E"
]
[\c
.BR "-P"
filedes]
[\c
.BR "-Q"
]
.br
.in +5n
[\c
.BR "-d"
debug_level]
[\c
.BR "-o"
output_file]
[\c
.BR "-s"
]
[dbname]
.in -5n
.SH DESCRIPTION
The Postgres backend server can be executed directly from the user shell.
This should be done only while debugging by the DBA, and should not be
done while other Postgres backends are being managed by a
.IR postmaster
on this set of databases.
.PP
The optional argument
.IR dbname
specifies the name of the database to be accessed.
.IR Dbname
defaults to the value of the
.SM USER
environment variable.
.PP
The
.IR postgres
server understands the following command-line options:
.TP 5n
.BR "-B" " n_buffers"
If the backend is running under the
.IR postmaster ,
.IR "n_buffers"
is the number of shared-memory buffers that the
.IR "postmaster"
has allocated for the backend server processes that it starts. If the
backend is running standalone, this specifies the number of buffers to
allocate. This value defaults to 64.
.TP
.BR "-E"
Echo all queries.
.TP
.BR "-P" " filedes"
.IR "filedes"
specifies the file descriptor that corresponds to the socket (port) on
which to communicate to the frontend process. This option is
.BR not
useful for interactive use.
.TP
.BR "-Q"
Specifies \*(lqquiet\*(rq mode.
.TP
.BR "-d" " debug_level"
Turns on debugging at the numeric level
.IR "debug_level" .
Turning on debugging will cause query parse trees and query plans to
be displayed.
.TP
.BR "-o" " output_file"
Sends all debugging and error output to
.IR output_file .
If the backend is running under the
.IR postmaster ,
error messages are still sent to the frontend process as well as to
.IR output_file ,
but debugging output is sent to the controlling tty of the
.IR postmaster
(since only one file descriptor can be sent to an actual file).
.TP
.BR "-s"
Print time information and other statistics at the end of each query.
This is useful for benchmarking or for use in tuning the number of
buffers.
.SH "DEPRECATED COMMAND OPTIONS"
There are several other options that may be specified, used mainly
for debugging purposes. These are listed here only for the use by
Postgres system developers.
.BR "Use of any of these options is highly discouraged" .
Furthermore, any of these options may disappear or change at any time.
.TP
.BR "-A" "n|r|b|Q\fIn\fP|X\fIn\fP"
.IP
This option generates a tremendous amount of output.
.TP
.BR "-L"
Turns off the locking system.
.TP
.BR "-N"
Disables use of newline as a query delimiter.
.TP
.BR "-S"
Indicates that the transaction system can run with the assumption of
stable main memory, thereby avoiding the necessary flushing of data
and log pages to disk at the end of each transaction system. This is
only used for performance comparisons for stable vs. non-stable
storage. Do not use this in other cases, as recovery after a system
crash may be impossible when this option is specified in the absence
of stable main memory.
.TP
.BR "-b"
Enables generation of bushy query plan trees (as opposed to left-deep
query plans trees). These query plans are not intended for actual
execution; in addition, this flag often causes Postgres to run out of
memory.
.TP
.BR "-f"
Forbids the use of particular scan and join methods:
.IR s " and " i
disable sequential and index scans respectively, while
.IR n ", " m " and " h
disable nested-loop, merge and hash joins respectively.
This is another feature that may not necessarily produce executable
plans.
.TP
.BR "-p"
Indicates to the backend server that it has been started by a
.IR postmaster
and make different assumptions about buffer pool management, file
descriptors, etc.
.TP
.BR "-t" "pa[rser]|pl[anner]|e[xecutor]"
Print timing statistics for each query relating to each of the major
system modules. This option cannot be used with
.BR "-s" .
.SH "SEE ALSO"
ipcclean(1),
psql(1),
postmaster(1).
.SH "DIAGNOSTICS"
Of the nigh-infinite number of error messages you may see when you
execute the backend server directly, the most common will probably be:
.TP
.BR "semget: No space left on device"
If you see this message, you should run the
.IR ipcclean
command. After doing this, try starting
.IR postgres
again. If this still doesn't work, you probably need to configure
your kernel for shared memory and semaphores as described in the
installation notes.

323
doc/man/postmaster.1 Normal file
View File

@ -0,0 +1,323 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/postmaster.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH POSTMASTER UNIX 11/05/95 Postgres95 Postgres95
.SH "NAME"
postmaster \(em run the Postgres postmaster
.SH "SYNOPSIS"
.BR "postmaster"
[\c
.BR "-B"
n_buffers]
[\c
.BR "-D"
data_dir]
[\c
.BR "-S" \c
]
[\c
.BR "-a"
system]
.br
.in +5n
[\c
.BR "-b"
backend_pathname]
[\c
.BR "-d"
[debug_level]]
[\c
.BR "-n" \c
]
.br
[\c
.BR "-o"
backend_options]
[\c
.BR "-p"
port]
[\c
.BR "-s" \c
]
.in -5n
.SH "DESCRIPTION"
The
.IR "postmaster"
manages the communication between frontend and backend processes, as
well as allocating the shared buffer pool and semaphores (on machines
without a test-and-set instruction). The
.IR postmaster
does not itself interact with the user and should be started as a
background process.
.BR "Only one postmaster should be run on a machine."
.PP
The
.IR "postmaster"
understands the following command-line options:
.TP 5n
.BR "-B" " n_buffers"
.IR "n_buffers"
is the number of shared-memory buffers for the
.IR "postmaster"
to allocate and manage for the backend server processes that it
starts. This value defaults to 64.
.TP
.BR "-D" " data_dir"
Specifies the directory to use as the root of the tree of database
directories. This directory uses the value of the environment
variable
.SM PGDATA.
If
.SM PGDATA
is not set, then the directory used is
.SM $POSTGRESHOME\c
/data. If neither environment variable is set and this command-line
option is not specified, the default directory that was
set at compile-time is used.
.TP
.BR "-S"
Specifies that the
.IR "postmaster"
process should start up in silent mode. That is, it will disassociate
from the user's (controlling) tty and start its own process group.
This should not be used in combination with debugging options because
any messages printed to standard output and standard error are
discarded.
.TP
.BR "-a" " system"
Specifies whether or not to use the authentication system
.IR "system"
(see
.IR introduction (1))
for frontend applications to use in connecting to the
.IR postmaster
process. Specify
.IR "system"
to enable a system, or
.BI "no" "system"
to disable a system. For example, to permit users to use
.IR Kerberos
authentication, use
.BR "-a kerberos" ;
to deny any unauthenticated
connections, use
.BR "-a nounauth .
The default is site-specific.
.TP
.BR "-b" " backend_pathname"
.IR "backend_pathname"
is the full pathname of the Postgres backend server executable file that
the
.IR "postmaster"
will invoke when it receives a connection from a frontend application.
If this option is not used, then the
.IR postmaster
tries to find this executable file in the directory in which its own
executable is located (this is done by looking at the pathname under
which the
.IR "postmaster"
was invoked. If no pathname was specified, then the
.SM PATH
environment variable is searched for an executable named
\*(lqpostgres\*(rq).
.TP
.BR "-d" " [debug_level]"
The optional argument
.IR debug_level
determines the amount of debugging output the backend servers will
produce.
If
.I debug_level
is one, the postmaster will trace all connection traffic,
and nothing else.
For levels two and higher,
debugging is turned on in the backend process and the postmaster
displays more information,
including the backend environment and process traffic.
Note that if no file is specified for backend servers to
send their debugging output then this output will appear on the
controlling tty of their parent
.IR postmaster .
.TP
.BR "-n" ", " "-s"
The
.IR "-s" " and " "-n"
options control the behavior of the
.IR "postmaster"
when a backend dies abnormally. \fBNeither option is intended for use in
ordinary operation\fP.
.IP
The ordinary strategy for this situation is to notify all other
backends that they must terminate and then reinitialize the shared
memory and semaphores. This is because an errant backend could have
corrupted some shared state before terminating.
.IP
If the
.IR "-s"
option is supplied, then the
.IR "postmaster"
will stop all other backend processes by sending the signal
.SM SIGSTOP,
but will not cause them to terminate. This permits system programmers
to collect core dumps from all backend processes by hand.
.IP
If the
.IR "-n"
option is supplied, then the
.IR "postmaster"
does not reinitialize shared data structures. A knowledgable system
programmer can then use the
.IR shmemdoc
program to examine shared memory and semaphore state.
.TP
.BR "-o" " backend_options"
The
.IR postgres (1)
options specified in
.IR "backend_options"
are passed to all backend server processes started by this
.IR postmaster .
If the option string contains any spaces, the entire string must be
quoted.
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is to listen for connections from frontend applications. Defaults to
5432, or the value of the
.SM PGPORT
environment variable (if set). If you specify a port other than the
default port then all frontend application users must specify the same
port (using command-line options or
.SM PGPORT\c
) when starting any libpq application, including psql.
.SH "WARNINGS"
If at all possible,
.BR "do not"
use
.SM SIGKILL
when killing the
.IR "postmaster" "."
.SM SIGHUP,
.SM SIGINT,
or
.SM SIGTERM
(the default signal for
.IR "kill" "(1))"
should be used instead. Hence, avoid
.nf
kill -KILL
.fi
or its alternative form
.nf
kill -9
.fi
as this will prevent the
.IR postmaster
from freeing the system resources (e.g., shared memory and semaphores)
that it holds before dying. This prevents you from having to deal with
the problem with
.IR shmat (2)
described below.
.SH "EXAMPLES"
.nf
# start postmaster using default values
postmaster -S
.fi
This command will start up
.IR "postmaster"
on the default port (5432) and will search
.SM $PATH
to find an executable file called \*(lqpostgres\*(rq. This is the
simplest and most common way to start the
.IR "postmaster" .
.nf
# start with specific port and executable name
postmaster -p -b /usr/postgres/bin/postgres &
.fi
This command will start up a
.IR "postmaster"
communicating through the port 1234, and will attempt to use the
backend located at \*(lq/usr/postgres/bin/postgres\*(rq. In order to
connect to this
.IR "postmaster"
using psql, you would need to either
specify
.BR "-p 1234"
on the
.IR "psql"
command-line or set the environment variable
.SM PGPORT
to 1234.
.SH "SEE ALSO"
ipcs(1),
ipcrm(1),
ipcclean(1),
psql(1),
postgres(1),
.SH "DIAGNOSTICS"
.TP
.BR "FindBackend: could not find a backend to execute..."
If you see this message, you do not have the
.IR "postgres"
executable in your path. Add the directoy in which postgres resides to
your path.
.TP
.BR "semget: No space left on device"
If you see this message, you should run the
.IR "ipcclean"
command. After doing this, try starting the
.IR "postmaster"
again. If this still doesn't work, you probably need to configure
your kernel for shared memory and semaphores as described in the
installation notes. If you run multiple
.IR postmaster s
on a single host, or have reduced the shared memory and semaphore
parameters from the defaults in the generic kernel, you may have to
go back and increase the shared memory and semaphores configured
into your kernel.
.TP
.BR "StreamServerPort: cannot bind to port"
If you see this message, you should be certain that there is no other
.IR "postmaster"
process already running. The easiest way to determine this is by
using the command
.nf
ps -ax | grep postmaster
.fi
on BSD-based systems
.nf
ps -e | grep postmast
.fi
(the equivalent syntax is on System V-like or POSIX-compliant systems such as HP-UX). If you
are sure that no other
.IR "postmaster"
processes are running and you still get this error, try specifying a
different port using the
.BR "-p"
option. You may also get this error if you terminate the
.IR "postmaster"
and immediately restart it using the same port; in this case, you must
simply wait a few seconds until the operating system closes the port
before trying again. Finally, you may get this error if you specify
a port number that your operating system considers to be reserved.
For example, many versions of Unix consider port numbers under 1024 to
be \*(lqtrusted\*(rq and only permit the Unix superuser to access them.
.TP
.BR "IpcMemoryAttach: shmat() failed: Permission denied"
A likely explanation is that another user attempted to start a
.IR "postmaster"
process on the same port which acquired shared resources and then
died. Since Postgres shared memory keys are based on the port number
assigned to the
.IR "postmaster" ,
such conflicts are likely if there is more than one installation on
a single host. If there are no other
.IR "postmaster"
processes currently running (see above), run
.IR "ipcclean"
and try again. If other
.IR "postmaster" s
are running, you will have to find the owners of those processes to
coordinate the assignment of port numbers and/or removal of unused
shared memory segments.

359
doc/man/psql.1 Normal file
View File

@ -0,0 +1,359 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/psql.1,v 1.1.1.1 1996/08/18 22:14:26 scrappy Exp $
.TH PSQL UNIX 1/20/96 Postgres95 Postgres95
.SH NAME
psql \(em run the interactive query front-end
.SH SYNOPSIS
.BR psql
[\c
.BR "-a"
authsvc
]
[\c
.BR "-A"
]
[\c
.BR "-c"
query
]
[\c
.BR "-d"
dbName]
[\c
.BR "-e"
]
[\c
.BR "-f"
filename]
[\c
.BR "-h"
hostname]
[\c
.BR "-H"
]
[\c
.BR "-l"
port]
[\c
.BR "-n"
]
[\c
.BR "-o"
filename
]
[\c
.BR "-p"
port]
[\c
.BR "-q"
]
[\c
.BR "-s"
]
[\c
.BR "-S"
]
[\c
.BR "-t"
]
[\c
.BR "-x"
]
[dbname]
.in -5n
.SH DESCRIPTION
psql is a interactive query front-end to Postgres. It enables you to
type in queries interactively, issue them to Postgres, and see the query
results.
.IR psql
can be used in a pipe sequence, and automatically detects when it
is not listening or talking to a real tty.
.IR psql
is designed to be an enhanced version of the older
.IR "monitor"
program.
.PP
.IR "psql"
is a frontend application, like any other. Hence, a
.IR "postmaster"
process must be running on the database server host before
.IR "psql"
is executed. In addition, the correct
.IR "postmaster"
port number must be specified
as described below.
.PP
The optional argument
.IR dbname
specifies the name of the database to be accessed. This database must
already have been created.
.IR dbname
defaults to the value of the
.SM USER
environment variable or, if that's not set, to the Unix account name of the
current user.
.PP
.IR "psql"
understands the following command-line options:
.TP
.BR "-a" " system"
Specifies an authentication system
.IR "system"
(see
.IR introduction (1))
to use in connecting to the
.IR postmaster
process. The default is site-specific.
.TP
.BR "-A"
Turn off fill justification when printing out attributes.
.TP
.BR "-c" " query"
Specifies that
.IR "psql"
is to execute one query string,
.IR "query" ,
and then exit. This is useful for shell scripts, typically in
conjunction with the
.BR -q ""
options.
.BR -c
option in shell scripts.
.TP
.BR "-d" " dbName"
Specifies the name of the database to connect to.
.TP
.BR "-e" " "
Echo the query sent to the backend
.TP
.BR "-f" " filename"
Use the file
.IR "filename"
as the source of queries instead of reading queries interactively.
.TP
.BR "-h" " hostname"
Specifies the hostname of the machine on which the
.IR postmaster
is running. Defaults to the name of the local host, or the value of
the
.SM PGHOST
environment variable (if set).
.TP
.BR "-H"
Turns on
.SM HTML3.0
tabular output.
.TP
.BR "-l"
Lists all available databases
.TP
.BR "-n"
Do not use the readline library for input line editing and command history.
.TP
.BR "-p" " port"
Specifies the Internet TCP port on which the
.IR postmaster
is listening for connections. Defaults to 5432, or the value of the
.SM PGPORT
environment variable (if set).
.TP
.BR "-q"
Specifies that
.IR psql
should do its work quietly. By default, it
prints welcome and exit messages and prompts for each query, and prints
out the number of rows returned from a query.
If this option is used, none of this happens. This is useful with the
.BR -c
option in shell scripts.
.TP
.BR "-s"
Run in single-step mode where the user at prompted for each query before
it is sent to the backend.
.TP
.BR "-S"
Run ins single-line mode where each query is terminated by a newline,
instead of a semicolon.
.TP
.BR "-t"
Turn off printing of attributes names.
This is useful with the
.BR -c
option in shell scripts.
.TP
.BR "-x"
Turns on extended field mode. When enabled each tuple will have its field
names printed on the left with the field values printed on the right.
This is useful for tuples which are otherwise too long to fit into
one screen line. HTML tuple output supports this mode also.
.PP
You may set environment variables to avoid typing some of the above
options. See the
.SM "ENVIRONMENT VARIABLES"
section below.
.SH "CONNECTING TO A DATABASE"
.IR psql
attempts to make a connection to the database at the hostname and
port number specified on the command line. If the connection could not
be made for any reason (e.g. insufficient privileges, postmaster is not
running on the server, etc)
.IR psql
will return an error that says
.nf
Connection to database failed.
.fi
The reason for the connection failure is not provided.
.SH "ENTERING QUERIES"
In normal operation, psql provides a prompt with the name of the
database that psql is current connected to followed by the string "=>".
For example,
.nf
Welcome to the POSTGRES95 interactive sql monitor:
Please read the file COPYRIGHT for copyright terms of POSTGRES95
type \e? for help on slash commands
type \eq to quit
type \eg or terminate with semicolon to execute query
You are currently connected to the database: testdb
testdb=>
.fi
.PP
At the prompt, the user may type in SQL queries. Unless the -S option
is set, input lines are sent to the backend when a query-terminating
semicolon is reached.
.PP
Whenever a query is executed, psql also polls for asynchronous notification
events generated by
.IR listen (l)
and
.IR notify (l).
.PP
.SH "PSQL COMMANDS"
.IP "\ea"
Toggle field alignment when printing out attributes.
.IP "\eC \fIcaption\fR"
Set the HTML3.0 table caption.
.IP "\ec \fIdbname\fR"
Establish a connection to a new database. The previous connection is closed.
.IP "\ed [\fItable\fR]"
List tables in the database, or if
.IR table
is specified, list the columns in
.IR table.
If table name is
.IR *,
list all tables and column information for each tables.
.IP "\ee [\fIfilename\fR]"
Edit the current query buffer or \fIfile\fR.
.IP "\eE [\fIfilename\fR]"
Edit the current query buffer or \fIfile\fR and execute it
upon editor exit.
.IP "\ef [\fIseparator\fR]"
Set the field separator. Default is a single blank space.
.IP "\eg [\fI|command\fR] | [\fIfilename\fR]"
Send the current query input buffer to the backend and optionally
save the output in
.IR filename
or pipe the output into
.IR "|command".
.IP "\eh [\fIcommand\fR]"
Give syntax help on the specified SQL command. If the
.IR command
is not specified, list all the commands for which syntax help is
available. If the
.IR command
is
.IR *,
give syntax help on all SQL commands.
.IP "\eH"
Toggle html3 output.
.IP "\ei \fIfilename\fR"
Read queries from
.IR filename
into the query input buffer.
.IP "\el"
List all the databases in the server.
.IP "\em"
Toggle monitor-like table display.
This is standard SQL output (i.e extra border characters).
.IP "\eo [\fI|command\fR] | [\fIfilename\fR]"
Send query results to
.IR filename .
Or pipe into
.IR command .
If no arguments are specified, send query results to
.IR stdout .
.IP "\ep"
Print the current query buffer.
.IP \eq
Quit the psql program.
.IP "\er"
Reset(clear) the query buffer.
.IP "\es [\fIfilename\fR]"
Print or save the command line history to \fIfilename\fR. (Only available if psql is
configured to use readline)
.IP "\et"
Toggle display of output attribute name headings and row count (defaults to on).
.IP "\eT"
Set html3.0 <table ...> options.
.IP "\ex"
Toggles extended field mode. When enabled each tuple will have its field
names printed on the left with the field values printed on the right.
This is useful for tuples which are otherwise too long to fit into
one screen line. HTML tuple output mode supports this flag too.
.IP "\e! [\fIcommand\fR]"
Escape to shell or execute
.IR command.
.IP \e?
Get help information about the \e commands.
.SH "ENVIRONMENT VARIABLES"
You may set any of the following environment variables to avoid
specifying command-line options:
.nf
hostname: PGHOST
port: PGPORT
tty: PGTTY
options: PGOPTION
realm: PGREALM
.fi
.PP
If
.SM PGOPTION
is specified, then the options it contains are parsed
.BR before
any command-line options.
.PP
.SM PGREALM
only applies if
.IR Kerberos
authentication is in use. If this environment variable is set, Postgres
will attempt authentication with servers for this realm and use
separate ticket files to avoid conflicts with local ticket files. See
.IR introduction (1)
for additional information on
.IR Kerberos .
.PP
See
.IR introduction (libpq)
for additional details.
.SH "RETURN VALUE"
When executed with the
.BR "-c"
option,
.IR psql
returns 0 to the shell on successful query completion, 1 otherwise.
.IR psql
will also return 1 if the connection to a database could not be made for
any reason.
.SH "SEE ALSO"
introduction(libpq),
monitor(1)
postgres(1),
postmaster(1).
.SH BUGS
If multiple queries are sent to the backend at once without semicolon
termination after each query, psql gets confused about the query
results. The queries will still be processed correctly by the backend.

61
doc/man/purge.l Normal file
View File

@ -0,0 +1,61 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.TH PURGE SQL 11/05/95 Postgres95 Postgres95
.SH NAME
purge \(em discard historical data
.SH SYNOPSIS
.nf
\fBpurge\fR classname [ \fBbefore\fR abstime ] [ \fBafter\fR reltime ]
.fi
.SH DESCRIPTION
.BR Purge
allows a user to specify the historical retention properties of a
class. If the date specified is an absolute time such as \*(lqJan 1
1987\*(rq, Postgres will discard tuples whose validity expired before
the indicated time.
.BR Purge
with no
.IR before
clause is equivalent to \*(lqpurge before now\*(rq. Until specified
with a purge command, instance preservation defaults to
\*(lqforever\*(rq.
.PP
The user may purge a class at any time as long as the purge date never
decreases. Postgres will enforce this restriction, silently.
.PP
Note that the
.BR purge
command does not do anything except set a parameter for system
operation. Use
.IR vacuum (l)
to enforce this parameter.
.SH EXAMPLE
.nf
--
--Always discard data in the EMP class
--prior to January 1, 1989
--
purge EMP before "Jan 1 1989"
.fi
.nf
--
--Retain only the current data in EMP
--
purge EMP
.fi
.SH "SEE ALSO"
vacuum(l).
.SH "BUGS AND CAVEATS"
Error messages are quite unhelpful. A complaint about
\*(lqinconsistent times\*(rq followed by several nine-digit numbers
indicates an attempt to \*(lqback up\*(rq a purge date on a relation.
.PP
You cannot purge certain system catalogs (namely, \*(lqpg_class\*(rq,
\*(lqpg_attribute\*(rq, \*(lqpg_am\*(rq, and \*(lqpg_amop\*(rq) due
to circularities in the system catalog code.
.PP
This definition of the
.BR purge
command is really only useful for non-archived relations, since
tuples will not be discarded from archive relations (they are
never vacuumed).

23
doc/man/remove_view.l Normal file
View File

@ -0,0 +1,23 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/remove_view.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
.TH "DROP VIEW" SQL 04/25/94 Postgres95 Postgres95
.SH NAME
drop view \(em removes a view from Postgres
.SH SYNOPSIS
.nf
\fBdrop view\fR view_name
.fi
.SH DESCRIPTION
This command drops an existing view from the Postgres system. To
execute this command you must be the owner of the view.
.SH EXAMPLE
.nf
/*
* this command will remove the "myview" view
*/
drop view myview
.fi
.SH "SEE ALSO"
create view(l),
drop rule(l),

63
doc/man/rename.l Normal file
View File

@ -0,0 +1,63 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/rename.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
.TH RENAME SQL 02/08/94 Postgres95 Postgres95
.SH NAME
rename \(em rename a class or an attribute in a class
.SH SYNOPSIS
.nf
\fBalter table\fR classname1
\fBrename to\fR classname2
\fBalter table\fR classname1 [\fB*\fR]
\fBrename [column]\fR attname1 \fBto\fR attname2
.fi
.SH DESCRIPTION
The
.BR rename
command
causes the name of a class or attribute to change without changing any
of the data contained in the affected class. Thus, the class or
attribute will remain of the same type and size after this command is
executed.
.PP
In order to rename an attribute in each class in an entire inheritance
hierarchy, use the
.IR classname
of the superclass and append a \*(lq*\*(rq. (By default, the attribute
will not be renamed in any of the subclasses.) This should
.BR always
be done when changing an attribute name in a superclass. If it is
not, queries on the inheritance hierarchy such as
.nf
select * from super* s
.fi
will not work because the subclasses will be (in effect) missing an
attribute found in the superclass.
.PP
You must own the class being modified in order to rename it or part of
its schema. Renaming any part of the schema of a system catalog is
not permitted.
.SH EXAMPLE
.nf
--
-- change the emp class to personnel
--
alter table emp rename to personnel
.fi
.nf
--
-- change the sports attribute to hobbies
--
alter table emp rename column sports to hobbies
.fi
.nf
--
-- make a change to an inherited attribute
--
alter table person * rename column last_name to family_name
.fi
.SH BUGS
Execution of historical queries using classes and attributes whose
names have changed will produce incorrect results in many situations.
.PP
Renaming of types, operators, rules, etc., should also be supported.

29
doc/man/revoke.l Normal file
View File

@ -0,0 +1,29 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/revoke.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
.TH REVOKE SQL 11/05/95 Postgres95 Postgres95
.SH NAME
revoke \(em revoke access privileges
.SH SYNOPSIS
.nf
\fBrevoke\fR <privilege[,privilege,...]>
\fBon\fR <rel1>[,...<reln>]
\fBfrom\fR [\fBpublic\fR | group <group> | <username>]
\fBprivilege\fR is {\fBALL\fR | \fBSELECT\fR | \fBINSERT\fR | \fBUPDATE\fR | \fBDELETE\fR | \fBRULE\fR}
.fi
.SH DESCRIPTION
.PP
.B revoke
allows you to revoke privileges given to all users or certain users or groups.
.SH EXAMPLES
.nf
--
--Example of a revoke
--
revoke insert
on mytab
from public
.fi
.SH "SEE ALSO"
grant(l)

24
doc/man/rollback.l Normal file
View File

@ -0,0 +1,24 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/rollback.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
.TH ROLLBACK SQL 01/20/96 Postgres95 Postgres95
.\" XXX This .XA has to go after the .TH so that the index page number goes
.\" in the right place...
.SH NAME
rollback \(em rollback, e.g. aborts, the current transaction
.SH SYNOPSIS
.nf
\fBrollback\fP \fB[transaction|work]\fR
.fi
.SH DESCRIPTION
This command rolls back the current transaction and causes all the
updates made by the transaction to be discarded.
.PP
.IR "rollback"
is functionally equivalent to the
.IR "abort"
command.
.SH "SEE ALSO"
abort(l),
begin(l),
end(l).

133
doc/man/select.l Normal file
View File

@ -0,0 +1,133 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/select.l,v 1.1.1.1 1996/08/18 22:14:27 scrappy Exp $
.TH SELECT SQL 11/05/95 Postgres95 Postgres95
.SH NAME
select \(em retrieve instances from a class
.SH SYNOPSIS
.nf
\fBselect\fR [distinct]
expression1 [\fBas\fR attr_name-1]
{, expression-1 [\fBas\fR attr_name-i]}
[\fBinto\fR \fBtable\fR classname]
[\fBfrom\fR from-last]
[\fBwhere\fR where-clause]
[\fBgroup by\fR attr_name1 {, attr_name-i....}
[\fBorder by\fR attr_name1
[\fBusing op1\fR] {, attr_namei [\fBusing opi\fR] }
.fi
.SH DESCRIPTION
.BR Select
will get all instances which satisfy the qualification,
.IR qual ,
compute the value of each element in the target list, and either (1)
return them to an application program through one of two different
kinds of portals or (2) store them in a new class.
.PP
If
into table class name
is specified, the result of the query will be stored in a new class
with the indicated name.
.PP
The
.BR "order by"
clause allows a user to specify that he wishes the instances sorted
according to the corresponding operator. This operator must be a
binary one returning a boolean. Multiple sort fields are allowed and
are applied from left to right.
.PP
The target list specifies the fields to be retrieved. Each
.IR attr_name
specifies the desired attribute or portion of an array attribute.
Thus, each
.IR attr_name
takes the form
.nf
class_name.att_name
.fi
or, if the user only desires part of an array,
.nf
--
--Specify a lower and upper index for each dimension
--(i.e., clip a range of array elements)
--
class_name.att_name[lIndex-1:uIndex-1]..[lIndex-i:uIndex-i]
--
--Specify an exact array element
--
class_name.att_name[uIndex-1]..[uIndex-i]
.fi
where each
.IR lIndex
or
.IR uIndex
is an integer constant.
.PP
When you retrieve an attribute which is of a complex type, the behavior
of the system depends on whether you used "nested dots" to project
out attributes of the complex type or not. See the examples below.
.PP
You must have read access to a class to read its values (see
.IR "grant/revoke" (l).
.SH EXAMPLES
.nf
--
--Find all employees who make more than their manager
--
select e.name
from emp e, emp m
where e.mgr = m.name
and e.sal > m.sal
.fi
.nf
--
--Retrieve all fields for those employees who make
--more than the average salary
--
select avg(sal) as ave
into table avgsal from emp;
.fi
.nf
--
--Retrieve all employee names in sorted order
--
select distinct name
from emp
order by name using <
.fi
.nf
--
--Retrieve all employee names that were valid on 1/7/85
--in sorted order
--
selec name
from emp['January 7 1985'] e
order by name using <
.fi
.nf
--
--Construct a new class, raise, containing 1.1
--times all employee's salaries
--
select 1.1 * emp.salary as salary
into tables raise
from emp
.fi
.SH "SEE ALSO"
insert(l),
close(l),
create table(l),
fetch(l),
update(l).
.SH BUGS
.BR "Select into"
does not delete duplicates.
.PP
If the backend crashes in the course of executing a
.BR "select into" ,
the class file will remain on disk. It can be safely removed by the
database DBA, but a subsequent
.BR "select into"
to the same name will fail with a cryptic error message about
\*(lqBlockExtend\*(rq.

349
doc/man/sql.l Normal file
View File

@ -0,0 +1,349 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/sql.l,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
.TH INTRODUCTION SQL 11/5/95 Postgres95 Postgres95
.SH "Section 4 \(em SQL Commands (COMMANDS)"
.SH "General Information"
.SH DESCRIPTION
The following is a description of the general syntax of SQL.
Individual SQL statements and commands are treated separately in the
document; this section describes the syntactic classes from which the
constituent parts of SQL statements are drawn.
.SH Comments
A
.IR comment
is an arbitrary sequence of characters following double dashes up to the end
of the line e.g:
.nf
-- This is a comment
.fi
.SH "Names"
.IR Names
in SQL are sequences of not more than NAMEDATALEN alphanumeric characters,
starting with an alphabetic character. By default, NAMEDATALEN is set
to 16, but at the time the system is built, NAMEDATALEN can be changed
by changing the #ifdef in src/backend/include/postgres.h. Underscore
(\*(lq_\*(rq) is considered an alphabetic character.
.SH "Keywords"
The following identifiers are reserved for use as
.IR keywords
and may not be used otherwise:
.PP
.ft B
.nf
.if n .ta 5 +15 +15 +15
.if t .ta 0.5i +1.5i +1.5i +1.5i
.fi
.ft
.ft B
.nf
.if n .ta 5 +15 +15 +15
.if t .ta 0.5i +1.5i +1.5i +1.5i
.fi
.ft
.PP
In addition, all Postgres classes have several predefined attributes used
by the system.
.SH "Constants"
There are six types of
.IR constants
for use in SQL. They are described below.
.SH "String Constants"
.IR Strings
in SQL are arbitrary sequences of ASCII characters bounded by single
quotes (' '). Uppercase alphabetics within strings are accepted
literally. Non-printing characters may be embedded within strings by
prepending them with a backslash, e.g., `\en'. Also, in order to embed
quotes within strings, it is necessary to prefix them with `\e' . The
same convention applies to `\e' itself. Because of the limitations on
instance sizes, string constants are currently limited to a length of
a little less than 8192 bytes. Larger objects may be created using the
Postgres Large Object interface.
.SH "Integer Constants"
.IR "Integer constants"
in SQL are collection of ASCII digits with no decimal point. Legal
values range from \(mi2147483647 to +2147483647. This will vary
depending on the operating system and host machine.
.SH "Floating Point Constants"
.IR "Floating point constants"
consist of an integer part, a decimal point, and a fraction part or
scientific notation of the following format:
.nf
{<dig>} .{<dig>} [e [+-] {<dig>}]
.fi
Where <dig> is a digit. You must include at least one <dig> after the
period and after the [+-] if you use those options. An exponent with
a missing mantissa has a mantissa of 1 inserted. There may be no
extra characters embedded in the string.
Floating point constaints are of type float4.
.SH "Constants of Postgres User-Defined Types"
A constant of an
.IR arbitrary
type can be entered using the notation:
.nf
'string'::type-name
.fi
or
.nf
CAST 'string' AS type-name
.fi
The value inside the string is passed to the input
conversion routine for the type called type-name. The result is a
constant of the indicated type. The explicit typecast may be omitted
if there is no ambiguity as to the type the constant must be, in which
case it is automatically coerced.
.SH "Array constants"
.IR "Array constants"
are arrays of any Postgres type, including other arrays, string
constants, etc. The general format of an array constant is the
following:
.nf
{<val1><delim><val2><delim>}
.fi
Where
.IR "<delim>"
is the delimiter for the type stored in the \*(lqpg_type\*(rq class.
(For built-in types, this is the comma character, \*(lq,\*(rq.) An
example of an array constant is
.nf
{{1,2,3},{4,5,6},{7,8,9}}
.fi
This constant is a two-dimensional, 3 by 3 array consisting of three
sub-arrays of integers.
.PP
Individual array elements can and should be placed between quotation
marks whenever possible to avoid ambiguity problems with respect to
leading white space.
.\" Elements of single-element arrays (e.g.,
.\" \*(lq{"1"}\*(rq) must be quoted.
.PP
.SH "FIELDS AND COLUMNS"
.SH "Fields"
A
.IR field
is either an attribute of a given class or one of the following:
.nf
oid
tmin
tmax
xmin
xmax
cmin
cmax
.fi
.PP
.IR Oid
stands for the unique identifier of an instance which is added by
Postgres to all instances automatically. Oids are not reused and are 32
bit quantities.
.PP
.IR "Tmin, tmax, xmin, cmin, xmax"
and
.IR cmax
stand respectively for the time that the instance was inserted, the
time the instance was deleted, the identity of the inserting
transaction, the command identifier within the transaction, the
identity of the deleting transaction and its associated deleting
command. For further information on these fields consult [STON87].
Times are represented internally as instances of the \*(lqabstime\*(rq
data type. Transaction identifiers are 32 bit quantities which are
assigned sequentially starting at 512. Command identifiers are 16 bit
objects; hence, it is an error to have more than 65535 SQL commands
within one transaction.
.SH "Columns"
A
.IR column
is a construct of the form:
.nf
Instance-variable{.composite_field}.field `['number`]'
.fi
.IR Instance-variable
identifies a particular class and can be thought of as standing for
the instances of that class. An instance variable is either a class
name, a surrogate for a class defined by means of a
.IR from
clause, or the keyword
.BR new
or
.BR current.
New and current can only appear in the action portion of a rule, while
other instance variables can be used in any SQL statement.
.IR Composite_field
is a field of of one of the Postgres composite types indicated in the
.IR information (l)
section, while successive composite fields address attributes in the
class(s) to which the composite field evaluates. Lastly,
.IR field
is a normal (base type) field in the class(s) last addressed. If
.IR field
is of type array, then the optional
.IR number
designator indicates a specific element in the array. If no number is
indicated, then all array elements are returned.
.SH "Operators"
Any built-in system, or user-defined operator may be used in SQL.
For the list of built-in and system operators consult
.BR "introduction" "(3)."
For a list of user-defined operators consult your system administrator
or run a query on the pg_operator class. Parentheses may be used for
arbitrary grouping of operators.
.SH "Expressions (a_expr)"
An
.IR expression
is one of the following:
.nf
( a_expr )
constant
attribute
a_expr binary_operator a_expr
a_expr right_unary_operator
left_unary_operator a_expr
parameter
functional expressions
aggregate expressions
.fi
We have already discussed constants and attributes. The two kinds of
operator expressions indicate respectively binary and left_unary
expressions. The following sections discuss the remaining options.
.SH "Parameters"
A
.IR parameter
is used to indicate a parameter in a SQL function. Typically this
is used in SQL function definition statement. The form of a
parameter is:
.nf
\'$' number
.fi
For example, consider the definition of a function, DEPT, as
.nf
create function DEPT (char16)
returns dept
as 'select * from
dept where name=$1'
language 'sql'
.fi
.SH "Functional Expressions"
A
.IR "functional expression"
is the name of a legal SQL function, followed by its argument list
enclosed in parentheses, e.g.:
.nf
fn-name (a_expr{ , a_expr})
.fi
For example, the following computes the square root of an employee
salary.
.nf
sqrt(emp.salary)
.fi
.SH "Aggregate Expression"
An
.IR "aggregate expression"
represents a simple aggregate (i.e., one that computes a single value)
or an aggregate function (i.e., one that computes a set of values).
The syntax is the following:
.nf
aggregate.name (attribute)
.fi
Here,
.IR aggregate_name
must be a previously defined aggregate.
.SH "Target_list"
A
.IR "target list"
is a parenthesized, comma-separated list of one or more elements, each
of which must be of the form:
.nf
a_expr[AS result_attname]
.fi
Here, result_attname is the name of the attribute to be created (or an
already existing attribute name in the case of update statements.) If
.IR result_attname
is not present, then
.IR a_expr
must contain only one attribute name which is assumed to be the name
of the result field. In Postgres default naming is only used if
.IR a_expr
is an attribute.
.SH‚‚ "Qualification"
A
.IR qualification
consists of any number of clauses connected by the logical operators:
.nf
not
and
or
.fi
A clause is an
.IR a_expr
that evaluates to a Boolean over a set of instances.
.SH "From List"
The
.IR "from list"
is a comma-separated list of
.IR "from expressions" .
.PP
Each
.IR "from expression"
is of the form:
.nf
[class_reference] instance_variable
{, [class_ref] instance_variable...}
.fi
where
.IR class_reference
is of the form
.nf
class_name [time_expression] [*]
.fi
The
.IR "from expression"
defines one or more instance variables to range over the class
indicated in
.IR class_reference .
Adding a
.IR time_expression
will indicate that a historical class is desired. One can also request
the instance variable to range over all classes that are beneath the
indicated class in the inheritance hierarchy by postpending the
designator \*(lq*\*(rq.
.SH‚‚ "Time Expressions"
A
.IR "time expression"
is in one of two forms:
.nf
['date']
['date-1', 'date-2']
.fi
The first case requires instances that are valid at the indicated
time. The second case requires instances that are valid at some time
within the date range specified. If no time expression is indicated,
the default is \*(lqnow\*(rq.
.PP
In each case, the date is a character string of the form
.nf
[MON-FRI] 'MMM DD [HH:MM:SS] YYYY' [Timezone]
.fi
where MMM is the month (Jan \- Dec), DD is a legal day number in the
specified month, HH:MM:SS is an optional time in that day (24-hour
clock), and YYYY is the year. If the time of day HH:MM:SS is not
specified, it defaults to midnight at the start of the specified day.
As of Version 3.0, times are no longer read and written using
Greenwich Mean Time; the input and output routines default to the
local time zone.
.PP
For example,
.nf
['Jan 1 1990']
['Mar 3 00:00:00 1980', 'Mar 3 23:59:59 1981r']
.fi
are valid time specifications.
.PP
Note that this syntax is slightly different than that used by the
time-range type.
.SH "SEE ALSO"
insert(l),
delete(l),
execute(l),
update(l),
select(l),
monitor(1).

65
doc/man/template.5 Normal file
View File

@ -0,0 +1,65 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/template.5,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
.TH TEMPLATE FILES 01/23/93 Postgres95 Postgres95
.SH Template
.SH NAME
\&.../data/files/global1.bki \(em global database template
.br
\&.../data/files/local1_XXX.bki \(em local database template
.br
\&.../data/files/template1/* \(em default database template
.SH DESCRIPTION
These files contain scripts which direct the construction of
databases. Note that the \*(lqglobal1.bki\*(rq and
\*(lqtemplate1_local.bki\*(rq files are installed automatically when
the Postgres super-user runs
.IR initdb .
These files are copied from
.nf
\&.../src/backend/obj/{dbdb,local}.bki
.fi
The databases which are generated by the template scripts are normal
databases. Consequently, you can use the terminal monitor or some
other frontend on a template database to simplify the customization
task. That is, there is no need to express everything about your
desired initial database state using a BKI template script, because
the database state can be tuned interactively.
.PP
The system catalogs consist of classes of two types: global and local.
There is one copy of each global class that is shared among all
databases at a site. Local classes, on the other hand, are not
accessible except from their own database.
.PP
The file
.nf
\&.../data/files/global1.bki
.fi
specifies the process used in the creation of global (shared) classes
by
.IR createdb .
Similarly, the
.nf
\&.../files/local1_XXX.bki
.fi
files specify the process used in the creation of local (unshared)
catalog classes for the \*(lqXXX\*(rq template database.
\*(lqXXX\*(rq may be any string of 16 or fewer printable characters.
If no template is specified in a
.IR createdb
command,
then the template in
.nf
\&.../files/local1_template1.bki
.fi
is used.
.PP
The .bki files are generated from C source code by an inscrutable set
of AWK scripts.
.SH BUGS
Postgres Version \*(PV does not permit users to have separate template
databases.
.SH "SEE ALSO"
bki(files),
initdb(1),
createdb(1).

279
doc/man/unix.1 Normal file
View File

@ -0,0 +1,279 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/unix.1,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
.TH INTRODUCTION UNIX 11/05/95 Postgres95 Postgres95
.SP INFORMATION UNIX 11/05/95
.BH "SECTION 2 \(em Unix COMMANDS (Unix)"
.SH "OVERVIEW"
This section outlines the interaction between Postgres and
the operating system. In particular, this section describes
the Postgres support programs that are executable as Unix
commands.
.SH TERMINOLOGY
In the following documentation, the term
.IR 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.
.PP
The
.IR "Postgres super-user"
is the user named \*(lqpostgres\*(rq 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
.IR not
the same as the Unix super-user,
.IR root ,
and should have a non-zero userid for security reasons.
.PP
The
.IR "database base administrator"
or DBA, is the person who is responsible for installing Postgres 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
.IR createdb (1).
.PP
The
.IR postmaster
is the process that acts as a clearing-house for requests to the Postgres
system.
Frontend applications connect to the
.IR postmaster ,
which keeps tracks of any system errors and communication between the
backend processes. The
.IR 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. See
.IR postmaster (1)
for details.
.PP
The
.IR "Postgres backend"
(the actual executable program called "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.
.SH NOTATION
\*(lq.../\*(rq at the front of a file name is used to represent the
path to the Postgres super-user's home directory. Anything in brackets
(\*(lq[\*(rq and \*(lq]\*(rq) is optional. Anything in braces
(\*(lq{\*(rq and \*(lq}\*(rq) can be repeated 0 or more times.
Parentheses (\*(lq(\*(rq and \*(lq)\*(rq ) are used to group boolean
expressions. \*(lq|\*(rq is the boolean operator
.SM OR .
.SH "USING Postgres FROM Unix"
All Postgres commands that are executed directly from a Unix shell are
found in the directory \*(lq.../bin\*(rq. Including this directory in
your search path will make executing the commands easier.
.PP
A collection of system catalogs exist at each site. These include a
class (\*(lqpg_user\*(rq) 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.
.SH "Security"
.SP SECURITY UNIX 03/12/94
.SH "USER AUTHENTICATION"
.IR Authentication
is the process by which the backend server and
.IR 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 \*(lqpg_user\*(rq 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.
.SS "From the user shell"
A backend server started from a user shell notes the user's (effective)
user-id before performing a
.IR setuid (3)
to the user-id of user \*(lqpostgres\*(rq. The effective user-id is used
as the basis for access control checks. No other authentication is
conducted.
.SS "From the network"
If the Postgres system is built as distributed, access to the Internet
TCP port of the
.IR postmaster
process is available to anyone. However, Postgres offers optional
host-based authentication where only access from certain hosts are
allowed. 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.
.PP
If greater security is desired, Postgres and its clients may be
modified to use a network authentication system. For example, the
.IR postmaster ,
.IR psql
and the
.IR libpq
library have already been configured to use either Version 4 or Version 5 of
the
.IR Kerberos
authentication system from the Massachusetts Institute of Technology.
For more information on using
.IR Kerberos
with Postgres, see the appendix below.
.SH "ACCESS CONTROL"
Postgres provides mechanisms to allow users to limit the access to
their data that is provided to other users.
.SS "Database superusers"
Database super-users (i.e., users who have \*(lqpg_user.usesuper\*(rq
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 \*(lqpg_user.usecatupd\*(rq set, and destruction of
system catalogs (or modification of their schemas) is never allowed.
.SS "Access Privilege
The use of access privilege to limit reading, writing and setting
of rules on classes is covered in
.IR "grant/revoke" (l).
.SS "Class removal and schema modification"
Commands that destroy or modify the structure of an existing class,
such as
.IR "alter" ,
.IR "drop table" ,
and
.IR "drop index" ,
only operate for the owner of the class. As mentioned above, these
operations are
.BR never
permitted on system catalogs.
.SH "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
.BR "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
\*(lqpg_class\*(rq, \*(lqpg_user\*(rq and \*(lqpg_group\*(rq are also
recommended.
.SS "Functions"
Functions written in any language except SQL
run inside the backend server
process with the permissions of the user \*(lqpostgres\*(rq (the
backend server runs with its real and effective user-id set to
\*(lqpostgres\*(rq). 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.
.SS "Rules"
Like SQL functions, rules always run with the identity and
permissions of the user who invoked the backend server.
.SH "SEE ALSO"
postmaster(1),
alter(l),
insert(l),
grant/revoke(l),
copy(l),
create(l),
delete(l),
drop table(l),
drop index(l),
drop rule(l),
update(l),
select(l),
kerberos(1),
kinit(1),
kerberos(3)
.SH CAVEATS
.PP
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.
.PP
User names, group names and associated system identifiers (e.g., the
contents of \*(lqpg_user.usesysid\*(rq) are assumed to be unique
throughout a database. Unpredictable results may occur if they are
not.
.SH "APPENDIX: USING KERBEROS"
.SS "Availability"
The
.IR Kerberos
authentication system is not distributed with Postgres, nor is it
available from the University of California at Berkeley. Versions of
.IR Kerberos
are typically available as optional software from operating system
vendors. In addition, a source code distribution may be obtained
through MIT Project Athena by anonymous FTP from ATHENA-DIST.MIT.EDU
(18.71.0.38). (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
.IR Kerberos
is restricted by U. S. government export regulations.
.PP
Any additional inquiries should be directed to your vendor or MIT
Project Athena (\*(lqinfo-kerberos@ATHENA.MIT.EDU\*(rq). Note that FAQLs
(Frequently-Asked Questions Lists) are periodically posted to the
.IR Kerberos
mailing list, \*(lqkerberos@ATHENA.MIT.EDU\*(rq (send mail to
\*(lqkerberos-request@ATHENA.MIT.EDU\*(rq to subscribe), and USENET
news group, \*(lqcomp.protocols.kerberos\*(rq.
.SS "Installation"
Installation of
.IR Kerberos
itself is covered in detail in the
.IR "Kerberos Installation Notes" .
Make sure that the server key file (the
.IR srvtab
or
.IR keytab )
is somehow readable by user \*(lqpostgres\*(rq.
.PP
Postgres and its clients can be compiled to use either Version 4 or
Version 5 of the MIT
.IR Kerberos
protocols by setting the
.SM KRBVERS
variable in the file \*(lq.../src/Makefile.global\*(rq 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.
.PP
After compilation is complete, Postgres must be registered as a
.IR Kerberos
service. See the
.IR "Kerberos Operations Notes"
and related manual pages for more details on registering services.
.SS "Operation"
After initial installation, Postgres should operate in all ways as a
normal
.IR Kerberos
service. For details on the use of authentication, see the manual
pages for
.IR postmaster (1)
and
.IR psql (1).
.PP
In the
.IR Kerberos
Version 5 hooks, the following assumptions are made about user
and service naming: (1) user principal names (anames) are assumed to
contain the actual Unix/Postgres user name in the first component; (2)
the Postgres service is assumed to be have two components, the service
name and a hostname, canonicalized as in Version 4 (i.e., all domain
suffixes removed).
.PP
.nf
user example: frew@S2K.ORG
user example: aoki/HOST=miyu.S2K.Berkeley.EDU@S2K.ORG
host example: postgres_dbms/ucbvax@S2K.ORG
.fi
.PP
Support for Version 4 will disappear sometime after the production
release of Version 5 by MIT.

41
doc/man/update.l Normal file
View File

@ -0,0 +1,41 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/man/Attic/update.l,v 1.1.1.1 1996/08/18 22:14:28 scrappy Exp $
.TH UPDATE SQL 11/05/95 Postgres95 Postgres95
.SH NAME
update \(em replace values of attributes in a class
.SH SYNOPSIS
.nf
\fBupdate\fR classname \fBset\fR attname-1 = expression-1,
{attname-i = expression-i}
[\fBwhere\fR qual]
.fi
.SH DESCRIPTION
.BR Update
changes the values of the attributes specified in
.IR target_list
for all instances which satisfy the qualification,
.IR qual .
Only the attributes to be modified need appear in
.IR target_list .
.PP
Array references use the same syntax found in
.IR select(l).
That is, either single array elements, a range of array elements or
the entire array may be replaced with a single query.
.PP
You must have write access to the class in order to modify it, as well
as read access to any class whose values are mentioned in the target list
or qualification.
.SH EXAMPLES
.nf
--
--Give all employees who work for Smith a 10% raise
--
update emp
set sal = 1.1 * sal
where mgr = 'Smith'
.fi
.SH "SEE ALSO"
create table(l),
select(l).

Some files were not shown because too many files have changed in this diff Show More