mirrors/postgres
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Complete merge of all old man page information.

Browse Source 
lisp.sgml is a placeholder for Eric Marsden's upcoming contribution.
catalogs.sgml is not yet marked up or integrated.
 It should perhaps become an appendix.
This commit is contained in:
Thomas G. Lockhart 1999-07-22 15:11:05 +00:00
parent a27512e634
commit f2f43efbe1
14 changed files with 3656 additions and 1624 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

450
doc/src/sgml/catalogs.sgml Normal file
View File

@ -0,0 +1,450 @@
.\" This is -*-nroff-*-
.\" XXX standard disclaimer belongs here....
.\" $Header: /cvsroot/pgsql/doc/src/sgml/catalogs.sgml,v 2.1 1999/07/22 15:11:03 thomas Exp $
.TH "SYSTEM CATALOGS" INTRO 03/13/94 PostgreSQL PostgreSQL
.SH "Section 7 - 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_shadow 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/rollback log
pg_magic shared magic constant
pg_time shared commit/rollback 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:
INTERNAL function: actual C name of function
C function: currently, this field is unused
SQL function: text of query(s)
PL function: text in procedural language */
bytea probin /* path to object file (C functions 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_shadow
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

316
doc/src/sgml/dfunc.sgml
View File

@ -1,28 +1,127 @@
<Chapter Id="dfunc">
<Title>Linking Dynamically-Loaded Functions</Title>
<chapter id="dfunc">
<title id="dfunc-title">Linking Dynamically-Loaded Functions</title>
<Para>
<!--
.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.
-->
<para>
After you have created and registered a user-defined
function, your work is essentially done. <ProductName>Postgres</ProductName>,
however, must load the object code (e.g., a <FileName>.o</FileName> file, or
function, your work is essentially done. <productname>Postgres</productname>,
however, must load the object code (e.g., a <filename>.o</filename> file, or
a shared library) that implements your function. As
previously mentioned, <ProductName>Postgres</ProductName> loads your code at
previously mentioned, <productname>Postgres</productname> loads your code at
runtime, as required. In order to allow your code to be
dynamically loaded, you may have to compile and
link-edit it in a special way. This section briefly
describes how to perform the compilation and
link-editing required before you can load your user-defined
functions into a running <ProductName>Postgres</ProductName> server. Note that
functions into a running <productname>Postgres</productname> server. Note that
this process has changed as of Version 4.2.
<Tip>
<Para>
The old <ProductName>Postgres</ProductName> dynamic
<tip>
<para>
The old <productname>Postgres</productname> dynamic
loading mechanism required
in-depth knowledge in terms of executable format, placement
and alignment of executable instructions within memory, etc.
on the part of the person writing the dynamic loader. Such
loaders tended to be slow and buggy. As of Version 4.2, the
<ProductName>Postgres</ProductName> dynamic loading mechanism has been rewritten to use
<productname>Postgres</productname> dynamic loading mechanism has been rewritten to use
the dynamic loading mechanism provided by the operating
system. This approach is generally faster, more reliable and
more portable than our previous dynamic loading mechanism.
@ -30,58 +129,59 @@ The reason for this is that nearly all modern versions of
UNIX use a dynamic loading mechanism to implement shared
libraries and must therefore provide a fast and reliable
mechanism. On the other hand, the object file must be
postprocessed a bit before it can be loaded into <ProductName>Postgres</ProductName>. We
postprocessed a bit before it can be loaded into <productname>Postgres</productname>. We
hope that the large increase in speed and reliability will
make up for the slight decrease in convenience.
</para>
</Tip>
</tip>
</para>
<para>
You should expect to read (and reread, and re-reread) the
manual pages for the C compiler, cc(1), and the link
editor, ld(1), if you have specific questions. In
addition, the regression test suites in the directory
<FileName>PGROOT/src/regress</FileName> contain several
<filename>PGROOT/src/regress</filename> contain several
working examples of this process. If you copy what these
tests do, you should not have any problems.
The following terminology will be used below:
<ItemizedList>
<ListItem>
<Para>
<FirstTerm>Dynamic loading</FirstTerm>
is what <ProductName>Postgres</ProductName> does to an object file. The
object file is copied into the running <ProductName>Postgres</ProductName>
<itemizedlist>
<listitem>
<para>
<firstterm>Dynamic loading</firstterm>
is what <productname>Postgres</productname> does to an object file. The
object file is copied into the running <productname>Postgres</productname>
server and the functions and variables within the
file are made available to the functions within
the <ProductName>Postgres</ProductName> process. <ProductName>Postgres</ProductName> does this using
the <productname>Postgres</productname> process.
<productname>Postgres</productname> does this using
the dynamic loading mechanism provided by the
operating system.
</Para>
</ListItem>
<ListItem>
<Para>
<FirstTerm>Loading and link editing</FirstTerm>
</para>
</listitem>
<listitem>
<para>
<firstterm>Loading and link editing</firstterm>
is what you do to an object file in order to produce
another kind of object file (e.g., an executable
program or a shared library). You perform
this using the link editing program, ld(1).
</Para>
</ListItem>
</ItemizedList>
</Para>
</para>
</listitem>
</itemizedlist>
</para>
<Para>
<para>
The following general restrictions and notes also apply
to the discussion below:
<ItemizedList>
<ListItem>
<Para>
<itemizedlist>
<listitem>
<para>
Paths given to the create function command must be
absolute paths (i.e., start with "/") that refer to
directories visible on the machine on which the
<ProductName>Postgres</ProductName> server is running.
<Tip>
<Para>
<productname>Postgres</productname> server is running.
<tip>
<para>
Relative paths do in fact work,
but are relative to
the directory where the database resides (which is generally
@ -89,45 +189,45 @@ invisible to the frontend application). Obviously, it makes
no sense to make the path relative to the directory in which
the user started the frontend application, since the server
could be running on a completely different machine!
</Para>
</Tip>
</Para>
</ListItem>
<ListItem>
<Para>
The <ProductName>Postgres</ProductName> user must be able to traverse the path
</para>
</tip>
</para>
</listitem>
<listitem>
<para>
The <productname>Postgres</productname> user must be able to traverse the path
given to the create function command and be able to
read the object file. This is because the <ProductName>Postgres</ProductName>
server runs as the <ProductName>Postgres</ProductName> user, not as the user
read the object file. This is because the <productname>Postgres</productname>
server runs as the <productname>Postgres</productname> user, not as the user
who starts up the frontend process. (Making the
file or a higher-level directory unreadable and/or
unexecutable by the "postgres" user is an extremely
common mistake.)
</Para>
</ListItem>
<ListItem>
<Para>
</para>
</listitem>
<listitem>
<para>
Symbol names defined within object files must not
conflict with each other or with symbols defined in
<ProductName>Postgres</ProductName>.
</Para>
</ListItem>
<ListItem>
<Para>
<productname>Postgres</productname>.
</para>
</listitem>
<listitem>
<para>
The GNU C compiler usually does not provide the special
options that are required to use the operating
system's dynamic loader interface. In such cases,
the C compiler that comes with the operating system
must be used.
</Para>
</ListItem>
</ItemizedList>
</para>
</listitem>
</itemizedlist>
</para>
<Sect1>
<Title><Acronym>ULTRIX</Acronym></Title>
<sect1>
<title><acronym>ULTRIX</acronym></title>
<Para>
<para>
It is very easy to build dynamically-loaded object
files under ULTRIX. ULTRIX does not have any shared library
mechanism and hence does not place any restrictions on
@ -138,42 +238,42 @@ The GNU C compiler usually does not provide the special
produce each object file with the option -G 0. (Notice
that that's the numeral ``0'' and not the letter
``O''). For example,
<ProgramListing>
<programlisting>
# simple ULTRIX example
% cc -G 0 -c foo.c
</ProgramListing>
</programlisting>
produces an object file called foo.o that can then be
dynamically loaded into <ProductName>Postgres</ProductName>.
dynamically loaded into <productname>Postgres</productname>.
No additional loading or link-editing must be performed.
</Para>
</Sect1>
</para>
</sect1>
<Sect1>
<Title><Acronym>DEC OSF/1</Acronym></Title>
<sect1>
<title><acronym>DEC OSF/1</acronym></title>
<Para>
<para>
Under DEC OSF/1, you can take any simple object file
and produce a shared object file by running the ld command
over it with the correct options. The commands to
do this look like:
<ProgramListing>
<programlisting>
# simple DEC OSF/1 example
% cc -c foo.c
% ld -shared -expect_unresolved '*' -o foo.so foo.o
</ProgramListing>
</programlisting>
The resulting shared object file can then be loaded
into <ProductName>Postgres</ProductName>. When specifying the object file name to
into <productname>Postgres</productname>. When specifying the object file name to
the create function command, one must give it the name
of the shared object file (ending in .so) rather than
the simple object file.
<Tip>
<Para>
Actually, <ProductName>Postgres</ProductName> does not care
<tip>
<para>
Actually, <productname>Postgres</productname> does not care
what you name the
file as long as it is a shared object file. If you prefer
to name your shared object files with the extension .o, this
is fine with <ProductName>Postgres</ProductName>
is fine with <productname>Postgres</productname>
so long as you make sure that the correct
file name is given to the create function command. In
other words, you must simply be consistent. However, from a
@ -183,19 +283,20 @@ files have been made into shared object files and which have
not. For example, it's very hard to write Makefiles to do
the link-editing automatically if both the object file and
the shared object file end in .o!
</Para>
</Tip>
</para>
</tip>
If the file you specify is
not a shared object, the backend will hang!
</Para>
</Sect1>
</para>
</sect1>
<Sect1>
<Title>
<Acronym>SunOS 4.x</Acronym>, <Acronym>Solaris 2.x</Acronym> and <Acronym>HP-UX</Acronym></Title>
<sect1>
<title>
<acronym>SunOS 4.x</acronym>, <acronym>Solaris 2.x</acronym> and
<acronym>HP-UX</acronym></title>
<Para>
<para>
Under SunOS 4.x, Solaris 2.x and HP-UX, the simple
object file must be created by compiling the source
file with special compiler flags and a shared library
@ -209,44 +310,61 @@ If the file you specify is
into a shared library using the HP-UX link editor with
the -b option. This sounds complicated but is actually
very simple, since the commands to do it are just:
<ProgramListing>
<programlisting>
# simple HP-UX example
% cc +z +u -c foo.c
% ld -b -o foo.sl foo.o
</ProgramListing>
</Para>
</programlisting>
</para>
<Para>
<para>
As with the .so files mentioned in the last subsection,
the create function command must be told which file is
the correct file to load (i.e., you must give it the
location of the shared library, or .sl file).
Under SunOS 4.x, the commands look like:
<ProgramListing>
<programlisting>
# simple SunOS 4.x example
% cc -PIC -c foo.c
% ld -dc -dp -Bdynamic -o foo.so foo.o
</ProgramListing>
</programlisting>
and the equivalent lines under Solaris 2.x are:
<ProgramListing>
<programlisting>
# simple Solaris 2.x example
% cc -K PIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
</ProgramListing>
</programlisting>
or
<ProgramListing>
<programlisting>
# simple Solaris 2.x example
% gcc -fPIC -c foo.c
% ld -G -Bdynamic -o foo.so foo.o
</ProgramListing>
</Para>
</programlisting>
</para>
<Para>
<para>
When linking shared libraries, you may have to specify
some additional shared libraries (typically system
libraries, such as the C and math libraries) on your ld
command line.
</Para>
</Sect1>
</Chapter>
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->

495
doc/src/sgml/extend.sgml
View File

@ -1,252 +1,279 @@
<Chapter Id="extend">
<Title>Extending <Acronym>SQL</Acronym>: An Overview</Title>
<chapter id="extend">
<title>Extending <acronym>SQL</acronym>: An Overview</title>
<Para>
In the sections that follow, we will discuss how you
can extend the <ProductName>Postgres</ProductName> <Acronym>SQL</Acronym> query language by adding:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
<para>
In the sections that follow, we will discuss how you
can extend the <productname>Postgres</productname>
<acronym>SQL</acronym> query language by adding:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
functions
</Para>
</ListItem>
<ListItem>
<Para>
</para>
</listitem>
<listitem>
<para>
types
</Para>
</ListItem>
<ListItem>
<Para>
</para>
</listitem>
<listitem>
<para>
operators
</Para>
</ListItem>
<ListItem>
<Para>
</para>
</listitem>
<listitem>
<para>
aggregates
</Para>
</ListItem>
</ItemizedList>
</Para>
</para>
</listitem>
</itemizedlist>
</para>
<Sect1>
<Title>How Extensibility Works</Title>
<sect1>
<title>How Extensibility Works</title>
<Para>
<ProductName>Postgres</ProductName> is extensible because its operation is
catalog-driven. If you are familiar with standard
relational systems, you know that they store information
about databases, tables, columns, etc., in what are
commonly known as system catalogs. (Some systems call
this the data dictionary). The catalogs appear to the
user as classes, like any other, but the <Acronym>DBMS</Acronym> stores
its internal bookkeeping in them. One key difference
between <ProductName>Postgres</ProductName> and standard relational systems is
that <ProductName>Postgres</ProductName> stores much more information in its
catalogs -- not only information about tables and columns,
but also information about its types, functions, access
methods, and so on. These classes can be modified by
the user, and since <ProductName>Postgres</ProductName> bases its internal operation
on these classes, this means that <ProductName>Postgres</ProductName> can be
extended by users. By comparison, conventional
database systems can only be extended by changing hardcoded
procedures within the <Acronym>DBMS</Acronym> or by loading modules
specially-written by the <Acronym>DBMS</Acronym> vendor.
</Para>
<Para>
<ProductName>Postgres</ProductName> is also unlike most other data managers in
that the server can incorporate user-written code into
itself through dynamic loading. That is, the user can
specify an object code file (e.g., a compiled .o file
or shared library) that implements a new type or function
and <ProductName>Postgres</ProductName> will load it as required. Code written
in <Acronym>SQL</Acronym> are even more trivial to add to the server.
This ability to modify its operation "on the fly" makes
<ProductName>Postgres</ProductName> uniquely suited for rapid prototyping of new
applications and storage structures.
</Para>
</Sect1>
<para>
<productname>Postgres</productname> is extensible because its operation is
catalog-driven. If you are familiar with standard
relational systems, you know that they store information
about databases, tables, columns, etc., in what are
commonly known as system catalogs. (Some systems call
this the data dictionary). The catalogs appear to the
user as classes, like any other, but the <acronym>DBMS</acronym> stores
its internal bookkeeping in them. One key difference
between <productname>Postgres</productname> and standard relational systems is
that <productname>Postgres</productname> stores much more information in its
catalogs -- not only information about tables and columns,
but also information about its types, functions, access
methods, and so on. These classes can be modified by
the user, and since <productname>Postgres</productname> bases its internal operation
on these classes, this means that <productname>Postgres</productname> can be
extended by users. By comparison, conventional
database systems can only be extended by changing hardcoded
procedures within the <acronym>DBMS</acronym> or by loading modules
specially-written by the <acronym>DBMS</acronym> vendor.
</para>
<Sect1>
<Title>The <ProductName>Postgres</ProductName> Type System</Title>
<para>
<productname>Postgres</productname> is also unlike most other data managers in
that the server can incorporate user-written code into
itself through dynamic loading. That is, the user can
specify an object code file (e.g., a compiled .o file
or shared library) that implements a new type or function
and <productname>Postgres</productname> will load it as required. Code written
in <acronym>SQL</acronym> are even more trivial to add to the server.
This ability to modify its operation "on the fly" makes
<productname>Postgres</productname> uniquely suited for rapid prototyping of new
applications and storage structures.
</para>
</sect1>
<Para>
The <ProductName>Postgres</ProductName> type system can be broken down in several ways.
Types are divided into base types and composite types.
Base types are those, like <FirstTerm>int4</FirstTerm>, that are implemented
in a language such as <ProductName>C</ProductName>. They generally correspond to
what are often known as "abstract data types"; <ProductName>Postgres</ProductName>
can only operate on such types through methods provided
by the user and only understands the behavior of such
types to the extent that the user describes them.
Composite types are created whenever the user creates a
class. EMP is an example of a composite type.
</Para>
<Para>
<ProductName>Postgres</ProductName> stores these types in only one way (within the
file that stores all instances of the class) but the
user can "look inside" at the attributes of these types
from the query language and optimize their retrieval by
(for example) defining indices on the attributes.
<ProductName>Postgres</ProductName> base types are further divided into built-in
types and user-defined types. Built-in types (like
<FirstTerm>int4</FirstTerm>) are those that are compiled into the system.
User-defined types are those created by the user in the
manner to be described below.
</Para>
</Sect1>
<sect1>
<title>The <productname>Postgres</productname> Type System</title>
<Sect1>
<Title>About the <ProductName>Postgres</ProductName> System Catalogs</Title>
<para>
The <productname>Postgres</productname> type system
can be broken down in several ways.
Types are divided into base types and composite types.
Base types are those, like <firstterm>int4</firstterm>, that are implemented
in a language such as <productname>C</productname>. They generally correspond to
what are often known as "abstract data types"; <productname>Postgres</productname>
can only operate on such types through methods provided
by the user and only understands the behavior of such
types to the extent that the user describes them.
Composite types are created whenever the user creates a
class. EMP is an example of a composite type.
</para>
<Para>
Having introduced the basic extensibility concepts, we
can now take a look at how the catalogs are actually
laid out. You can skip this section for now, but some
later sections will be incomprehensible without the
information given here, so mark this page for later
reference.
All system catalogs have names that begin with <FirstTerm>pg_</FirstTerm>.
The following classes contain information that may be
useful to the end user. (There are many other system
catalogs, but there should rarely be a reason to query
them directly.)
<para>
<productname>Postgres</productname> stores these types
in only one way (within the
file that stores all instances of the class) but the
user can "look inside" at the attributes of these types
from the query language and optimize their retrieval by
(for example) defining indices on the attributes.
<productname>Postgres</productname> base types are further
divided into built-in
types and user-defined types. Built-in types (like
<firstterm>int4</firstterm>) are those that are compiled
into the system.
User-defined types are those created by the user in the
manner to be described below.
</para>
</sect1>
<TABLE TOCENTRY="1">
<TITLE>Postgres System Catalogs</TITLE>
<TITLEABBREV>Catalogs</TITLEABBREV>
<TGROUP COLS="2">
<THEAD>
<ROW>
<ENTRY>Catalog Name</ENTRY>
<ENTRY>Description</ENTRY>
</ROW>
</THEAD>
<TBODY>
<ROW>
<ENTRY>pg_database</ENTRY>
<ENTRY> databases</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_class</ENTRY>
<ENTRY> classes</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_attribute</ENTRY>
<ENTRY> class attributes</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_index</ENTRY>
<ENTRY> secondary indices</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_proc</ENTRY>
<ENTRY> procedures (both C and SQL)</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_type</ENTRY>
<ENTRY> types (both base and complex)</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_operator</ENTRY>
<ENTRY> operators</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_aggregate</ENTRY>
<ENTRY> aggregates and aggregate functions</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_am</ENTRY>
<ENTRY> access methods</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_amop</ENTRY>
<ENTRY> access method operators</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_amproc</ENTRY>
<ENTRY> access method support functions</ENTRY>
</ROW>
<ROW>
<ENTRY>pg_opclass</ENTRY>
<ENTRY> access method operator classes</ENTRY>
</ROW>
</TBODY>
</TGROUP>
</TABLE>
</Para>
<sect1>
<title>About the <productname>Postgres</productname> System Catalogs</title>
<Para>
<Figure Id="EXTEND-CATALOGS" Float="1">
<Title>The major <ProductName>Postgres</ProductName> system catalogs</Title>
<Graphic Align="center" FileRef="catalogs.gif" Format="GIF"></Graphic>
</Figure>
<para>
Having introduced the basic extensibility concepts, we
can now take a look at how the catalogs are actually
laid out. You can skip this section for now, but some
later sections will be incomprehensible without the
information given here, so mark this page for later
reference.
All system catalogs have names that begin with
<firstterm>pg_</firstterm>.
The following classes contain information that may be
useful to the end user. (There are many other system
catalogs, but there should rarely be a reason to query
them directly.)
The Reference Manual gives a more detailed explanation
of these catalogs and their attributes. However,
<XRef LinkEnd="EXTEND-CATALOGS" EndTerm="EXTEND-CATALOGS">
shows the major entities and their relationships
in the system catalogs. (Attributes that do not refer
to other entities are not shown unless they are part of
a primary key.)
This diagram is more or less incomprehensible until you
actually start looking at the contents of the catalogs
and see how they relate to each other. For now, the
main things to take away from this diagram are as follows:
<table tocentry="1">
<title>Postgres System Catalogs</title>
<titleabbrev>Catalogs</titleabbrev>
<tgroup cols="2">
<thead>
<row>
<entry>Catalog Name</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry>pg_database</entry>
<entry> databases</entry>
</row>
<row>
<entry>pg_class</entry>
<entry> classes</entry>
</row>
<row>
<entry>pg_attribute</entry>
<entry> class attributes</entry>
</row>
<row>
<entry>pg_index</entry>
<entry> secondary indices</entry>
</row>
<row>
<entry>pg_proc</entry>
<entry> procedures (both C and SQL)</entry>
</row>
<row>
<entry>pg_type</entry>
<entry> types (both base and complex)</entry>
</row>
<row>
<entry>pg_operator</entry>
<entry> operators</entry>
</row>
<row>
<entry>pg_aggregate</entry>
<entry> aggregates and aggregate functions</entry>
</row>
<row>
<entry>pg_am</entry>
<entry> access methods</entry>
</row>
<row>
<entry>pg_amop</entry>
<entry> access method operators</entry>
</row>
<row>
<entry>pg_amproc</entry>
<entry> access method support functions</entry>
</row>
<row>
<entry>pg_opclass</entry>
<entry> access method operator classes</entry>
</row>
</tbody>
</tgroup>
</table>
</para>
<para>
<figure float="1" id="EXTEND-CATALOGS">
<title>The major <productname>Postgres</productname> system catalogs</title>
<graphic fileref="catalogs.gif" format="GIF" align="center"></graphic>
</figure>
The Reference Manual gives a more detailed explanation
of these catalogs and their attributes. However,
<xref endterm="EXTEND-CATALOGS" linkend="EXTEND-CATALOGS">
shows the major entities and their relationships
in the system catalogs. (Attributes that do not refer
to other entities are not shown unless they are part of
a primary key.)
This diagram is more or less incomprehensible until you
actually start looking at the contents of the catalogs
and see how they relate to each other. For now, the
main things to take away from this diagram are as follows:
<ItemizedList Mark="bullet" Spacing="compact">
<ListItem>
<Para>
In several of the sections that follow, we will
present various join queries on the system
catalogs that display information we need to extend
the system. Looking at this diagram should make
some of these join queries (which are often
three- or four-way joins) more understandable,
because you will be able to see that the
attributes used in the queries form foreign keys
in other classes.
</Para>
</ListItem>
<ListItem>
<Para> Many different features (classes, attributes,
functions, types, access methods, etc.) are
tightly integrated in this schema. A simple
create command may modify many of these catalogs.
</Para>
</ListItem>
<ListItem>
<Para> Types and procedures
are central to the schema.
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
In several of the sections that follow, we will
present various join queries on the system
catalogs that display information we need to extend
the system. Looking at this diagram should make
some of these join queries (which are often
three- or four-way joins) more understandable,
because you will be able to see that the
attributes used in the queries form foreign keys
in other classes.
</para>
</listitem>
<listitem>
<para>
Many different features (classes, attributes,
functions, types, access methods, etc.) are
tightly integrated in this schema. A simple
create command may modify many of these catalogs.
</para>
</listitem>
<listitem>
<para>
Types and procedures
are central to the schema.
<Note>
<Para>
We use the words <FirstTerm>procedure</FirstTerm> and <FirstTerm>function</FirstTerm> more or less
interchangably.
</Para>
</Note>
<note>
<para>
We use the words <firstterm>procedure</firstterm>
and <firstterm>function</firstterm> more or less interchangably.
</para>
</note>
Nearly every catalog contains some reference to
instances in one or both of these classes. For
example, <ProductName>Postgres</ProductName> frequently uses type
signatures (e.g., of functions and operators) to
identify unique instances of other catalogs.
Nearly every catalog contains some reference to
instances in one or both of these classes. For
example, <productname>Postgres</productname> frequently uses type
signatures (e.g., of functions and operators) to
identify unique instances of other catalogs.
</para>
</listitem>
<listitem>
<para>
There are many attributes and relationships that
have obvious meanings, but there are many
(particularly those that have to do with access
methods) that do not. The relationships between
pg_am, pg_amop, pg_amproc, pg_operator and
pg_opclass are particularly hard to understand
and will be described in depth (in the section
on interfacing types and operators to indices)
after we have discussed basic extensions.
</para>
</listitem>
</itemizedlist>
</para>
</sect1>
</chapter>
</Para>
</ListItem>
<ListItem>
<Para> There are many attributes and relationships that
have obvious meanings, but there are many
(particularly those that have to do with access
methods) that do not. The relationships between
pg_am, pg_amop, pg_amproc, pg_operator and
pg_opclass are particularly hard to understand
and will be described in depth (in the section
on interfacing types and operators to indices)
after we have discussed basic extensions.
</para>
</ListItem>
</ItemizedList>
</Para>
</sect1>
</Chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->

415
doc/src/sgml/indices.sgml
View File

@ -1,57 +1,384 @@
<chapter id="indices">
<title>Indices</title>
<chapter id="indices">
<title id="indices-title">Indices and Keys</title>
<para>
<para>
Indexes are primarily used to enhance database
performance. They should be defined on table columns (or class
attributes) which are used as qualifications in repetative queries.
Inappropriate use will result in slower performance, since update
and insertion times are increased in the presence of indices.
</para>
<sect1>
<title>Partial Indices</title>
<para>
Two forms of indices may be defined:
<para>
<note>
<title>Author</title>
<para>
This is from a reply to a question on the e-mail list
by <ulink url="aoki@CS.Berkeley.EDU">Paul M. Aoki</ulink>
on 1998-08-11.
<itemizedlist>
<listitem>
<para>
For a <firstterm>value index</firstterm>,
the key fields for the
index are specified as column names; a column may also have
an associated 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 <literal>int4_ops</literal> class;
this operator class includes
comparison functions for four-byte integers. The default
operator class is the appropriate operator class for that
field type.
</para>
</listitem>
<listitem>
<para>
For a <firstterm>functional index</firstterm>, an index is defined
on the result of a user-defined function applied
to one or more attributes of a single class.
These functional indices
can be used to obtain fast access to data
based on operators that would normally require some
transformation to apply them to the base data.
</para>
</listitem>
</itemizedlist>
</para>
<para>
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).
</para>
<para>
The Postgres query optimizer will consider using btree indices in a scan
whenever an indexed attribute is involved in a comparison using one of:
<simplelist type="inline">
<member>&lt;</member>
<member>&lt;=</member>
<member>=</member>
<member>&gt;=</member>
<member>&gt;</member>
</simplelist>
</para>
<para>
Both box classes support indices on the <literal>box</literal> data
type in <productname>Postgres</productname>.
The difference between them is that <literal>bigbox_ops</literal>
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
<literal>bigbox_ops</literal>.
The <literal>poly_ops</literal> operator class supports rtree
indices on <literal>polygon</literal> data.
</para>
<para>
The <productname>Postgres</productname>
query optimizer will consider using an rtree index whenever
an indexed attribute is involved in a comparison using one of:
<simplelist type="inline">
<member>&lt;&lt;</member>
<member>&amp;&lt;</member>
<member>&amp;&gt;</member>
<member>&gt;&gt;</member>
<member>@</member>
<member>~=</member>
<member>&amp;&amp;</member>
</simplelist>
</para>
<para>
The <productname>Postgres</productname>
query optimizer will consider using a hash index whenever
an indexed attribute is involved in a comparison using
the <literal>=</literal> operator.
</para>
<para>
Currently, only the BTREE access method supports multi-column
indexes. Up to 7 keys may be specified.
</para>
<para>
Use <xref endterm="sql-dropindex-title"
linkend="sql-dropindex-title">
to remove an index.
</para>
<para>
The <literal>int24_ops</literal>
operator class is useful for constructing indices on int2 data, and
doing comparisons against int4 data in query qualifications.
Similarly, <literal>int42_ops</literal>
support indices on int4 data that is to be compared against int2 data
in queries.
</para>
<para>
The following select list returns all ops_names:
<programlisting>
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
</programlisting>
</para>
<sect1 id="keys">
<title id="keys-title">Keys</title>
<para>
<note>
<title>Author</title>
<para>
Written by
<ulink url="herouth@oumail.openu.ac.il">Herouth Maoz</ulink>
This originally appeared on the User's Mailing List on 1998-03-02
in response to the question:
"What is the difference between PRIMARY KEY and UNIQUE constraints?".
</para>
</note>
</para>
<para>
<programlisting>
Subject: Re: [QUESTIONS] PRIMARY KEY | UNIQUE
What's the difference between:
PRIMARY KEY(fields,...) and
UNIQUE (fields,...)
- Is this an alias?
- If PRIMARY KEY is already unique, then why
is there another kind of key named UNIQUE?
</programlisting>
</para>
<para>
A primary key is the field(s) used to identify a specific row. For example,
Social Security numbers identifying a person.
</para>
<para>
A simply UNIQUE combination of fields has nothing to do with identifying
the row. It's simply an integrity constraint. For example, I have
collections of links. Each collection is identified by a unique number,
which is the primary key. This key is used in relations.
</para>
<para>
However, my application requires that each collection will also have a
unique name. Why? So that a human being who wants to modify a collection
will be able to identify it. It's much harder to know, if you have two
collections named "Life Science", the the one tagged 24433 is the one you
need, and the one tagged 29882 is not.
</para>
<para>
So, the user selects the collection by its name. We therefore make sure,
withing the database, that names are unique. However, no other table in the
database relates to the collections table by the collection Name. That
would be very inefficient.
</para>
<para>
Moreover, despite being unique, the collection name does not actually
define the collection! For example, if somebody decided to change the name
of the collection from "Life Science" to "Biology", it will still be the
same collection, only with a different name. As long as the name is unique,
that's OK.
</para>
<para>
So:
<itemizedlist>
<listitem>
<para>
Primary key:
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
Is used for identifying the row and relating to it.
</para>
</listitem>
<listitem>
<para>
Is impossible (or hard) to update.
</para>
</listitem>
<listitem>
<para>
Should not allow NULLs.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
<listitem>
<para>
Unique field(s):
<itemizedlist spacing="compact" mark="bullet">
<listitem>
<para>
Are used as an alternative access to the row.
</para>
</listitem>
<listitem>
<para>
Are updateable, so long as they are kept unique.
</para>
</listitem>
<listitem>
<para>
NULLs are acceptable.
</para>
</listitem>
</itemizedlist>
</para>
</listitem>
</itemizedlist>
</para>
<para>
As for why no non-unique keys are defined explicitly in standard
<acronym>SQL</acronym> syntax? Well, you
must understand that indices are implementation-dependent.
<acronym>SQL</acronym> does not
define the implementation, merely the relations between data in the
database. <productname>Postgres</productname> does allow
non-unique indices, but indices
used to enforce <acronym>SQL</acronym> keys are always unique.
</para>
<para>
Thus, you may query a table by any combination of its columns, despite the
fact that you don't have an index on these columns. The indexes are merely
an implementational aid which each <acronym>RDBMS</acronym> offers
you, in order to cause
commonly used queries to be done more efficiently.
Some <acronym>RDBMS</acronym> may give you
additional measures, such as keeping a key stored in main memory. They will
have a special command, for example
<programlisting>
CREATE MEMSTORE ON &lt;table&gt; COLUMNS &lt;cols&gt;
</programlisting>
(this is not an existing command, just an example).
</para>
<para>
In fact, when you create a primary key or a unique combination of fields,
nowhere in the <acronym>SQL</acronym> specification does it say
that an index is created, nor that
the retrieval of data by the key is going to be more efficient than a
sequential scan!
</para>
<para>
So, if you want to use a combination of fields which is not unique as a
secondary key, you really don't have to specify anything - just start
retrieving by that combination! However, if you want to make the retrieval
efficient, you'll have to resort to the means your
<acronym>RDBMS</acronym> provider gives you
- be it an index, my imaginary MEMSTORE command, or an intelligent
<acronym>RDBMS</acronym>
which creates indices without your knowledge based on the fact that you have
sent it many queries based on a specific combination of keys... (It learns
from experience).
</para>
</sect1>
<sect1 id="partial-index">
<title id="partial-index-title">Partial Indices</title>
<note>
<title>Author</title>
<para>
This is from a reply to a question on the e-mail list
by <ulink url="aoki@CS.Berkeley.EDU">Paul M. Aoki</ulink>
on 1998-08-11.
<!--
Paul M. Aoki | University of California at Berkeley
aoki@CS.Berkeley.EDU | Dept. of EECS, Computer Science Division #1776
| Berkeley, CA 94720-1776
-->
</note>
</para>
</note>
A <firstterm>partial index</firstterm>
is an index built over a subset of a table; the subset is defined by
a predicate. <productname>Postgres</productname>
supported partial indices with arbitrary
predicates. I believe IBM's db2 for as/400 supports partial indices
using single-clause predicates.
<para>
A <firstterm>partial index</firstterm>
is an index built over a subset of a table; the subset is defined by
a predicate. <productname>Postgres</productname>
supported partial indices with arbitrary
predicates. I believe IBM's db2 for as/400 supports partial indices
using single-clause predicates.
</para>
<para>
The main motivation for partial indices is this:
if all of the queries you ask that can
profitably use an index fall into a certain range, why build an index
over the whole table and suffer the associated space/time costs?
<para>
The main motivation for partial indices is this:
if all of the queries you ask that can
profitably use an index fall into a certain range, why build an index
over the whole table and suffer the associated space/time costs?
(There are other reasons too; see
<xref linkend="STON89b-full" endterm="STON89b"> for details.)
(There are other reasons too; see
<xref endterm="STON89b" linkend="STON89b-full"> for details.)
</para>
<para>
The machinery to build, update and query partial indices isn't too
bad. The hairy parts are index selection (which indices do I build?)
and query optimization (which indices do I use?); i.e., the parts
that involve deciding what predicate(s) match the workload/query in
some useful way. For those who are into database theory, the problems
are basically analogous to the corresponding materialized view
problems, albeit with different cost parameters and formulae. These
are, in the general case, hard problems for the standard ordinal
<acronym>SQL</acronym>
types; they're super-hard problems with black-box extension types,
because the selectivity estimation technology is so crude.
<para>
The machinery to build, update and query partial indices isn't too
bad. The hairy parts are index selection (which indices do I build?)
and query optimization (which indices do I use?); i.e., the parts
that involve deciding what predicate(s) match the workload/query in
some useful way. For those who are into database theory, the problems
are basically analogous to the corresponding materialized view
problems, albeit with different cost parameters and formulae. These
are, in the general case, hard problems for the standard ordinal
<acronym>SQL</acronym>
types; they're super-hard problems with black-box extension types,
because the selectivity estimation technology is so crude.
</para>
<para>
Check <xref linkend="STON89b-full" endterm="STON89b">,
<xref linkend="OLSON93-full" endterm="OLSON93">,
and
<xref linkend="SESHADRI95-full" endterm="SESHADRI95">
for more information.
<para>
Check <xref endterm="STON89b" linkend="STON89b-full">,
<xref endterm="OLSON93" linkend="OLSON93-full">,
and
<xref endterm="SESHADRI95" linkend="SESHADRI95-full">
for more information.
</para>
</sect1>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/catalog"
sgml-local-ecat-files:nil
End:
-->

104
doc/src/sgml/lisp.sgml Normal file
View File

@ -0,0 +1,104 @@
<chapter id="lisp">
<title id="lisp-title">Lisp Programming Interface</title>
<abstract>
<para>
<filename>pg.el</filename> is a socket-level interface to
<productname>Postgres</productname> for emacs.
</para>
</abstract>
<note>
<title>Author</title>
<para>
Written by
<ulink url="mailto:emarsden@mail.dotcom.fr">Eric Marsden</ulink>
on 21 Jul 1999.
</para>
</note>
<para>
<filename>pg.el</filename> is a socket-level interface to
<productname>Postgres</productname> for emacs (text
editor extraordinaire). The module is capable of type coercions from a
range of SQL types to the equivalent Emacs Lisp type. It currently
supports neither crypt or Kerberos authentication, nor large objects.
</para>
<para>
The code (version 0.2) is available under GNU GPL from
<ulink url="http://www.chez.com/emarsden/downloads/pg.el">
http://www.chez.com/emarsden/downloads/pg.el</ulink>
</para>
<para>
Changes since last release:
<itemizedlist mark="bullet" spacing="compact">
<listitem>
<para>
now works with XEmacs (tested with Emacs 19.34 & 20.2, and XEmacs
20.4)
</para>
</listitem>
<listitem>
<para>
added functions to provide database metainformation (list of
databases, of tables, of columns)
</para>
</listitem>
<listitem>
<para>
arguments to `pg:result' are now :keywords
</para>
</listitem>
<listitem>
<para>
MULE-resistant
</para>
</listitem>
<listitem>
<para>
more self-testing code
</para>
</listitem>
</itemizedlist>
</para>
<para>
Please note that this is a programmer's API, and doesn't provide any
form of user interface. Example:
<programlisting>
(defun demo ()
(interactive)
(let* ((conn (pg:connect "template1" "postgres" "postgres"))
(res (pg:exec conn "SELECT * from scshdemo WHERE a = 42")))
(message "status is %s" (pg:result res :status))
(message "metadata is %s" (pg:result res :attributes))
(message "data is %s" (pg:result res :tuples))
(pg:disconnect conn)))
</programlisting>
</para>
</chapter>
<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:"/usr/lib/sgml/CATALOG"
sgml-local-ecat-files:nil
End:
-->

2
doc/src/sgml/oper.sgml
View File

@ -12,7 +12,7 @@
<ProductName>Postgres</ProductName> provides a large number of
built-in operators on system types.
These operators are declared in the system catalog
pg_operator. Every entry in pg_operator includes
<literal>pg_operator</literal>. Every entry in <literal>pg_operator</literal> includes
the name of the procedure that implements the operator and the
class <Acronym>OIDs</Acronym> of the input and output types.
</Para>

137
doc/src/sgml/postgres.sgml
View File

@ -1,105 +1,3 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/postgres.sgml,v 1.28 1999/06/23 06:15:12 thomas Exp $
Postgres integrated documentation.
Other subset docs should be copied and shrunk from here.
thomas 1998-02-23
$Log: postgres.sgml,v $
Revision 1.28 1999/06/23 06:15:12 thomas
Add backup/restore info to Admin Guide.
Split management chapter from start-ag.sgml to manage-ag.sgml.
Revision 1.27 1999/06/03 04:21:49 thomas
Markup changes for v6.5 release.
Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
Revision 1.26 1999/06/01 17:26:18 thomas
Make sure that only one intro is included in the integrated doc.
Multiple intros cause trouble since they have some section elements
(e.g. "y2k.sgml") in common leading to duplicate labels.
Include emacs formatting hints in the intro*.sgml sources.
Revision 1.25 1999/05/27 15:49:08 thomas
Markup fixes.
Update for v6.5 release.
Revision 1.24 1999/05/26 17:30:29 thomas
Add chapters on CVS access, MVCC, SQL theory to the docs.
Add an appendix with more details on date/time attributes and handling.
Update most references to Postgres version numbers to 6.5,
*except* for the porting list which will require a report
from a successful installation to be updated.
Revision 1.23 1999/05/22 02:27:24 thomas
Finish initial markup of cvs.sgml, and include it in the programmer's guide
and the integrated doc. Clean up other markup.
Revision 1.22 1999/05/20 05:39:27 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.21 1999/05/04 02:19:20 thomas
Include chapters on security and an intro to SQL.
Revision 1.20 1999/04/06 15:41:13 thomas
Fix markup to include all closing tags.
Required by newest versions of DocBook and style sheets.
Revision 1.19 1999/03/30 15:23:03 thomas
Include libpq+.sgml in the doc set.
Had been omitted from the integrated doc for no good reason.
Revision 1.18 1999/02/13 03:52:46 thomas
Include chapter on SQL language elements (keywords, etc).
Should merge with or complement Stefan's Master's Thesis intro to SQL.
Revision 1.17 1999/01/19 16:06:25 thomas
Merge current.sgml into release.sgml so all release notes are in the same
file. Per Bruce's preference. Go to it Bruce!
No info yet for v6.4.2 or upcoming releases.
Revision 1.16 1999/01/07 02:59:45 thomas
Include installation instructions for WIN32 client-side libraries.
From Magnus Hagander <mha@sollentuna.net>.
Revision 1.15 1998/12/18 16:23:34 thomas
Fix typos in rules.sgml.
Add Emacs configuration block to postgres.sgml.
Revision 1.14 1998/10/31 09:36:34 thomas
Cleanup for v6.4 release.
Make new file current.sgml to hold release info for the current release.
Should be moved to release.sgml before filling with next release info.
Revision 1.13 1998/10/30 19:37:09 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.12 1998/10/27 06:14:01 thomas
Include configuration chapter with new info on configure and make.
Revision 1.11 1998/10/25 00:24:31 thomas
Add Y2K statement for intros.
Make sure notation section is included in most intros.
Revision 1.7-1.10 1998/10/21 05:31:52 thomas
Include new information from Massimo. Rearrange ODBC docs.
Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
and notation sections appear in all documents without having the history
show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
Move SQL reference pages up into the User's Guide.
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity about SYSTEM "about.sgml">
@ -123,8 +21,8 @@ Move SQL reference pages up into the User's Guide.
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity keys SYSTEM "keys.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
@ -156,28 +54,29 @@ Move SQL reference pages up into the User's Guide.
<!entity trouble SYSTEM "trouble.sgml">
<!-- programmer's guide -->
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
@ -277,7 +176,7 @@ Your name here...
&oper;
&func;
&typeconv;
&keys;
&indices;
&array;
&inherit;
&mvcc;
@ -341,7 +240,6 @@ Your name here...
&trigger;
&spi;
&xplang;
<!-- &libpq; -->
</Part>
<part Id="part-interfaces">
@ -359,6 +257,7 @@ Your name here...
&libpgtcl;
&odbc;
&jdbc;
&lisp;
</Part>
<part Id="part-developer">

38
doc/src/sgml/programmer.sgml
View File

@ -1,9 +1,15 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.18 1999/06/23 06:21:19 thomas Exp $
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/programmer.sgml,v 1.19 1999/07/22 15:11:04 thomas Exp $
Postgres Programmer's Guide.
$Log: programmer.sgml,v $
Revision 1.19 1999/07/22 15:11:04 thomas
Complete merge of all old man page information.
lisp.sgml is a placeholder for Eric Marsden's upcoming contribution.
catalogs.sgml is not yet marked up or integrated.
It should perhaps become an appendix.
Revision 1.18 1999/06/23 06:21:19 thomas
Remove User's Guide entities since they were not being used.
@ -34,28 +40,29 @@ Make new file current.sgml to hold release info for the current release.
<!entity notation SYSTEM "notation.sgml">
<!entity y2k SYSTEM "y2k.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity arch-pg SYSTEM "arch-pg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity dfunc SYSTEM "dfunc.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity extend SYSTEM "extend.sgml">
<!entity func-ref SYSTEM "func-ref.sgml">
<!entity gist SYSTEM "gist.sgml">
<!entity intro-pg SYSTEM "intro-pg.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity libpq SYSTEM "libpq.sgml">
<!entity libpqpp SYSTEM "libpq++.sgml">
<!entity libpgtcl SYSTEM "libpgtcl.sgml">
<!entity ecpg SYSTEM "ecpg.sgml">
<!entity lisp SYSTEM "lisp.sgml">
<!entity lobj SYSTEM "lobj.sgml">
<!entity odbc SYSTEM "odbc.sgml">
<!entity jdbc SYSTEM "jdbc.sgml">
<!entity rules SYSTEM "rules.sgml">
<!entity spi SYSTEM "spi.sgml">
<!entity trigger SYSTEM "trigger.sgml">
<!entity xaggr SYSTEM "xaggr.sgml">
<!entity xfunc SYSTEM "xfunc.sgml">
<!entity xindex SYSTEM "xindex.sgml">
<!entity xplang SYSTEM "xplang.sgml">
<!entity xoper SYSTEM "xoper.sgml">
<!entity xtypes SYSTEM "xtypes.sgml">
<!-- developer's guide -->
<!entity arch-dev SYSTEM "arch-dev.sgml">
@ -172,6 +179,7 @@ Disable it until we put in some info.
&ecpg;
&odbc;
&jdbc;
&lisp;
<!-- development -->

271
doc/src/sgml/security.sgml
View File

@ -102,6 +102,221 @@
</varlistentry>
</variablelist>
</para>
<Sect2>
<Title>Host-Based Access Control</Title>
<Para>
.SH NAME
$PGDATA/pg_hba.conf
.SH DESCRIPTION
<firstterm>Host-based access control</firstterm>
is the name for the basic controls PostgreSQL
exercises on what clients are allowed to access a database and how
the users on those clients must authenticate themselves.
</para>
<para>
Each database system contains a file named
<filename>pg_hba.conf</filename>, in its <envar>PGDATA</envar>
directory, which controls who can connect to each database.
</para>
<para>
Every client accessing a database
<emphasis>must</emphasis>
be covered by one of
the entries in <filename>pg_hba.conf</filename>.
Otherwise all attempted connections from that
client will be rejected with a "User authentication failed" error
message.
</para>
<para>
The general format of the <filename>pg_hba.conf</filename>
file is of a set of records, one per
line. Blank lines and lines beginning with a hash character
("#") are ignored. A record is
made up of a number of fields which are separated by spaces and/or tabs.
</para>
<para>
Connections from clients can be made using UNIX domain sockets or Internet
domain sockets (ie. TCP/IP). Connections made using UNIX domain sockets
are controlled using records of the following format:
<synopsis>
local <replaceable>database</replaceable> <replaceable>authentication method</replaceable>
</synopsis>
where
<simplelist>
<member>
<replaceable>database</replaceable>
specifies the database that this record applies to. The value
<literal>all</literal>
specifies that it applies to all databases.
</member>
<member>
<replaceable>authentication method</replaceable>
specifies the method a user must use to authenticate themselves when
connecting to that database using UNIX domain sockets. The different methods
are described below.
</member>
</simplelist>
</para>
<para>
Connections made using Internet domain sockets are controlled using records
of the following format.
<synopsis>
host <replaceable>database</replaceable> <replaceable>TCP/IP address</replaceable> <replaceable>TCP/IP mask</replaceable> <replaceable>authentication method</replaceable>
</synopsis>
</para>
<para>
The <replaceable>TCP/IP address</replaceable>
is logically anded to both the specified
<replaceable>TCP/IP mask</replaceable>
and the TCP/IP address
of the connecting client.
If the two resulting values are equal then the
record is used for this connection. If a connection matches more than one
record then the earliest one in the file is used.
Both the
<replaceable>TCP/IP address</replaceable>
and the
<replaceable>TCP/IP mask</replaceable>
are specified in dotted decimal notation.
</para>
<para>
If a connection fails to match any record then the
<firstterm>reject</firstterm>
authentication method is applied (see below).
</para>
<sect3>
<title>Authentication Methods</title>
<para>
The following authentication methods are supported for both UNIX and TCP/IP
domain sockets:
<variablelist>
<varlistentry>
<term>trust</term>
<listitem>
<para>
The connection is allowed unconditionally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>reject</term>
<listitem>
<para>
The connection is rejected unconditionally.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>crypt</term>
<listitem>
<para>
The client is asked for a password for the user. This is sent encrypted
(using <citetitle>crypt(3)</citetitle>)
and compared against the password held in the
<filename>pg_shadow</filename> table.
If the passwords match, the connection is allowed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>password</term>
<listitem>
<para>
The client is asked for a password for the user. This is sent in clear
and compared against the password held in the
<filename>pg_shadow</filename> table.
If the passwords match, the connection is allowed. An optional password file
may be specified after the
<literal>password</literal>
keyword which is used to match the supplied password rather than the pg_shadow
table. See
<citerefentry><refentrytitle>pg_passwd</refentrytitle></citerefentry>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
The following authentication methods are supported for TCP/IP
domain sockets only:
<variablelist>
<varlistentry>
<term>krb4</term>
<listitem>
<para>
Kerberos V4 is used to authenticate the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>krb5</term>
<listitem>
<para>
Kerberos V5 is used to authenticate the user.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>ident</term>
<listitem>
<para>
The ident server on the client is used to authenticate the user (RFC 1413).
An optional map name may be specified after the
<literal>ident</literal>
keyword which allows ident user names to be mapped onto
<productname>Postgres</productname> user names.
Maps are held in the file
<filename>$<envar>PGDATA</envar>/pg_ident.conf</filename>.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect3>
<sect3>
<title>Examples</title>
<para>
<programlisting>
# Trust any connection via UNIX domain sockets.
local trust
# Trust any connection via TCP/IP from this machine.
host all 127.0.0.1 255.255.255.255 trust
# We don't like this machine.
host all 192.168.0.10 255.255.255.0 reject
# This machine can't encrypt so we ask for passwords in clear.
host all 192.168.0.3 255.255.255.0 password
# The rest of this group of machines should provide encrypted passwords.
host all 192.168.0.0 255.255.255.0 crypt
</programlisting>
</para>
</sect3>
</sect2>
</sect1>
<sect1>
@ -138,20 +353,50 @@
have to explicitly insert/update the <literal>pg_group table</literal>.
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=>
<programlisting>
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=>
</programlisting>
</para>
The fields in pg_group are:
* groname: the group name. This a name 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[].
<para>
The fields in <filename>pg_group</filename> are:
<variablelist>
<varlistentry>
<term>groname</term>
<listitem>
<para>
The group name. This a name and should be purely
alphanumeric. Do not include underscores or other punctuation.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>grosysid</term>
<listitem>
<para>
The group id. This is an int4. This should be unique for
each group.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>grolist</term>
<listitem>
<para>
The list of pg_user id's that belong in the group. This
is an int4[].
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>

457
doc/src/sgml/syntax.sgml
View File

@ -3,14 +3,18 @@
<abstract>
<para>
<acronym>SQL</acronym> manipulates sets of data. The language is
composed of various <firstterm>key words</firstterm>. Arithmetic
and procedural expressions are allowed. We will cover these topics
in this chapter; subsequent chapters will include details on data
types, functions, and operators.
A description of the general syntax of SQL.
</para>
</abstract>
<para>
<acronym>SQL</acronym> manipulates sets of data. The language is
composed of various <firstterm>key words</firstterm>. Arithmetic
and procedural expressions are allowed. We will cover these topics
in this chapter; subsequent chapters will include details on data
types, functions, and operators.
</para>
<sect1>
<title>Key Words</title>
@ -230,7 +234,7 @@ MAXVALUE MINVALUE MODE
NOCREATEDB NOCREATEUSER NOTHING NOTNULL
OIDS OPERATOR
PASSWORD PROCEDURAL
RECIPE RENAME RETURNS ROW RULE
RECIPE RENAME RETURNS ROW RULE
SEQUENCE SERIAL SHARE START STATEMENT STDIN STDOUT
TRUSTED
VALID VERSION
@ -302,18 +306,455 @@ UNCOMMITTED UNNAMED
</sect2>
</sect1>
<sect1>
<title>Comments</title>
<para>
A <firstterm>comment</firstterm>
is an arbitrary sequence of characters following double dashes up to the end
of the line. We also support double-slashes as comments, e.g.:
<programlisting>
-- This is a standard SQL comment
// And this is another supported comment style, like C++
</programlisting>
We also support C-style block comments, e.g.:
<programlisting>
/* multi
line
comment */
</programlisting>
</para>
</sect1>
<sect1>
<title>Names</title>
<para>
Names in SQL are sequences of less than NAMEDATALEN alphanumeric characters,
starting with an alphabetic character. By default, NAMEDATALEN is set
to 32, but at the time the system is built, NAMEDATALEN can be changed
by changing the #ifdef in src/backend/include/postgres.h. Underscore
("_") is considered an alphabetic character.
</para>
</sect1>
<sect1>
<title>Constants</title>
<para>
There are six types of
<firstterm>constants</firstterm>
for use in SQL. They are described below.
</para>
<sect2>
<title>String Constants</title>
<para>
<firstterm>Strings</firstterm>
in SQL are arbitrary sequences of ASCII characters bounded by single
quotes ("'", e.g. 'This is a string').
Uppercase alphabetics within strings are accepted
literally. Non-printing characters may be embedded within strings by
prepending them with a backslash
("\"; e.g. "\<replaceable>tab</replaceable>".
SQL92 allows single quotes to be embedded in strings by typing two
adjacent single quotes (e.g. 'Dianne''s horse'), and for
historical reasons <productname>Postgres</productname> also allows
single quotes to be escaped with a backslash
(e.g. 'Dianne\'s horse').
</para>
<para>
Because of the limitations on
instance sizes, string constants are currently limited to a length of
a little less than 8192 bytes. Larger strings may be handled using the
Postgres Large Object interface.
</para>
</sect2>
<sect2>
<title>Integer Constants</title>
<para>
<firstterm>Integer constants</firstterm>
in SQL are collection of ASCII digits with no decimal point. Legal
values range from -2147483648 to +2147483647. This will vary
depending on the operating system and host machine.
</para>
</sect2>
<sect2>
<title>Floating Point Constants</title>
<para>
<firstterm>Floating point constants</firstterm>
consist of an integer part, a decimal point, and a fraction part or
scientific notation of the following format:
<synopsis>
{<replaceable>dig</replaceable>}.{<replaceable>dig</replaceable>} [e [+-] {<replaceable>dig</replaceable>}]
</synopsis>
where <replaceable>dig</replaceable> is one or more digits.
You must include at least one <replaceable>dig</replaceable> 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 float8.
</para>
</sect2>
<sect2>
<title>Constants of Postgres User-Defined Types</title>
<para>
A constant of an
<emphasis>arbitrary</emphasis>
type can be entered using the notations:
<synopsis>
<replaceable>type</replaceable> '<replaceable>string</replaceable>'
'<replaceable>string</replaceable>'::<replaceable>type</replaceable>
CAST '<replaceable>string</replaceable>' AS <replaceable>type</replaceable>
</synopsis>
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.
</para>
</sect2>
<sect2>
<title>Array constants</title>
<para>
<firstterm>Array constants</firstterm>
are arrays of any Postgres type, including other arrays, string
constants, etc. The general format of an array constant is the
following:
<synopsis>
{<replaceable>val1</replaceable><replaceable>delim</replaceable><replaceable>val2</replaceable><replaceable>delim</replaceable>}
</synopsis>
where <replaceable>delim</replaceable>
is the delimiter for the type stored in the <literal>pg_type</literal> class.
(For built-in types, this is the comma character (","). An
example of an array constant is
<programlisting>
{{1,2,3},{4,5,6},{7,8,9}}
</programlisting>
This constant is a two-dimensional, 3 by 3 array consisting of three
sub-arrays of integers.
</para>
<para>
Individual array elements can and should be placed between quotation
marks whenever possible to avoid ambiguity problems with respect to
leading white space.
</para>
</sect2>
</sect1>
<sect1>
<title>Fields and Columns</title>
<sect2>
<title>Fields</title>
<para>
A <firstterm>field</firstterm>
is either an attribute of a given class or one of the following:
<variablelist>
<varlistentry>
<term>oid</term>
<listitem>
<para>
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.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>xmin</term>
<listitem>
<para>
The identity of the inserting transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>xmax</term>
<listitem>
<para>
The identity of the deleting transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>cmin</term>
<listitem>
<para>
The command identifier within the transaction.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>cmax</term>
<listitem>
<para>
The identity of the deleting command.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
For further information on these fields consult
<xref linkend="STON87a" endterm="STON87a">.
Times are represented internally as instances of the
<literal>abstime</literal>
data type. Transaction and command identifiers are 32 bit quantities.
Transactions are assigned sequentially starting at 512.
</para>
</sect2>
<sect2>
<title>Columns</title>
<para>
A <firstterm>column</firstterm> is a construct of the form:
<synopsis>
<replaceable>instance</replaceable>{.<replaceable>composite_field</replaceable>}.<replaceable>field</replaceable> `['<replaceable>number</replaceable>`]'
</synopsis>
<replaceable>instance</replaceable>
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 FROM clause,
or the keyword NEW or 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.
<replaceable>composite_field</replaceable>
is a field of of one of the Postgres composite types,
while successive composite fields address attributes in the
class(s) to which the composite field evaluates. Lastly,
<replaceable>field</replaceable>
is a normal (base type) field in the class(s) last addressed. If
<replaceable>field</replaceable>
is of type <literal>array</literal>,
then the optional <replaceable>number</replaceable>
designator indicates a specific element in the array. If no number is
indicated, then all array elements are returned.
</para>
</sect2>
</sect1>
<sect1>
<title>Operators</title>
<para>
Any built-in system, or user-defined operator may be used in SQL.
For the list of built-in and system operators consult
<xref linkend="operators" endterm="operators">.
For a list of user-defined operators consult your system administrator
or run a query on the <literal>pg_operator</literal> class.
Parentheses may be used for arbitrary grouping of operators in expressions.
</para>
</sect1>
<sect1>
<title>Expressions</title>
<para>
<acronym>SQL92</acronym> allows <firstterm>expressions</firstterm>
to transform data in expressions. Expressions may contain operators
to transform data in tables. Expressions may contain operators
(see <xref linkend="operators-title" endterm="operators-title">
for more details) and functions
(<xref linkend="functions-title" endterm="functions-title"> has
more information).
</para>
<para>
An expression is one of the following:
<simplelist>
<member>( a_expr )</member>
<member>constant</member>
<member>attribute</member>
<member><replaceable>a_expr</replaceable> <replaceable>binary_operator</replaceable> <replaceable>a_expr</replaceable></member>
<member><replaceable>a_expr</replaceable> <replaceable>right_unary_operator</replaceable></member>
<member><replaceable>left_unary_operator</replaceable> <replaceable>a_expr</replaceable></member>
<member>parameter</member>
<member>functional expressions</member>
<member>aggregate expressions</member>
</simplelist>
</para>
<para>
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.
</para>
<sect2>
<title>Parameters</title>
<para>
A <firstterm>parameter</firstterm>
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:
<synopsis>
$<replaceable class="parameter">number</replaceable>
</synopsis>
</para>
<para>
For example, consider the definition of a function,
<function>dept</function>, as
<programlisting>
CREATE FUNCTION dept (name)
RETURNS dept
AS 'select * from
dept where name=$1'
LANGUAGE 'sql';
</programlisting>
</para>
</sect2>
<sect2>
<title>Functional Expressions</title>
<para>
A <firstterm>functional expression</firstterm>
is the name of a legal SQL function, followed by its argument list
enclosed in parentheses:
<synopsis>
<replaceable>function</replaceable> (<replaceable>a_expr</replaceable> [, <replaceable>a_expr</replaceable> )
</synopsis>
</para>
<para>
For example, the following computes the square root of an employee
salary:
<programlisting>
sqrt(emp.salary)
</programlisting>
</para>
</sect2>
<sect2>
<title>Aggregate Expression</title>
<para>
An <firstterm>aggregate expression</firstterm>
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:
<synopsis>
<replaceable>aggregate_name</replaceable> (<replaceable>attribute</replaceable>)
</synopsis>
where <replaceable>aggregate_name</replaceable>
must be a previously defined aggregate.
</para>
</sect2>
<sect2>
<title>Target List</title>
<para>
A <firstterm>target list</firstterm>
is a parenthesized, comma-separated list of one or more elements, each
of which must be of the form:
<synopsis>
<replaceable>a_expr</replaceable> [ AS <replaceable>result_attname</replaceable> ]
</synopsis>
where <replaceable>result_attname</replaceable>
is the name of the attribute to be created (or an
already existing attribute name in the case of update statements.) If
<replaceable>result_attname</replaceable>
is not present, then
<replaceable>a_expr</replaceable>
must contain only one attribute name which is assumed to be the name
of the result field. In <productname>Postgres</productname>
default naming is only used if
<replaceable>a_expr</replaceable>
is an attribute.
</para>
</sect2>
<sect2>
<title>Qualification</title>
<para>
A <firstterm>qualification</firstterm>
consists of any number of clauses connected by the logical operators:
<simplelist>
<member>NOT</member>
<member>AND</member>
<member>OR</member>
</simplelist>
A clause is an <replaceable>a_expr</replaceable>
that evaluates to a <literal>boolean</literal> over a set of instances.
</para>
</sect2>
<sect2>
<title>From List</title>
<para>
The <firstterm>from list</firstterm>
is a comma-separated list of <firstterm>from expressions</firstterm>.
Each "from expression" is of the form:
<synopsis>
[ <replaceable>class_reference</replaceable> ] <replaceable>instance_variable</replaceable>
{, [ <replaceable>class_ref</replaceable> ] <replaceable>instance_variable</replaceable>... }
</synopsis>
where <replaceable>class_reference</replaceable>
is of the form
<synopsis>
<replaceable>class_name</replaceable> [ * ]
</synopsis>
The "from expression"
defines one or more instance variables to range over the class
indicated in <replaceable>class_reference</replaceable>.
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 asterisk ("*").
</para>
</sect2>
</sect1>
</chapter>

57
doc/src/sgml/user.sgml
View File

@ -1,56 +1,3 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/Attic/user.sgml,v 1.12 1999/06/03 04:21:51 thomas Exp $
Postgres User's Manual.
Derived from postgres.sgml.
thomas 1998-02-24
$Log: user.sgml,v $
Revision 1.12 1999/06/03 04:21:51 thomas
Markup changes for v6.5 release.
Clean out duplicate stuff in odbc.sgml resulting from a faulty patch.
Revision 1.11 1999/05/26 17:30:30 thomas
Add chapters on CVS access, MVCC, SQL theory to the docs.
Add an appendix with more details on date/time attributes and handling.
Update most references to Postgres version numbers to 6.5,
*except* for the porting list which will require a report
from a successful installation to be updated.
Revision 1.10 1999/05/22 02:27:25 thomas
Finish initial markup of cvs.sgml, and include it in the programmer's guide
and the integrated doc. Clean up other markup.
Revision 1.9 1999/05/20 05:39:29 thomas
Rearrange and consolidate the Admin Guide.
Add reference pages for utilities and remove standalone chapters for same.
Add material for an appendix on date/time properties, but not yet
integrated with the User's Guide.
Break up the former chapter on pg_options
into Admin and Programmer's Guides.
Revision 1.8 1999/05/04 02:26:06 thomas
Include new introductory chapter on SQL from Stefan S.
Should this be in the tutorial instead?
Revision 1.7 1998/10/30 19:37:16 thomas
Minor editing and markup changes as a result of preparing the Postscript
documentation for v6.4.
Bigger updates to the installation instructions (install and config).
Revision 1.6 1998/09/30 05:41:54 thomas
Clean up pages. Add information for operator precedence.
Split introduction sections into separate files to allow the legal notice
and notation sections appear in all documents without having the history
show up everplace too.
Add full list of reserved and non-reserved key words in syntax.sgml.
Add a separate chapter to the admin guide on security.
Revision 1.5 1998/08/17 16:20:32 thomas
Move SQL reference pages up into the User's Guide.
-->
<!doctype book PUBLIC "-//Davenport//DTD DocBook V3.0//EN" [
<!entity about SYSTEM "about.sgml">
@ -67,9 +14,9 @@ Move SQL reference pages up into the User's Guide.
<!entity datetime SYSTEM "datetime.sgml">
<!entity environ SYSTEM "environ.sgml">
<!entity func SYSTEM "func.sgml">
<!entity indices SYSTEM "indices.sgml">
<!entity inherit SYSTEM "inherit.sgml">
<!entity intro SYSTEM "intro.sgml">
<!entity keys SYSTEM "keys.sgml">
<!entity manage SYSTEM "manage.sgml">
<!entity mvcc SYSTEM "mvcc.sgml">
<!entity oper SYSTEM "oper.sgml">
@ -157,7 +104,7 @@ Your name here...
&oper;
&func;
&typeconv;
&keys;
&indices;
&array;
&inherit;
&mvcc;

1047
doc/src/sgml/xfunc.sgml
View File

File diff suppressed because it is too large Load Diff

5
doc/src/sgml/xindex.sgml
View File

@ -1,3 +1,8 @@
<!--
$Header: /cvsroot/pgsql/doc/src/sgml/xindex.sgml,v 1.5 1999/07/22 15:11:05 thomas Exp $
Postgres documentation
-->
<chapter id="xindex">
<title>Interfacing Extensions To Indices</title>

1486
doc/src/sgml/xplang.sgml
View File

File diff suppressed because it is too large Load Diff