.\".he '\*(dA'DRAFT'\*(tI'		\" comment out in production version
.\"========================================================
.de cW					\" arg3arg1arg2, constant-width arg1
\&\\$3\\fC\\$1\\fP\\$2
.\"\&\\$3\\fC\\s-1\\$1\\s0\\fP\\$2
..
.\"------------------------------------
.de (P					\" prologue for constant-width block
.ft C
.ps -1
.vs -1
..
.\"-----------------
.de )P					\" epilogue for constant-width block
.vs +1
.ps +1
.ft P
..
.\"------------------------------------
.de (T					\" prologue for constant-width table
.(P
.in +\\n(biu
..
.\"-----------------
.de )T					\" epilogue for constant-width table
.in -\\n(biu
.)P
..
.\"------------------------------------
.de (C					\" begin constant-width list
.(l
.(P
..
.\"-----------------
.de )C					\" end constant-width list
.)P
.)l
..
.\"---------------------------------------------------------------------------
.ds rM Reference Manual
.ds uM User Manual
.ds uX \s-2UNIX\s0
.ds vC Version 4.0
.ds vP Version 3.1
.\"---------------------------------------------------------------------------
.\"
.\"	release4.0.me:  postgres version 4.0 release notes.  print using
.\"			psroff -me.
.\"
.nr pi 3n
.nr si 2n
.nr pp 11
.nr tp 11
.nr sp 11
.de RV
.ie "\\$2"" \
\{\
.	ds VN "0.0
.	ds VD "(No date)
.	ds VT "UNAUDITED VERSION
.\}
.el \
\{\
.	ds VN \\$3
.	ds VD \\$4
.	ie "\\$7"Exp" \
.		ds VT "DRAFT
.	el \
.		ds VT \\$7
.\}
..
.RV $Header: /usr/local/dev/postgres/mastertree/doc/RCS/release.4.0.me,v 1.13 1992/07/14 23:24:14 mao Exp $
.ds PG "\\s-2POSTGRES\\s0
.ds PQ "\\s-2POSTQUEL\\s0
.ce 99
.ft B
.ps 14
\*(PG \*(vC
.sp 0.5v
Release Notes
.sp
.ps 11
\*(VD
.ce 0
.he '\*(PG \*(vC Release Notes'%'\*(VD'
.ft P
.sp 2
.sh 1 "Introduction"
.pp
These are the release notes for \*(vC
of the \*(PG database system from UC Berkeley.
The database system and its installation procedure
are covered in detail in the setup document for this release,
which can be found in the file
.cW $POSTGRESHOME/doc/postgres-setup.me .
Here, we cover only the most important differences from \*(vP
and earlier versions of the system.
.sh 1 "Aim"
.pp
This release provides improved functionality over \*(vP in many areas
of the system.
In particular, significant advances have been made in
\*(PG functions and large objects.
.sh 1 "Changes to \*(PQ"
.sh 2 "define function"
.pp
The syntax for defining functions has been changed slightly.
\*(PG now
supports functions that can return sets of values.
To declare
such a function you use the keyword
.cW setof
before the actual type name when specifying the return type:
.(C
define function hobbies
    (language = "postquel", returntype = setof hobbies_r)
    arg is (emp)
    as "retrieve (hobbies_r.all)
        where hobbies_r.person = $1.name"
.)C
The function
.cW hobbies
is declared to return a set of instances from the
class
.cW hobbies_r .
Had
.cW setof
been omitted, the
.cW retrieve
would be executed
exactly one time and the first instance retrieved would be the only return
value.
The primary reason for forcing this distinction is that
\*(PQ functions declared to return a single value can be used in a much
more general fashion than functions returning a set of results.
.lp
\*(PG does
not support functions or operators with sets as arguments.
For example:
.(C
define function alwaysone
    (language = "postquel", returntype = int4)
    as "retrieve (x = 1)"
.)C
Calls to
.cW alwaysone
may be used as though they were constants.
In contrast,
if we had declared the return type to be
.cW "setof int4" ,
.cW alwaysone
would be
forbidden as an argument to functions and/or operators.
.pp
\*(PG now provides much better optimization of
expensive functions.
To aid the optimizer, the author of a C function can
now
choose to specify parameters which will be used to determine the function's
.q cost
in the query under consideration.
For complete details see the \*(rM
page on functions.
.sh 2 "NULL Detection"
.pp
\*(PG now recognizes the keywords
.cW ISNULL
and
.cW NOTNULL
and allows qualifications based on whether or not an attribute is
null.
The general syntax in qualifications is:
.(C
where \f2expression\fP ISNULL
where \f2expression\fP NOTNULL
.)C
.sh 2 "Unified Syntax for Functions and Attributes"
.pp
If a \*(PQ function is declared that takes instances of a class
as its only argument,
it may be invoked in two different ways.
For example,
assume that the function
.cW overpaid
has been declared in \*(PQ to take an instance of the
.cW emp
class and return a boolean value.
Then the two queries
.(C
retrieve (emp.overpaid)
retrieve (overpaid = overpaid(emp))
.)C
are exactly equivalent.
Similarly,
attributes may be referenced in the same ways.
If
.cW emp
has an attribute
.cW salary ,
then
.(C
retrieve (emp.salary)
retrieve (salary = salary(emp))
.)C
are equivalent.
Both of these may be considered parameterless method calls on
instances of the
.cW emp
class.
.sh 2 "Binary Portals"
.pp
It is now possible to get data out of \*(PG in binary format.
The query syntax is
.(C
retrieve iportal \f2portal name\fP (\f2target list\fP) \f2qualifiers\fP
.)C
Taking advantage of this feature should speed up
.cW libpq
application programs
considerably.
See the \*(rM for all of the details.
.sh 2 "Arrays"
.pp
In previous releases array indirection values were required to be integer
constants.  In \*(vC they can be any expression as long as the expression is
of type int4.  For example the following queries are now legal
.(C
retrieve (foo.a[1+2], foo[arrayind.i], foo.a)
retrieve (foo.a[arrayind.i]) where arrayind.i <= 3
.)C
.sh 1 "General System Changes"
.sh 2 "Functions"
.pp
The big story of the \*(vC release is improved \*(PQ functions.
\*(PQ function support in previous releases suffered from the following
limitations:
.ip \0\0\(bu
They could take only a single argument,
which had to be an instance of some class.
.ip \0\0\(bu
They had to return a set of instances of some class.
.ip \0\0\(bu
No run-time or declaration-time type checking was performed
to verify that the arguments or return value of the function
were correctly typed.
.pp
\*(PQ functions in \*(vP of \*(PG were implemented using
the rewrite rules system.
\*(vC supports query language functions as first-class citizens,
and no longer relies on the rules system to implement them.
As a result,
the shortcomings listed above have been eliminated.
.pp
There are no special restrictions on the types or the number of arguments,
nor is there any restriction on the type of the result.
As outlined above,
the syntax for defining a \*(PQ function is
analogous to defining a C function.
The biggest difference is that the
.cW as
clause must contain a quoted list of \*(PQ queries.
Within the body of the function, $\f2number\fP refers to the
.i number th
parameter passed
in by the caller.
See the \*(rM for details.
.pp
C functions have also been improved.
In previous releases C functions were
restricted to taking at most one
.q tuple
argument, that is, an argument whose
type is an instance of some class.
In \*(vC, C functions can take
up to eight tuple arguments.\**
.(f
The 8-argument limit applies to
.b all
\*(PG functions.
.)f
.pp
Finally, \*(PG provides enhanced optimization of both C and \*(PQ
functions.
In the case of C functions,
the optimizer takes user-specified
parameters on cost into account when deciding how to execute a query.
.pp
\*(PQ functions have one important limitation:
system attributes
(for example,
.cW tmin ,
.cW tmax ,
and
.cW oid )
of function return values and parameters cannot be referenced.
The \*(PG parser checks this condition when a function is
defined and invoked,
and prints a descriptive error message if the condition
is violated.
This limitation will be removed in a future release of the system.
.sh 2 "Revised Support for Nested Relations"
.pp
\*(vP of \*(PG supported nested relations using
tuple-valued attributes and rewrite rules.
For example,
given the declarations:
.(C
create person (name = char16, child = char16)

addattr (parent = person) to person

define rewrite rule find_parent
    on retrieve to person.parent do instead
	retrieve (person.all)
	    where person.child = current.name
.)C
it was possible to refer to
.(C
person.parent.name
.)C
and have the correct name fetched by \*(PG.
.lp
In \*(vC of \*(PG,
rewrite rules are no longer used to support nested relations.
Instead,
a function should be declared that returns tuples of the
appropriate type.
For example,
in \*(vC,
.(C
create person (name = char16, child = char16)

define function parent
    (language = "postquel", returntype = person)
    arg is (person)
    as "retrieve (person.all) where person.child = $1.name"
.)C
are equivalent to the rule and attribute additions shown above.
The same nested-dot notation is supported for functions
as was supported for rewrite rules.
.pp
As a side effect of the improved support for functions,
it is not possible in \*(vC to create a relation which has
an attribute that is of a complex (tuple) type.
For example,
the
.cW addattr
command shown above is illegal in this release of \*(PG,
since the type of the attribute being added is
.cW person ,
and
.cW person
is a class.
Support for attributes of complex types will be reintroduced
in a future release of \*(PG.
.sh 2 "Sets"
.pp
\*(PG now provides limited support for sets.
Currently this comes via
results of \*(PQ functions (C functions should also be able to return a
set of values; this will be available in a future release).
The key
design choice to point out is that when two set-valued \*(PQ functions
appear in the target list of a
.cW retrieve
query, the result will be a set
of
.q flattened
tuples.
This set of tuples is the cross product of all
the sets appearing the target list.
For example, if you have two
functions,
.cW f
and
.cW g ,
where
.cW f
returns 3 results and
.cW g
returns 2, \*(PG
will return 6 tuples which make up all combinations of
.cW f
and
.cW g .
If either
.cW f
or
.cW g
retuns no results (i.e. the empty set) then we consider it to
be a set of 1 element whose value is NULL.
This choice was made primarily
to avoid returning no results when a function in the target list returns
nothing.
.sh 2 "Large Objects and the Inversion File System"
.pp
Support for large objects in \*(PG has been improved.
\*(vP supported large objects stored in \*(uX files.
User applications could open, seek,
read, and write these large objects,
but only inside dynamically-loaded functions.
In addition,
changes to large objects were not transaction-protected,
and no support for historical access was available.
.pp
In \*(vC,
another large object implementation is provided.
This implementation breaks large objects into
.q chunks,
and stores each chunk in a tuple in the database.
Updates are transaction-protected and time travel is available.
\*(vP
large objects (\c
.q "\*(uX large objects" )
are still supported.
The new implementation (\c
.q "Inversion large objects" )
is available by specifying the proper flags when an object
is created.
Details are provided in the \*(rM.
.pp
In addition,
a rudimentary file system has been built on top of the \*(PG
Inversion large object implementation.
The Inversion file system provides transaction-protected access
to user files,
time travel on file system state,
and the ability to do attribute- or content-based searches
for file data.
.pp
At present,
no kernel interface to Inversion is available,
so the Inversion file system cannot be mounted and used
in the same way as the native file system.
Instead,
a suite of library routines and utility programs
give users access to the Inversion file system.
Again,
see the \*(rM for details.
.sh 2 "Indices on System Catalogs"
.pp
\*(PG now has secondary indices defined on the system catalogs.
Initially, we have indexed
.cW pg_proc ,
.cW pg_attribute ,
and
.cW pg_type .
We expect that, after profiling \*(PG performance on large databases,
additional indices will be added in future releases.
.sh 1 "Miscellaneous"
.sh 2 "Big Bug Fixes"
.pp
We have found and fixed a number of serious bugs with multi-user
operation that were present in release 3.1.
One bug sometimes caused
a backend to read end-of-file from the socket on start up.
Another much more destructive bug caused data from one
database to be written to another database in certain circumstances.
If the database being written to was
.cW template1 ,
then the corruption would be passed on to whoever
ran a subsequent
.cW createdb .
Often
.cW createdb
would just fail.
.sh 2 "\*(rM and \*(uM"
.pp
A serious effort was made to improve the
dilapidated condition of both the \*(rM and \*(uM.
The main focus was to root out all of the lies they contained,
as well as documenting all of the new features.
We will be paying much closer attention to bugs in these two documents.
If you find something wrong in them,
or something you can't understand,
let us know about it
.cW bug-postgres@postgres.Berkeley.EDU ). (
.sh 2 "\*(PG User Ids and Unix UIDs"
.pp
The user ID of a \*(PG registered user
.b must
match the user's \*(uX user ID.
In the new release, the user ID of the \*(PG
user in
.cW /etc/passwd is
.b not
presumed to be anything.
We now adjust
the system catalog entry for the user ID at installation time.
It will
happen automatically; there is no longer any need to edit
.cW pg_user.h .
.sh 2 "Security"
.pp
Security in \*(PG is pretty much non-existent.
We are working on providing it for a future release.
For now the only check \*(PG performs is at initialization
time.
The backend will lookup the front-end user to make sure s/he is a
registered \*(PG user before allowing the user to run any queries.
Just so you are aware,
it is not at all difficult for someone to circumvent this
poor excuse for a lock-out mechanism.
If you really care about your data,
you should make backups of your
.cW $POSTGRESHOME/data
directory regularly.
.lp
In previous
releases,
.cW pg_user
contained entries for each of the \*(PG implementors.
In \*(vC,
the only entry is for the user named
.cW postgres .
.sh 2 "Append Returns an Object Id"
.pp
When you run the \*(PQ
.cW append
command from
.cW pqexec ,
the command tag that you
receive has the
.cW oid
of the appended tuple in it.
When you run
.cW append
queries
from the monitor you get output something like:
.(C
APPEND 206557
.)C
When two or more tuples are appended by the same command \*(PG returns the
invalid object ID zero.
.sh 1 "Known Bugs"
.pp
There are a few known bugs that we did not fix in the current
release.
.sh 2 "Indices and the Instance Level Rule System"
.pp
The instance-level rule system essentially ignores indices, so if you are
defining a rule on an indexed attribute, you should use the query rewrite
rule system.
.sh 2 "Retrieve Into and failed backends"
.pp
If a backend fails while in the course of executing a
.cW "retrieve into"
query,
a spurious file, with the same name as the target class of the
.cW "retrieve into" ,
will be left in the database directory.
This file can be safely deleted by the
database administrator.
.sh 2 "Known bugs list"
.pp
A list of known bugs and suggested work-arounds can be anonymously
FTP'd from
.cW postgres.Berkeley.EDU
(128.32.149.1).
This list is kept in the file
.cW pub/postgres-v4r0.bugs .
We will make every attempt to keep this list up to date.
.sh 1 "Machine-dependent Problems"
.sh 2 "SPARCstations running SunOS 4.0.3"
.pp
\*(PG has been known to crash SunOS 4.0.3 on SPARCstations, due to a SunOS
bug in shared memory.
This bug has not been observed on SunOS 4.1 and higher,
so any reports of crashes on SunOS 4.1 and higher are especially appreciated.