Skip to content

P
Postgres FD Implementation
Commit 59bb41a2 authored by Marc G. Fournier's avatar Marc G. Fournier
Browse files
Options

Import of PostgreSQL User Manual

parent f02bd933
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 4701 additions and 0 deletions
doc/manual/admin.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/advanced.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - ADVANCED POSTGRES SQL FEATURES</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="query.html">[ Previous ]</A>
<A HREF="extend.html">[ Next ]</A>
</font>
<HR>
<H1>5. ADVANCED POSTGRES <B>SQL</B> FEATURES</H1>
<HR>
Having covered the basics of using POSTGRES <B>SQL</B> to
access your data, we will now discuss those features of
POSTGRES that distinguish it from conventional data
managers. These features include inheritance, time
travel and non-atomic data values (array- and
set-valued attributes).
Examples in this section can also be found in
<CODE>advance.sql</CODE> in the tutorial directory. (Refer to the
introduction of the <A HREF="query.html">previous chapter</A> for how to use
it.)
<H2><A NAME="inheritance">5.1. Inheritance</A></H2>
Let's create two classes. The capitals class contains
state capitals which are also cities. Naturally, the
capitals class should inherit from cities.
<pre> CREATE TABLE cities (
name text,
population float,
altitude int -- (in ft)
);
CREATE TABLE capitals (
state char2
) INHERITS (cities);
</pre>
In this case, an instance of capitals <B>inherits</B> all
attributes (name, population, and altitude) from its
parent, cities. The type of the attribute name is
<B>text</B>, a built-in POSTGRES type for variable length
ASCII strings. The type of the attribute population is
<B>float4</B>, a built-in POSTGRES type for double precision
floating point numbres. State capitals have an extra
attribute, state, that shows their state. In POSTGRES,
a class can inherit from zero or more other classes,<A HREF="#4"><font size=-1>[4]</font></A>
and a query can reference either all instances of a
class or all instances of a class plus all of its
descendants. For example, the following query finds
all the cities that are situated at an attitude of 500
'ft or higher:
<pre> SELECT name, altitude
FROM cities
WHERE altitude &gt; 500;
+----------+----------+
|name | altitude |
+----------+----------+
|Las Vegas | 2174 |
+----------+----------+
|Mariposa | 1953 |
+----------+----------+
</pre>
On the other hand, to find the names of all cities,
including state capitals, that are located at an altitude
over 500 'ft, the query is:
<pre> SELECT c.name, c.altitude
FROM cities&#42; c
WHERE c.altitude &gt; 500;
</pre>
which returns:
<pre> +----------+----------+
|name | altitude |
+----------+----------+
|Las Vegas | 2174 |
+----------+----------+
|Mariposa | 1953 |
+----------+----------+
|Madison | 845 |
+----------+----------+
</pre>
Here the &#42; after cities indicates that the query should
be run over cities and all classes below cities in the
inheritance hierarchy. Many of the commands that we
have already discussed -- select, update and delete --
support this &#42; notation, as do others, like alter command.
<H2><A NAME="time-travel">5.2. Time Travel</A></H2>
POSTGRES supports the notion of time travel. This feature
allows a user to run historical queries. For
example, to find the current population of Mariposa
city, one would query:
<pre> SELECT &#42; FROM cities WHERE name = 'Mariposa';
+---------+------------+----------+
|name | population | altitude |
+---------+------------+----------+
|Mariposa | 1320 | 1953 |
+---------+------------+----------+
</pre>
POSTGRES will automatically find the version of Mariposa's
record valid at the current time.
One can also give a time range. For example to see the
past and present populations of Mariposa, one would
query:
<pre> SELECT name, population
FROM cities['epoch', 'now']
WHERE name = 'Mariposa';
</pre>
where "epoch" indicates the beginning of the system
clock.<A HREF="#5"><font size=-1>[5]</font></A> If you have executed all of the examples so
far, then the above query returns:
<pre> +---------+------------+
|name | population |
+---------+------------+
|Mariposa | 1200 |
+---------+------------+
|Mariposa | 1320 |
+---------+------------+
</pre>
The default beginning of a time range is the earliest
time representable by the system and the default end is
the current time; thus, the above time range can be
abbreviated as ``[,].''
<H2><A NAME="non-atomic-values">5.3. Non-Atomic Values</A></H2>
One of the tenets of the relational model is that the
attributes of a relation are atomic. POSTGRES does not
have this restriction; attributes can themselves contain
sub-values that can be accessed from the query
language. For example, you can create attributes that
are arrays of base types.
<H3><A NAME="arrays">5.3.1. Arrays</A></H3>
POSTGRES allows attributes of an instance to be defined
as fixed-length or variable-length multi-dimensional
arrays. Arrays of any base type or user-defined type
can be created. To illustrate their use, we first create a
class with arrays of base types.
<pre> &#42; CREATE TABLE SAL_EMP (
name text,
pay_by_quarter int4[],
schedule char16[][]
);
</pre>
The above query will create a class named SAL_EMP with
a <B>text</B> string (name), a one-dimensional array of <B>int4</B>
(pay_by_quarter), which represents the employee's
salary by quarter and a two-dimensional array of <B>char16</B>
(schedule), which represents the employee's weekly
schedule. Now we do some <B>INSERTS</B>s; note that when
appending to an array, we enclose the values within
braces and separate them by commas. If you know <B>C</B>,
this is not unlike the syntax for initializing structures.
<pre> INSERT INTO SAL_EMP
VALUES ('Bill',
'{10000, 10000, 10000, 10000}',
'{{"meeting", "lunch"}, {}}');
INSERT INTO SAL_EMP
VALUES ('Carol',
'{20000, 25000, 25000, 25000}',
'{{"talk", "consult"}, {"meeting"}}');
</pre>
By default, POSTGRES uses the "one-based" numbering
convention for arrays -- that is, an array of n elements starts with array[1] and ends with array[n].
Now, we can run some queries on SAL_EMP. First, we
show how to access a single element of an array at a
time. This query retrieves the names of the employees
whose pay changed in the second quarter:
<pre> &#42; SELECT name
FROM SAL_EMP
WHERE SAL_EMP.pay_by_quarter[1] &lt;&gt;
SAL_EMP.pay_by_quarter[2];
+------+
|name |
+------+
|Carol |
+------+
</pre>
This query retrieves the third quarter pay of all
employees:
<pre> &#42; SELECT SAL_EMP.pay_by_quarter[3] FROM SAL_EMP;
+---------------+
|pay_by_quarter |
+---------------+
|10000 |
+---------------+
|25000 |
+---------------+
</pre>
We can also access arbitrary slices of an array, or
subarrays. This query retrieves the first item on
Bill's schedule for the first two days of the week.
<pre> &#42; SELECT SAL_EMP.schedule[1:2][1:1]
FROM SAL_EMP
WHERE SAL_EMP.name = 'Bill';
+-------------------+
|schedule |
+-------------------+
|{{"meeting"},{""}} |
+-------------------+
</pre>
<p>
<HR>
<A NAME="4"><B>4.</B></A> i.e., the inheritance hierarchy is a directed acyclic
graph.<br>
<A NAME="5"><B>5.</B></A> On UNIX systems, this is always midnight, January 1,
1970 GMT.<br>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="query.html">[ Previous ]</A>
<A HREF="extend.html">[ Next ]</A>
</font>
doc/manual/appenda.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - Appendix A:</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="refs.html">[ Previous ]</A>
[ Next ]
</font>
<HR>
<H1>Appendix A: Linking Dynamically-Loaded Functions</H1>
<HR>
After you have created and registered a user-defined
function, your work is essentially done. POSTGRES,
however, must load the object code (e.g., a .o file, or
a shared library) that implements your function. As
previously mentioned, POSTGRES loads your code at
runtime, as required. In order to allow your code to be
dynamically loaded, you may have to compile and
linkedit it in a special way. This section briefly
describes how to perform the compilation and
linkediting required before you can load your user-defined
functions into a running POSTGRES server. Note that
this process has changed as of Version 4.2.<A HREF="#11">11</A> 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
/usr/local/postgres95/src/regress 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:
<DL>
<DT>Dynamic loading
<DD>is what POSTGRES does to an object file. The
object file is copied into the running POSTGRES
server and the functions and variables within the
file are made available to the functions within
the POSTGRES process. POSTGRES does this using
the dynamic loading mechanism provided by the
operating system.
<DT>Loading and link editing
<DD>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).
</DL>
<p>
The following general restrictions and notes also apply
to the discussion below.
<UL>
<LI>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
POSTGRES server is running.<A HREF="#12">12</A>
<LI>The POSTGRES 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 POSTGRES
server runs as the POSTGRES 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.)
<LI>Symbol names defined within object files must not
conflict with each other or with symbols defined in
POSTGRES.
<LI>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.
</UL>
<p>
<B>ULTRIX</B><br>
It is very easy to build dynamically-loaded object
files under ULTRIX. ULTRIX does not have any sharedlibrary
mechanism and hence does not place any restrictions on
the dynamic loader interface. On the other
hand, we had to (re)write a non-portable dynamic loader
ourselves and could not use true shared libraries.
Under ULTRIX, the only restriction is that you must
produce each object file with the option -G 0. (Notice
that that's the numeral ``0'' and not the letter
``O''). For example,
<pre> # simple ULTRIX example
&#37; cc -G 0 -c foo.c
</pre>
produces an object file called foo.o that can then be
dynamically loaded into POSTGRES. No additional loading or link-editing must be performed.
<p>
<B>DEC OSF/1</B><br>
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:
<pre> # simple DEC OSF/1 example
&#37; cc -c foo.c
&#37; ld -shared -expect_unresolved '&#42;' -o foo.so foo.o
</pre>
The resulting shared object file can then be loaded
into POSTGRES. 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.<A HREF="#13">13</A> If the file you specify is
not a shared object, the backend will hang!
<p>
<B>SunOS 4.x, Solaris 2.x and HP-UX</B><br>
Under both 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
must be produced.
The necessary steps with HP-UX are as follows. The +z
flag to the HP-UX C compiler produces so-called
"Position Independent Code" (PIC) and the +u flag
removes
some alignment restrictions that the PA-RISC architecture
normally enforces. The object file must be turned
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:
<pre> # simple HP-UX example
&#37; cc +z +u -c foo.c
&#37; ld -b -o foo.sl foo.o
</pre>
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:
<pre> # simple SunOS 4.x example
&#37; cc -PIC -c foo.c
&#37; ld -dc -dp -Bdynamic -o foo.so foo.o
</pre>
and the equivalent lines under Solaris 2.x are:
<pre> # simple Solaris 2.x example
&#37; cc -K PIC -c foo.c
or
&#37; gcc -fPIC -c foo.c
&#37; ld -G -Bdynamic -o foo.so foo.o
</pre>
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.
<HR>
<A NAME="11"><B>11.</B></A> The old POSTGRES 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
POSTGRES 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.
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 POSTGRES. We
hope that the large increase in speed and reliability will
make up for the slight decrease in convenience.
<hr width=50 align=left>
<A NAME="12"><B>12.</B></A> Relative paths do in fact work,
but are relative to
the directory where the database resides (which is generally
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!<br>
<hr width=50 align=left>
<A NAME="13"><B>13.</B></A> Actually, POSTGRES 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 POSTGRES 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
pragmatic point of view, we discourage this practice because
you will undoubtedly confuse yourself with regards to which
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!<br>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="refs.html">[ Previous ]</A>
[ Next ]
</font>
</BODY>
</HTML>
doc/manual/architec.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - ARCHITECTURE</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="intro.html">[ Previous ]</A>
<A HREF="start.html">[ Next ]</A>
</font>
<HR>
<H1>2. POSTGRES ARCHITECTURE CONCEPTS</H1>
<HR>
Before we continue, you should understand the basic
POSTGRES system architecture. Understanding how the
parts of POSTGRES interact will make the next chapter
somewhat clearer.
In database jargon, POSTGRES uses a simple "process
per-user" client/server model. A POSTGRES session
consists of the following cooperating UNIX processes (programs):
<UL>
<LI>A supervisory daemon process (the <B>postmaster</B>),
<LI>the user's frontend application (e.g., the <B>psql</B> program), and
<LI>the one or more backend database servers (the <B>postgres</B> process itself).
</UL>
A single <B>postmaster</B> manages a given collection of
databases on a single host. Such a collection of
databases is called an installation or site. Frontend
applications that wish to access a given database
within an installation make calls to the library.
The library sends user requests over the network to the
<B>postmaster</B> (Figure 1(a)), which in turn starts a new
backend server process (Figure 1(b))
<IMG SRC="figure01.gif" ALIGN=right ALT="Figure 1- How a connection is established"><br>
and connects the
frontend process to the new server (Figure 1(c)). From
that point on, the frontend process and the backend
server communicate without intervention by the
<B>postmaster</B>. Hence, the <B>postmaster</B> is always running, waiting
for requests, whereas frontend and backend processes
come and go. The <B>LIBPQ</B> library allows a single
frontend to make multiple connections to backend processes.
However, the frontend application is still a
single-threaded process. Multithreaded frontend/backend
connections are not currently supported in <B>LIBPQ</B>.
One implication of this architecture is that the
<B>postmaster</B> and the backend always run on the same
machine (the database server), while the frontend
application may run anywhere. You should keep this
in mind,
because the files that can be accessed on a client
machine may not be accessible (or may only be accessed
using a different filename) on the database server
machine.
You should also be aware that the <B>postmaster</B> and
postgres servers run with the user-id of the POSTGRES
"superuser." Note that the POSTGRES superuser does not
have to be a special user (e.g., a user named
"postgres"). Furthermore, the POSTGRES superuser
should
definitely not be the UNIX superuser, "root"! In any
case, all files relating to a database should belong to
this POSTGRES superuser.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="intro.html">[ Previous ]</A>
<A HREF="start.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/copy.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 - Copyright</TITLE>
</HEAD>
<BODY>
<H1 align=center>The <B>POSTGRES95</B> - Copyright</H1>
<HR>
<B>POSTGRES95</B> is copyright (C) 1994-5 by the Regents of the
University of California. Permission to use, copy, modify,
and distribute this software and its documentation for any
purpose, without fee, and without a written agreement is
hereby granted, provided that the above copyright notice and
this paragraph and the following two paragraphs appear in
all copies.<p>
<b> IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE
LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL,
INCIDENTAL, OR CONSEQUENTIAL DAMAGES, INCLUDING LOST
PROFITS, ARISING OUT OF THE USE OF THIS SOFTWARE AND
ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF CALIFORNIA
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
THE UNIVERSITY OF CALIFORNIA SPECIFICALLY
DISCLAIMS ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
FOR A PARTICULAR PURPOSE. THE SOFTWARE PROVIDED
HEREUNDER IS ON AN "AS IS" BASIS, AND THE UNIVERSITY OF
CALIFORNIA HAS NO OBLIGATIONS TO PROVIDE MAINTENANCE,
SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
</b>
</BODY>
</HTML>
doc/manual/extend.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - EXTENDING SQL: AN OVERVIEW</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="advanced.html">[ Previous ]</A>
<A HREF="xfunc.html">[ Next ]</A>
</font>
<HR>
<H1>6. EXTENDING SQL: AN OVERVIEW</H1>
<HR>
In the sections that follow, we will discuss how you
can extend the POSTGRES <B>SQL</B> query language by adding:
<UL>
<LI>functions
<LI>types
<LI>operators
<LI>aggregates
</UL>
<p>
<H2><A NAME="how-extensibility-works">6.1. How Extensibility Works</A></H2>
POSTGRES 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 DBMS stores
its internal bookkeeping in them. One key difference
between POSTGRES and standard relational systems is
that POSTGRES 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 POSTGRES bases its internal operation
on these classes, this means that POSTGRES can be
extended by users. By comparison, conventional
database systems can only be extended by changing hardcoded
procedures within the DBMS or by loading modules
specially-written by the DBMS vendor.
POSTGRES 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 POSTGRES will load it as required. Code written
in <B>SQL</B> are even more trivial to add to the server.
This ability to modify its operation "on the fly" makes
POSTGRES uniquely suited for rapid prototyping of new
applications and storage structures.
<H2><A NAME="the-postgres-type-system">6.2. The POSTGRES Type System</A></H2>
The POSTGRES type system can be broken down in several
ways.
Types are divided into base types and composite types.
Base types are those, like <CODE>int4</CODE>, that are implemented
in a language such as <B>C</B>. They generally correspond to
what are often known as "abstract data types"; POSTGRES
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.
POSTGRES 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.
POSTGRES base types are further divided into built-in
types and user-defined types. Built-in types (like
<CODE>int4</CODE>) are those that are compiled into the system.
User-defined types are those created by the user in the
manner to be described below.
<H2><A NAME="about-the-postgres-system-catalogs">6.3. About the POSTGRES System Catalogs</A></H2>
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 <CODE>pg_</CODE>.
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.)
<p>
<center>
<table border=1>
<tr>
<th>catalog name</th><th> description </th>
</tr>
<tr>
<td><CODE>pg_database</CODE> </td><td> databases </td>
</tr>
<tr>
<td><CODE>pg_class</CODE> </td><td> classes </td>
</tr>
<tr>
<td><CODE>pg_attribute</CODE> </td><td> class attributes </td>
</tr>
<tr>
<td><CODE>pg_index</CODE> </td><td> secondary indices </td>
</tr>
<tr>
</tr>
<tr>
<td><CODE>pg_proc</CODE> </td><td> procedures (both C and SQL) </td>
</tr>
<tr>
<td><CODE>pg_type</CODE> </td><td> types (both base and complex) </td>
</tr>
<tr>
<td><CODE>pg_operator</CODE> </td><td> operators </td>
</tr>
<tr>
<td><CODE>pg_aggregate</CODE> </td><td> aggregates and aggregate functions </td>
</tr>
<tr>
</tr>
<tr>
</tr>
<tr>
<td><CODE>pg_am</CODE> </td><td> access methods </td>
</tr>
<tr>
<td><CODE>pg_amop</CODE> </td><td> access method operators </td>
</tr>
<tr>
<td><CODE>pg_amproc</CODE> </td><td> access method support functions </td>
</tr>
<tr>
<td><CODE>pg_opclass</CODE> </td><td> access method operator classes </td>
</tr>
</table>
</center>
<p>
<IMG SRC="figure03.gif"
ALT="Figure 3. The major POSTGRES system catalogs">
The Reference Manual gives a more detailed explanation
of these catalogs and their attributes. However, Figure 3
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:
<OL>
<LI> 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.
<LI> 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.
<LI> Types and procedures <A HREF="#6"><font size=-1>[6]</font></A>
are central to the schema.
Nearly every catalog contains some reference to
instances in one or both of these classes. For
example, POSTGRES frequently uses type
signatures (e.g., of functions and operators) to
identify unique instances of other catalogs.
<LI> 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
<CODE>pg_am, pg_amop, pg_amproc, pg_operator</CODE> and
<CODE>pg_opclass</CODE> 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.
</OL>
<p>
<HR>
<A NAME="6"><B>6.</B></A> We use the words <I>procedure</I> and <I>function</I> more or less
interchangably.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="advanced.html">[ Previous ]</A>
<A HREF="xfunc.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/intro.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - Introduction</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
[ Previous ]
<A HREF="architec.html">[ Next ]</A>
</font>
<HR>
<H1>1. INTRODUCTION</H1>
<HR>
This document is the user manual for the
<A HREF="http://s2k-ftp.cs.berkeley.edu:8000/postgres95/"><B>POSTGRES95</B></A>
database management system developed at the University
of California at Berkeley. <B>POSTGRES95</B> is based on
<A HREF="http://s2k-ftp.CS.Berkeley.EDU:8000/postgres/postgres.html">
<B>POSTGRES release 4.2</B></A>. The POSTGRES project,
led by Professor Michael Stonebraker, has been sponsored by the
Defense Advanced Research Projects Agency (DARPA), the
Army Research Office (ARO), the National Science
Foundation (NSF), and ESL, Inc.
<H2>1.1. What is POSTGRES?</H2>
Traditional relational database management systems
(DBMSs) support a data model consisting of a collection
of named relations, containing attributes of a specific
type. In current commercial systems, possible types
include floating point numbers, integers, character
strings, money, and dates. It is commonly recognized
that this model is inadequate for future data
processing applications.
The relational model successfully replaced previous
models in part because of its "Spartan simplicity".
However, as mentioned, this simplicity often makes the
implementation of certain applications very difficult
to implement. POSTGRES offers substantial additional
power by incorporating the following four additional
basic constructs in such a way that users can easily
extend the system:
<p>
<PRE> classes
inheritance
types
functions
</PRE><p>
In addition, POSTGRES supports a powerful production
rule system.
<H2><A NAME="a-short-history-of-the-postgres-project">1.2. A Short History of the POSTGRES Project</A></H2>
Implementation of the POSTGRES DBMS began in 1986. The
initial concepts for the system were presented in
<A HREF="refs.html#STON86">[STON86]</A> and the definition of the initial data model
appeared in <A HREF="refs.html#ROW87">[ROWE87]</A>. The design of the rule system at
that time was described in <A HREF="refs.html#STON87a">[STON87a]</A>. The rationale
and architecture of the storage manager were detailed
in <A HREF="refs.html#STON87b">[STON87b]</A>.
POSTGRES has undergone several major releases since
then. The first "demoware" system became operational
in 1987 and was shown at the 1988 <B>ACM-SIGMOD</B>
Conference. We released Version 1, described in <A HREF="refs.html#STON90a">[STON90a]</A>,
to a few external users in June 1989. In response to a
critique of the first rule system <A HREF="refs.html#STON89">[STON89]</A>, the rule
system was redesigned <A HREF="refs.html#STON90">[STON90b]</A> and Version 2 was
released in June 1990 with the new rule system.
Version 3 appeared in 1991 and added support for multiple
storage managers, an improved query executor, and a
rewritten rewrite rule system. For the most part,
releases since then have focused on portability and
reliability.
POSTGRES has been used to implement many different
research and production applications. These include: a
financial data analysis system, a jet engine
performance monitoring package, an asteroid tracking
database, a medical information database, and several
geographic information systems. POSTGRES has also been
used as an educational tool at several universities.
Finally, <A HREF="http://www.illustra.com/">Illustra Information Technologies</A> picked up
the code and commercialized it.
POSTGRES became the primary data manager for the
<A HREF="http://www.sdsc.edu/0/Parts_Collabs/S2K/s2k_home.html">Sequoia 2000</A> scientific computing project in late 1992.
Furthermore, the size of the external user community
nearly doubled during 1993. It became increasingly
obvious that maintenance of the prototype code and
support was taking up large amounts of time that should
have been devoted to database research. In an effort
to reduce this support burden, the project officially
ended with <B>Version 4.2</B>.
<H2><A NAME="what-is-postgres95">1.3. What is <B>POSTGRES95</B>?</A></H2>
<B>POSTGRES95</B> is a derivative of the last official release
of POSTGRES (version 4.2). The code is now completely
ANSI C and the code size has been trimmed by 25&#37;. There
are a lot of internal changes that improve performance
and code maintainability. <B>POSTGRES95</B> runs about 30-50&#37;
faster on the Wisconsin Benchmark compared to v4.2.
Apart from bug fixes, these are the major enhancements:
<UL>
<LI>The query language <B>POSTQUEL</B> has been replaced with
<B>SQL</B> (implemented in the server). We do not support
subqueries (which can be imitated with user defined
<B>SQL</B> functions) at the moment. Aggregates have been
re-implemented. We also added support for <B>GROUP BY</B>.
The <B>libpq</B> interface is still available for <B>C</B>
programs.
<LI>In addition to the monitor program, we provide a new
program (<B>psql</B>) which supports <B>GNU</B> <B>readline</B>.
<LI>We added a new front-end library, <B>libpgtcl</B>, that
supports <B>Tcl</B>-based clients. A sample shell,
pgtclsh, provides new Tcl commands to interface <B>tcl</B>
programs with the <B>POSTGRES95</B> backend.
<LI>The large object interface has been overhauled. We
kept Inversion large objects as the only mechanism
for storing large objects. (This is not to be
confused with the Inversion file system which has been
removed.)
<LI>The instance-level rule system has been removed.
<LI>Rules are still available as rewrite rules.
<LI>A short tutorial introducing regular <B>SQL</B> features as
well as those of ours is distributed with the source
code.
<LI><B>GNU</B> make (instead of <B>BSD</B> make) is used for the
build. Also, <B>POSTGRES95</B> can be compiled with an
unpatched <B>gcc</B> (data alignment of doubles has been
fixed).
</UL>
<p>
<H2><A NAME="about-this-release">1.4. About This Release</A></H2>
<B>POSTGRES95</B> is available free of charge. This manual
describes version 1.0 of <B>POSTGRES95</B>. The authors have
compiled and tested <B>POSTGRES95</B> on the following
platforms:
<p>
<center>
<table border=4>
<tr>
<th>Architecture</th>
<th>Processor</th>
<th>Operating System</th>
</tr>
<tr>
<td>DECstation 3000</td>
<td>Alpha AXP</td>
<td>OSF/1 2.1, 3.0, 3.2</td>
</tr>
<tr>
<td>DECstation 5000</td>
<td>MIPS</td>
<td>ULTRIX 4.4</td>
</tr>
<tr>
<td>Sun4</td>
<td>SPARC</td>
<td>SunOS 4.1.3, 4.1.3_U1; Solaris 2.4</td>
</tr>
<tr>
<td>H-P 9000/700 and 800</td>
<td>PA-RISC</td>
<td>HP-UX 9.00, 9.01, 9.03</td>
</tr>
<tr>
<td>Intel</td>
<td>X86</td>
<td>Linux 1.2.8, ELF</td>
</table>
</center>
<p>
<H2><A NAME="outline-of-this-manual">1.5. Outline of This Manual</A></H2>
From now on, We will use POSTGRES to mean <B>POSTGRES95</B>.
The first part of this manual goes over some basic sys-
tem concepts and procedures for starting the POSTGRES
system. We then turn to a tutorial overview of the
POSTGRES data model and SQL query language, introducing
a few of its advanced features. Next, we explain the
POSTGRES approach to extensibility and describe how
users can extend POSTGRES by adding user-defined types,
operators, aggregates, and both query language and pro-
gramming language functions. After an extremely brief
overview of the POSTGRES rule system, the manual
concludes with a detailed appendix that discusses some of
the more involved and operating system-specific
procedures involved in extending the system.
<HR>
<B>UNIX</B> is a trademark of X/Open, Ltd. Sun4, SPARC, SunOS
and Solaris are trademarks of Sun Microsystems, Inc. DEC,
DECstation, Alpha AXP and ULTRIX are trademarks of Digital
Equipment Corp. PA-RISC and HP-UX are trademarks of
Hewlett-Packard Co. OSF/1 is a trademark of the Open
Software Foundation.<p>
We assume proficiency with UNIX and C programming.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
[ Previous ]
<A HREF="architec.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/libpq.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/lobj.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/pg95user.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual</TITLE>
</HEAD>
<BODY>
<H1 align=center>
The <B>
<A HREF="http://s2k-ftp.cs.berkeley.edu:8000/postgres95/">
POSTGRES95</A></B> User Manual</H1>
<p align=CENTER>
Version 1.0 (September 5, 1995)<br><br>
<A HREF="http://s2k-ftp.cs.berkeley.edu:8000/personal/andrew">Andrew Yu</A>
and
<A HREF="http://http.cs.berkeley.edu/~jolly/">Jolly Chen</A><br>
(with the POSTGRES Group)<br>
Computer Science Div., Dept. of EECS<br>
University of California at Berkeley<br>
</p>
<!--#exec cgi="/cgi-bin/wais-pg95.pl"-->
<H1 align=center>Table of Contents</H1>
<DL>
<DT><A HREF="intro.html">1. INTRODUCTION</A>
<DL>
<DT><A HREF="intro.html#a-short-history-of-the-postgres-project">1.1. A Short History of POSTGRES</A>
<DT><A HREF="intro.html#what-is-postgres95">1.2. What is POSTGRES95?</A>
<DT><A HREF="intro.html#about-this-release">1.4. About This Release</A>
<DT><A HREF="intro.html#outline-of-this-manual">1.5. Outline of This Manual</A>
</DL>
<DT><A HREF="architec.html">2. ARCHITECTURE CONCEPTS</A>
<DT><A HREF="start.html">3. GETTING STARTED</A>
<DL>
<DT><A HREF="start.html#setting-up-your-environment">3.1. Setting Up Your Enviroment</A>
<DT><A HREF="start.html#starting-the-postmaster">3.2. Starting The Postmaster</A>
<DT><A HREF="start.html#adding-and-deleting-users">3.3. Adding And Deleting Users</A>
<DT><A HREF="start.html#starting-applications">3.4. Starting Applications</A>
<DT><A HREF="start.html#managing-a-database">3.5. Managing A Database</A>
<DL>
<DT><A HREF="start.html#creating-a-database">3.5.1. Creating A Database</A>
<DT><A HREF="start.html#accesssing-a-database">3.5.2. Accessing A Database</A>
<DT><A HREF="start.html#destroying-a-database">3.5.3. Destroying A Database</A>
</DL>
</DL>
<DT><A HREF="query.html">4. QUERY LANGUAGE</A>
<DL>
<DT><A HREF="query.html#concepts">4.1. Concepts</A>
<DT><A HREF="query.html#creating-a-new-class">4.2. Creating a New Class</A>
<DT><A HREF="query.html#populating-a-class-with-instances">4.3. Populating a Class with Instances</A>
<DT><A HREF="query.html#querying-a-class">4.4. Querying a Class</A>
<DT><A HREF="query.html#redirecting-select-queries">4.5. Redirecting SELECT Queries</A>
</DL>
<DT><A HREF="advanced.html">5. ADVANCED POSTGRES SQL FEATURES</A>
<DL>
<DT><A HREF="advanced.html#inheritance">5.1. Inheritance</A>
<DT><A HREF="advanced.html#time-travel">5.2. Time Travel</A>
<DT><A HREF="advanced.html#non-atomic-values">5.3. Non-Atomic Values</A>
<DL>
<DT><A HREF="advanced.html#arrays">5.3.1. Arrays</A>
</DL>
</DL>
<DT><A HREF="extend.html">6. EXTENDING SQL: AN OVERVIEW</A>
<DL>
<DT><A HREF="extend.html#how-extensibility-works">6.1. How Extensibility Works</A>
<DT><A HREF="extend.html#the-postgres-type-system">6.2. The POSTGRES Type System</A>
<DT><A HREF="extend.html#about-the-postgres-system-catalogs">6.3. About the POSTGRES System Catalogs</A>
</DL>
<DT><A HREF="xfunc.html">7. EXTENDING SQL: FUNCTIONS</A>
<DL>
<DT><A HREF="xfunc.html#query-language-sql-functions">7.1. Query Language (SQL) Functions</A>
<DL>
<DT><A HREF="xfunc.html#sql-functions-on-base-types">7.1.1. SQL Functions on Base Types</A>
</DL>
<DT><A HREF="xfunc.html#programming-language-functions">7.2. Programming Language Functions</A>
<DL>
<DT><A HREF="xfunc.html#programming-language-functions-on-base-types">7.2.1. Programming Language Functions on Base Types</A>
<DT><A HREF="xfunc.html#programming-language-functions-on-composite-types">7.2.2. Programming Language Functions on Composite Types</A>
<DT><A HREF="xfunc.html#caveats">7.2.3. Caveats</A>
</DL>
</DL>
<DT><A HREF="xtypes.html">8. EXTENDING SQL: TYPES</A>
<DL>
<DT><A HREF="xtypes.html#user-defined-types">8.1. User-Defined Types</A>
<DL>
<DT><A HREF="xtypes.html#functions-needed-for-a-user-defined-type">8.1.1. Functions Needed for a User-Defined Type</A>
<DT><A HREF="xtypes.html#large-objects">8.1.2. Large Objects</A>
</DL>
</DL>
<DT><A HREF="xoper.html">9. EXTENDING SQL: OPERATORS</A>
<DL>
</DL>
<DT><A HREF="xaggr.html">10. EXTENDING SQL: AGGREGATES</A>
<DL>
</DL>
<DT><A HREF="xindex.html">11. INTERFACING EXTENSIONS TO INDICES</A>
<DL>
</DL>
<DT><A HREF="libpq.html">12. LIBPQ</A>
<DL>
<DT><A HREF="libpq.html#control-and-initialization">12.1. Control and Initialization</A>
<DT><A HREF="libpq.html#database-connection-functions">12.2. Database Connection Functions</A>
<DT><A HREF="libpq.html#query-execution-functions">12.3. Query Execution Functions</A>
<DT><A HREF="libpq.html#fast-path">12.4. Fast Path</A>
<DT><A HREF="libpq.html#asynchronous-notification">12.5. Asynchronous Notification</A>
<DT><A HREF="libpq.html#functions-associated-with-the-copy-command">12.6. Functions Associated with the COPY Command</A>
<DT><A HREF="libpq.html#tracing-functions">12.7. LIBPQ Tracing Functions</A></A>
<DT><A HREF="libpq.html#authentication-functions">12.8. User Authentication Functions</A>
<DT><A HREF="libpq.html#bugs">12.9. BUGS</A>
<DT><A HREF="libpq.html#sample-programs">12.10. Sample Programs</A>
<DL>
<DT><A HREF="libpq.html#sample-program-1">12.10.1. Sample Program 1</A>
<DT><A HREF="libpq.html#sample-program-2">12.10.2. Sample Program 2</A>
<DT><A HREF="libpq.html#sample-program-3">12.10.3. Sample Program 3</A>
</DL>
</DL>
<DT><A HREF="lobj.html">13. LARGE OBJECTS</A>
<DL>
<DT><A HREF="lobj.html#historical-note">13.1. Historical Note</A>
<DT><A HREF="lobj.html#inversion-large-objects">13.2. Inversion Large Objects</A>
<DT><A HREF="lobj.html#large-object-interfaces">13.3. Large Object Interfaces</A>
<DL>
<DT><A HREF="lobj.html#creating-large-objects">13.3.1. Creating a Large Object</A>
<DT><A HREF="lobj.html#importing-a-large-object">13.3.2. Importing a Large Object</A>
<DT><A HREF="lobj.html#exporting-a-large-object">13.3.3. Exporting a Large Object</A>
<DT><A HREF="lobj.html#opening-an-existing-large-object">13.3.4. Opening an Existing Large Object</A>
<DT><A HREF="lobj.html#writing-data-to-a-large-object">13.3.5. Writing Data to a Large Object</A>
<DT><A HREF="lobj.html#seeking-on-a-large-object">13.3.6. Seeking on a Large Object</A>
<DT><A HREF="lobj.html#closing-a-large-object-descriptor">13.3.7. Closing a Large Object Descriptor</A>
</DL>
<DT><A HREF="lobj.html#built-in-registered-functions">13.4. Built in registered functions</A>
<DT><A HREF="lobj.html#accessing-large-objects-from-libpq">13.5. Accessing Large Objects from LIBPQ</A>
<DT><A HREF="lobj.html#sample-program">13.6. Sample Program</A>
</DL>
<DT><A HREF="rules.html">14. THE POSTGRES RULE SYSTEM</A>
<DT><A HREF="admin.html">15. ADMINISTERING POSTGRES</A>
<DT><A HREF="refs.html">16. REFERENCES</A>
<p>
<DT><A HREF="appenda.html">Appendix A: Linking Dynamically-Loaded Functions</A>
</DL>
<HR>
<A HREF="http://eol.ists.ca/cgi-bin/HyperNews/get/dunlop/pg95-user.html">HyperNews Forum</A> - About this Manual.
<HR>
<p align=center><B>POSTGRES95</B> is <A HREF="copy.html">copyright</A> &copy; 1994-5 by the Regents of the
University of California.<br><br>
Converted to HTML by <a href="http://www.eol.ists.ca/~dunlop/dunlop.html">J. Douglas Dunlop</a>
<a href="mailto:dunlop@eol.ists.ca">&lt;dunlop@eol.ists.ca&gt;</a><br>
The file
<A HREF="http://www.eol.ists.ca/~dunlop/postgres95-manual/pg95user.tgz">
pg95user.tgz</a> contains the complete manual for download.</p>
</BODY>
</HTML>
doc/manual/query.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/refs.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - REFERENCES</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="rules.html">[ Previous ]</A>
<A HREF="appenda.html">[ Next ]</A>
</font>
<HR>
<H1>16. REFERENCES</H1>
<HR>
<DL COMPACT>
<DT><A NAME="DATE93"><B>[DATE93]</B></A><DD>Date, C. J. and Darwen, Hugh, A Guide to The
SQL Standard, 3rd Edition, Reading, MA, June
1993.
<DT><A NAME="MELT93"><B>[MELT93]</B></A><DD>Melton, J. Understanding the New SQL, 1994.
<DT><A NAME="ONG90"><B>[ONG90]</B></A><DD>Ong, L. and Goh, J., ``A Unified Framework
for Version Modeling Using Production Rules
in a Database System," Electronics Research
Laboratory, University of California, ERL
Technical Memorandum M90/33, Berkeley, CA,
April 1990.
<DT><A NAME="ROWE87"><B>[ROWE87]</B></A><DD>Rowe, L. and Stonebraker, M., ``The POSTGRES
Data Model,'' Proc. 1987 VLDB Conference,
Brighton, England, Sept. 1987.
<DT><A NAME="STON86"><B>[STON86]</B></A><DD>Stonebraker, M. and Rowe, L., ``The Design
of POSTGRES,'' Proc. 1986 ACM-SIGMOD Conference on Management of Data, Washington, DC,
May 1986.
<DT><A NAME="STON87a"><B>[STON87a]</B></A><DD>Stonebraker, M., Hanson, E. and Hong, C.-H.,
``The Design of the POSTGRES Rules System,''
Proc. 1987 IEEE Conference on Data Engineering, Los Angeles, CA, Feb. 1987.
<DT><A NAME="STON87b"><B>[STON87b]</B></A><DD>Stonebraker, M., ``The POSTGRES Storage System,'' Proc. 1987 VLDB Conference, Brighton,
England, Sept. 1987.
<DT><A NAME="STON89"><B>[STON89]</B></A><DD>Stonebraker, M., Hearst, M., and Potamianos,
S., ``A Commentary on the POSTGRES Rules
System,'' SIGMOD Record 18(3), Sept. 1989.
<DT><A NAME="STON90a"><B>[STON90a]</B></A><DD>Stonebraker, M., Rowe, L. A., and Hirohama,
M., ``The Implementation of POSTGRES,'' IEEE
Transactions on Knowledge and Data Engineering 2(1), March 1990.
<DT><A NAME="STON90b"><B>[STON90b]</B></A><DD>Stonebraker, M. et al., ``On Rules, Procedures, Caching and Views in Database Systems,'' Proc. 1990 ACM-SIGMOD Conference on
Management of Data, Atlantic City, N.J.,
June 1990.
</DL>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="rules.html">[ Previous ]</A>
<A HREF="appenda.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/rules.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - THE POSTGRES RULE SYSTEM</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="lobj.html">[ Previous ]</A>
<A HREF="admin.html">[ Next ]</A>
</font>
<HR>
<H1>14. THE POSTGRES RULE SYSTEM
</H1><HR>
Production rule systems are conceptually simple, but
there are many subtle points involved in actually using
them. Consequently, we will not attempt to explain the
actual syntax and operation of the POSTGRES rule system
here. Instead, you should read <A HREF="refs.html#STON90b">[STON90b]</A> to understand
some of these points and the theoretical foundations of
the POSTGRES rule system before trying to use rules.
The discussion in this section is intended to provide
an overview of the POSTGRES rule system and point the
user at helpful references and examples.
The "query rewrite" rule system modifies queries to
take rules into consideration, and then passes the modified
query to the query optimizer for execution. It
is very powerful, and can be used for many things such
as query language procedures, views, and versions. The
power of this rule system is discussed in
<A HREF="refs.html#ONG90">[ONG90]</A> as
well as <A HREF="refs.html#STON90b">[STON90b]</A>.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="lobj.html">[ Previous ]</A>
<A HREF="admin.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/start.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/xaggr.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - EXTENDING SQL: AGGREGATES</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xoper.html">[ Previous ]</A>
<A HREF="xindex.html">[ Next ]</A>
</font>
<HR>
<H1>10. EXTENDING SQL: AGGREGATES</H1>
<HR>
Aggregates in POSTGRES are expressed in terms of state
transition functions. That is, an aggregate can be
defined in terms of state that is modified whenever an
instance is processed. Some state functions look at a
particular value in the instance when computing the new
state (<B>sfunc1</B> in the create aggregate syntax) while
others only keep track of their own internal state
(<B>sfunc2</B>).
If we define an aggregate that uses only <B>sfunc1</B>, we
define an aggregate that computes a running function of
the attribute values from each instance. "Sum" is an
example of this kind of aggregate. "Sum" starts at
zero and always adds the current instance's value to
its running total. We will use the <B>int4pl</B> that is
built into POSTGRES to perform this addition.
<pre> CREATE AGGREGATE complex_sum (
sfunc1 = complex_add,
basetype = complex,
stype1 = complex,
initcond1 = '(0,0)'
);
SELECT complex_sum(a) FROM test_complex;
+------------+
|complex_sum |
+------------+
|(34,53.9) |
+------------+
</pre>
If we define only <B>sfunc2</B>, we are specifying an aggregate
that computes a running function that is independent of
the attribute values from each instance.
"Count" is the most common example of this kind of
aggregate. "Count" starts at zero and adds one to its
running total for each instance, ignoring the instance
value. Here, we use the built-in <B>int4inc</B> routine to do
the work for us. This routine increments (adds one to)
its argument.
<pre> CREATE AGGREGATE my_count (sfunc2 = int4inc, -- add one
basetype = int4, stype2 = int4,
initcond2 = '0')
SELECT my_count(&#42;) as emp_count from EMP;
+----------+
|emp_count |
+----------+
|5 |
+----------+
</pre>
"Average" is an example of an aggregate that requires
both a function to compute the running sum and a function
to compute the running count. When all of the
instances have been processed, the final answer for the
aggregate is the running sum divided by the running
count. We use the <B>int4pl</B> and <B>int4inc</B> routines we used
before as well as the POSTGRES integer division
routine, <B>int4div</B>, to compute the division of the sum by
the count.
<pre> CREATE AGGREGATE my_average (sfunc1 = int4pl, -- sum
basetype = int4,
stype1 = int4,
sfunc2 = int4inc, -- count
stype2 = int4,
finalfunc = int4div, -- division
initcond1 = '0',
initcond2 = '0')
SELECT my_average(salary) as emp_average FROM EMP;
+------------+
|emp_average |
+------------+
|1640 |
+------------+
</pre>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xoper.html">[ Previous ]</A>
<A HREF="xindex.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/xfunc.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/xindex.html 0 → 100644
View file @ 59bb41a2
This diff is collapsed.
doc/manual/xoper.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - THE QUERY LANGUAGE</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xtypes.html">[ Previous ]</A>
<A HREF="xaggr.html">[ Next ]</A>
</font>
<HR>
<H1>9. EXTENDING SQL: OPERATORS</H1>
<HR>
POSTGRES supports left unary, right unary and binary
operators. Operators can be overloaded, or re-used
with different numbers and types of arguments. If
there is an ambiguous situation and the system cannot
determine the correct operator to use, it will return
an error and you may have to typecast the left and/or
right operands to help it understand which operator you
meant to use.
To create an operator for adding two complex numbers
can be done as follows. First we need to create a
function to add the new types. Then, we can create the
operator with the function.
<pre>
CREATE FUNCTION complex_add(complex, complex)
RETURNS complex
AS '&#36;PWD/obj/complex.so'
LANGUAGE 'c';
CREATE OPERATOR + (
leftarg = complex,
rightarg = complex,
procedure = complex_add,
commutator = +
);
</pre>
We've shown how to create a binary operator here. To
create unary operators, just omit one of leftarg (for
left unary) or rightarg (for right unary).
If we give the system enough type information, it can
automatically figure out which operators to use.
<pre>
SELECT (a + b) AS c FROM test_complex;
+----------------+
|c |
+----------------+
|(5.2,6.05) |
+----------------+
|(133.42,144.95) |
+----------------+
</pre>
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xtypes.html">[ Previous ]</A>
<A HREF="xaggr.html">[ Next ]</A>
</font>
</BODY>
</HTML>
doc/manual/xtypes.html 0 → 100644
View file @ 59bb41a2
<HTML>
<HEAD>
<TITLE>The POSTGRES95 User Manual - EXTENDING SQL: TYPES</TITLE>
</HEAD>
<BODY>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xfunc.html">[ Previous ]</A>
<A HREF="xoper.html">[ Next ]</A>
</font>
<HR>
<H1>8. EXTENDING SQL: TYPES</H1>
<HR>
As previously mentioned, there are two kinds of types
in POSTGRES: base types (defined in a programming language)
and composite types (instances).
Examples in this section up to interfacing indices can
be found in <CODE>complex.sql</CODE> and <CODE>complex.c</CODE>. Composite examples
are in <CODE>funcs.sql</CODE>.
<p>
<H2><A NAME="user-defined-types">8.1. User-Defined Types</A></H2>
<p>
<H3><A NAME="functions-needed-for-a-user-defined-type">8.1.1. Functions Needed for a User-Defined Type</A></H3>
A user-defined type must always have input and output
functions. These functions determine how the type
appears in strings (for input by the user and output to
the user) and how the type is organized in memory. The
input function takes a null-delimited character string
as its input and returns the internal (in memory)
representation of the type. The output function takes the
internal representation of the type and returns a null
delimited character string.
Suppose we want to define a complex type which represents
complex numbers. Naturally, we choose to represent a
complex in memory as the following <B>C</B> structure:
<pre> typedef struct Complex {
double x;
double y;
} Complex;
</pre>
and a string of the form (x,y) as the external string
representation.
These functions are usually not hard to write, especially
the output function. However, there are a number of points
to remember.
<OL>
<LI> When defining your external (string) representation,
remember that you must eventually write a
complete and robust parser for that representation
as your input function!
<pre> Complex &#42;
complex_in(char &#42;str)
{
double x, y;
Complex &#42;result;
if (sscanf(str, " ( &#37;lf , &#37;lf )", &amp;x, &amp;y) != 2) {
elog(WARN, "complex_in: error in parsing
return NULL;
}
result = (Complex &#42;)palloc(sizeof(Complex));
result-&gt;x = x;
result-&gt;y = y;
return (result);
}
</pre>
The output function can simply be:
<pre> char &#42;
complex_out(Complex &#42;complex)
{
char &#42;result;
<p>
if (complex == NULL)
return(NULL);
<p>
result = (char &#42;) palloc(60);
sprintf(result, "(&#37;g,&#37;g)", complex-&gt;x, complex-&gt;y);
return(result);
}
</pre>
<LI> You should try to make the input and output
functions inverses of each other. If you do
not, you will have severe problems when you need
to dump your data into a file and then read it
back in (say, into someone else's database on
another computer). This is a particularly common
problem when floating-point numbers are
involved.
</OL>
To define the <B>complex</B> type, we need to create the two
user-defined functions complex_in and complex_out
before creating the type:
<pre> CREATE FUNCTION complex_in(opaque)
RETURNS complex
AS '/usr/local/postgres95/tutorial/obj/complex.so'
LANGUAGE 'c';
CREATE FUNCTION complex_out(opaque)
RETURNS opaque
AS '/usr/local/postgres95/tutorial/obj/complex.so'
LANGUAGE 'c';
CREATE TYPE complex (
internallength = 16,
input = complex_in,
output = complex_out
);
</pre>
As discussed earlier, POSTGRES fully supports arrays of
base types. Additionally, POSTGRES supports arrays of
user-defined types as well. When you define a type,
POSTGRES automatically provides support for arrays of
that type. For historical reasons, the array type has
the same name as the user-defined type with the
underscore character _ prepended.
Composite types do not need any function defined on
them, since the system already understands what they
look like inside.
<p>
<H3><A NAME="large-objects">8.1.2. Large Objects</A></H3>
The types discussed to this point are all "small"
objects -- that is, they are smaller than 8KB<A HREF="#7"><font size=-1>[7]</font></A> in size.
If you require a larger type for something like a document
retrieval system or for storing bitmaps, you will
need to use the POSTGRES large object interface.
<p>
<HR>
<A NAME="8"><B>[7]</B></A> 8 &#42; 1024 == 8192 bytes. In fact, the type must be considerably smaller than 8192 bytes, since the POSTGRES tuple
and page overhead must also fit into this 8KB limitation.
The actual value that fits depends on the machine architecture.
<HR>
<font size=-1>
<A HREF="pg95user.html">[ TOC ]</A>
<A HREF="xfunc.html">[ Previous ]</A>
<A HREF="xoper.html">[ Next ]</A>
</font>
</BODY>
</HTML>
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment