mirror of
https://git.postgresql.org/git/postgresql.git
synced 2025-04-12 20:40:47 +08:00
Support Docs & Contrib
This commit is contained in:
Marc G. Fournier
parent
1960a3b965
commit
9848d3655d
22
COPYRIGHT
Normal file
22
COPYRIGHT
Normal 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
283
HISTORY
Normal 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
256
INSTALL
Normal 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
10
MAKE_CTAGS
Normal 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
73
MIGRATION_to_1.02.1
Normal 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
36
README
Normal 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
251
contrib/array/array_iterator.c
Normal 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
26
contrib/array/array_iterator.doc
Normal 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
137
contrib/array/array_iterator.sql
Normal 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
147
contrib/datetime/datetime_functions.c
Normal 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(¤t_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(¤t_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
25
contrib/datetime/datetime_functions.doc
Normal 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
69
contrib/datetime/datetime_functions.sql
Normal 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
19
contrib/pginterface/Makefile
Normal 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
42
contrib/pginterface/README
Normal 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
58
contrib/pginterface/halt.c
Normal 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
7
contrib/pginterface/halt.h
Normal file
@ -0,0 +1,7 @@
|
||||
/*
|
||||
** halt.h
|
||||
**
|
||||
*/
|
||||
|
||||
void halt();
|
||||
|
||||
98
contrib/pginterface/pginsert.c
Normal file
98
contrib/pginterface/pginsert.c
Normal 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
177
contrib/pginterface/pginterface.c
Normal 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
13
contrib/pginterface/pginterface.h
Normal 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
83
contrib/soundex/soundex.c
Normal 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
57
contrib/soundex/soundex.sql
Normal 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
361
contrib/string/string_io.c
Normal 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
111
contrib/string/string_io.sql
Normal 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
180
contrib/zap_ltv/README
Normal 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
93
contrib/zap_ltv/zap_ltv.pl
Normal 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
44
doc/1.0_to_1.01.sql
Normal 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
827
doc/FAQ
Normal 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
50
doc/MIGRATION_from_1.0_to_1.01
Normal 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
32
doc/Makefile
Normal 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
28
doc/README.OPENLINK
Normal 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
147
doc/README.flex
Normal 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
35
doc/README.support
Normal 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
24
doc/RELEASE.patchlevel
Normal 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
121
doc/TODO
Normal 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
41
doc/bug.template
Normal 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
181
doc/libpgtcl.doc
Normal 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
3
doc/man/README
Normal 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
23
doc/man/abort.l
Normal 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
61
doc/man/alter_table.l
Normal 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
20
doc/man/begin.l
Normal 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
224
doc/man/bki.5
Normal 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
700
doc/man/built-in.3
Normal 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
446
doc/man/catalogs.3
Normal 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
23
doc/man/cleardbdir.1
Normal 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
28
doc/man/close.l
Normal 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
33
doc/man/cluster.l
Normal 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
23
doc/man/commit.l
Normal 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
162
doc/man/copy.l
Normal 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
94
doc/man/create_aggregate.l
Normal 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
417
doc/man/create_function.l
Normal 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
314
doc/man/create_index.l
Normal 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
219
doc/man/create_operator.l
Normal 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
221
doc/man/create_rule.l
Normal 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
145
doc/man/create_table.l
Normal 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
161
doc/man/create_type.l
Normal 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
69
doc/man/create_version.l
Normal 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
45
doc/man/create_view.l
Normal 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
127
doc/man/createdb.1
Normal 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
25
doc/man/createdb.l
Normal 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
122
doc/man/createuser.1
Normal 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
41
doc/man/delete.l
Normal 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
134
doc/man/destroydb.1
Normal 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
26
doc/man/destroydb.l
Normal 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
119
doc/man/destroyuser.1
Normal 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
41
doc/man/drop.l
Normal 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
24
doc/man/drop_aggregate.l
Normal 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
28
doc/man/drop_function.l
Normal 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
22
doc/man/drop_index.l
Normal 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
44
doc/man/drop_operator.l
Normal 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
27
doc/man/drop_rule.l
Normal 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
30
doc/man/drop_type.l
Normal 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
17
doc/man/end.l
Normal 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
70
doc/man/fetch.l
Normal 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
37
doc/man/files.5
Normal 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
33
doc/man/grant.l
Normal 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
65
doc/man/initdb.1
Normal 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
113
doc/man/insert.l
Normal 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
36
doc/man/ipcclean.1
Normal 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
499
doc/man/large_objects.3
Normal 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
962
doc/man/libpq.3
Normal 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
44
doc/man/listen.l
Normal 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
51
doc/man/load.l
Normal 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
269
doc/man/monitor.1
Normal 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
48
doc/man/notify.l
Normal 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
130
doc/man/page.5
Normal 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
73
doc/man/pg_dump.1
Normal 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
43
doc/man/pg_hba.5
Normal 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
163
doc/man/postgres.1
Normal 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
323
doc/man/postmaster.1
Normal 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
359
doc/man/psql.1
Normal 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
61
doc/man/purge.l
Normal 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
23
doc/man/remove_view.l
Normal 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
63
doc/man/rename.l
Normal 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
29
doc/man/revoke.l
Normal 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
24
doc/man/rollback.l
Normal 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
133
doc/man/select.l
Normal 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
349
doc/man/sql.l
Normal 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
65
doc/man/template.5
Normal 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
279
doc/man/unix.1
Normal 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
41
doc/man/update.l
Normal 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
Loading…
x
Reference in New Issue
Block a user