.\"
.\"	release3.0.me:  postgres version 3.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
.\}
..
.de CW
\\f(CW\\$1\\fP\\$2
..
.RV $Header: /data/01/postgres/src/old_doc/RCS/release3.0.me,v 1.8 1991/08/18 05:20:58 kemnitz Exp $
.ds PG "\\s-2POSTGRES\\s0
.ds PQ "\\s-2POSTQUEL\\s0
.ce 99
.ft B
.ps 14
\*(PG Version 3
.sp 0.5v
Release Notes
.sp
.ps 11
\*(VD
.ce 0
.he '\*(PG V3.0 Release Notes'%'\*(VD'
.sp 2
.sh 1 "Introduction"
.pp
These are the release notes for version 3.0
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.
Here,
we cover only the most important differences from release
2.1 and earlier versions of the system.
.sh 1 "Changes to \*(PQ"
.pp
The \*(PQ query language has been changed to better support
remote access to databases over a network,
and to provide more control over data storage.
.sh 2 "Createdb, destroydb"
.pp
The
.i createdb
and
.i destroydb
commands have been added to the query language.
Syntax is
.CW "createdb dbname"
or
.CW "destroydb dbname" .
There must be a database open while these commands are being run.
We recommend running these queries from inside the
.q template1
database.
.pp
This change was made in order to permit users to create and
destroy databases without logging onto the machine on which
the postmaster is running.
.sh 2 "Vacuum"
.pp
The
.i vacuum
command has been added to \*(PQ.
This command causes the open database to be vacuumed.
Vacuuming updates statistics on relations,
cleans out records from aborted transactions,
and sets commit times on committed transactions.
Syntax is
.CW vacuum .
.pp
This query may be submitted at any time.
It is a good idea to update statistics after copying in a large
file,
or deleting a large number of records from a class.
.pp
This change was made in order to get rid of the
.i vacuum
Unix program,
which was very large and required maintenance separate from
the \*(PG backend.
.sh 2 "Create syntax changes"
.pp
The
.i create
command for creating new classes has some new optional specifications.
The syntax
.(b
.ft CW
create foo (a = int4) store = "magnetic disk"
.ft
.)b
will cause the new class
.q foo
to be created,
and to be stored on magnetic disk.
Similarly,
.(b
.ft CW
create foo (a = int4) archive = heavy arch_store = "magnetic disk"
.ft
.)b
creates class
.q foo
as an archived class;
historical data is stored on magnetic disk.
.pp
As the second example above implies,
archival of user data is supported in the current release.
Scans of archived data are planned and executed for historical
queries,
and the vacuum cleaner
(see
.i vacuum ,
above)
moves data from the current store to the archive.
.pp
In the released system,
the only possible location for user data is
.q "magnetic disk" ;
this is also the default.
The additional specifications for storage managers
were added to support research being done at Berkeley.
.pp
Some caveats here:
Since
.q store
and
.q arch_store
are new keywords,
they may not be used in queries except as shown above.
In addition,
if an archived relation is destroyed,
historical queries are no longer guaranteed to return
the correct answer.
.sh 2 "Portals"
.pp
The command
.(b
.ft CW
retrieve portal myportal (pg_user.all)
.ft
.)b
in release 2.1 and earlier versions of \*(PG could be
issued as a stand-alone transaction.
This violated isolation requirements,
since the results from the retrieve were not actually
instantiated until they were
.CW fetch ed,
but locks were released on successful completion of the
.CW retrieve .
.lp
As of release 3.0,
operations on portals must be done inside of
\f(CWbegin\fP/\f(CWend\fP
transaction blocks.
This change may require you to rewrite libpq application
programs,
if your applications use portals outside of transaction blocks.
The correct interaction is now
.(b
.ft CW
begin
retrieve portal myportal (pg_user.all)
fetch 10 in myportal
	\&...
close myportal
end
.ft
.)b
.lp
If the user fails to close a portal before the end of the
transaction block,
it is freed automatically,
and all resources it holds are released.
.sh 1 "Unix command changes"
.pp
The names and behavior of some Unix commands
shipped with \*(PG have changed in the new release.
.sh 2 "Createdb, Destroydb"
.pp
The
.i createdb
and
.i destroydb
commands are now shell scripts,
rather than compiled programs,
and submit queries via the terminal monitor.
The postmaster must be running in order for these scripts to
work.
For the sake of backward compatibility,
we have provided two different scripts
(createdb.sh and destroydb.sh)
that run without using the postmaster or shared resources.
Use of these two scripts is discouraged;
if at all possible,
use
.i createdb
and
.i destroydb
instead.
.pp
This change was made to make creating and destroying databases
from remote machines easier,
and to get rid of extra binaries.
Since \*(PQ now provides both of these as query language commands,
special programs are no longer necessary.
.sh 2 "Vacuum, Vcontrol"
.pp
Since the query language now supports the
.i vacuum
command,
the
.i vacuum
Unix program has been replaced by a shell script
which submits a query via the terminal monitor.
The
.i vctontrol
program is no longer shipped with \*(PG.
The syntax for the new script is
.CW "vacuum dbname" .
This opens a connection to a backend using database
.q dbname
and vacuums it.
.pp
We strongly recommend that production databases be vacuumed nightly.
This will keep statistics current,
and permit the query optimizer to make better choices
in planning user queries.
The easiest way to make this happen is to add entries of the form
.CW "vacuum dbname"
to your crontab file.
.pp
This change was made to get rid of the separate
.i vacuum
program,
ease maintenance,
and make the \*(PG distribution smaller.
.sh 2 "Monitor"
.pp
The terminal monitor takes several new flags.
The
.q \-q
flag suppresses conversational output.
The new
.q \-c
flag causes the argument immediately following it to be executed
as a \*(PQ query;
this overrides the normal interactive behavior of the monitor.
For example,
.(b
.ft CW
monitor -c "retrieve (pg_class.all)" mydb
.ft
.)b
executes the query
.q "retrieve (pg_class.all)"
on
.q mydb ,
sending the output to stdout.
After the query completes,
the terminal monitor exits.
.pp
The \-c switch was added to make it easier to use
\*(PQ queries in shell scripts.
The \-q switch was added because
.q "I live to serve you"
stopped seeming cute at three o'clock one morning.
.sh 2 "Initdb"
.pp
The
.i initdb
shell script initializes the
template database for \*(PG.
In general,
it is run by the installation process,
and need never be run by users.
.i Initdb
creates the data/ directory hierarchy in $POSTGRESHOME,
sets up some control files,
and populates the template database
.i template1 .
.pp
This change was made to get rid of the
.q "baby backend"
that handled bootstrapping of \*(PG in previous releases.
The functionality of that program was rolled into the
standard backend.
In addition,
.i initdb
substantially simplifies the installation procedure,
and gets rid of confusing syntax required for
.i createdb
in earlier releases.
.sh 1 "General System Changes"
.pp
The new release includes bug fixes to many problems
reported in version 2.1 and previous releases.
We have also sped the code up substantially.
This section contains a partial list of enhancements
made since release 2.1.
.sh 2 "Multi-User Stability"
.pp
We have done extensive rewriting and testing
of the code that handles concurrent access,
and believe that \*(PG is much better suited for
multi-user applications than it has been in the past.
The lock manager has been entirely rewritten,
and exclusion is guaranteed around critical sections.
Standard two-phase locking is provided on user tables.
System catalogs and indices have locking strategies
that provide higher concurrency.
.pp
As a new feature,
if one \*(PG backend terminates abnormally (dumps core),
then all backends running concurrently are killed and
restarted.
This is to guarantee that any data corrupted by the errant
backend are destroyed,
and not flushed to disk or propagated to other backends.
.pp
We are particularly interested in reports of bugs caused
by concurrent access to data by multiple users.
.sh 2 "Storage Manager Switch"
.pp
Previous releases of \*(PG had built-in assumptions
about the underlying storage medium.
All data were assumed to reside on magnetic disk.
Version 3.0 removes this assumption from the code.
Data may reside on other media,
at the discretion of the database administrator.
Access is location-transparent.
.pp
At Berkeley,
we have implemented a storage manager for a Sony optical disk
WORM jukebox
and for persistent main memory.
Neither of these is supported in the released system.
.sh 2 "Executor Rewrite"
.pp
The query executor has been almost completely rewritten,
in order to simplify code maintenance and to speed up execution.
Several memory leaks have been plugged,
and performance has been substantially improved.
.sh 2 "Query Rewrite Rule System"
.pp
The query rewrite rule system has been completely rewritten for this release.
This version implements the almost all the rewrite rule semantics specified in
"On Rules, Procedures, Caching, and Views" by Stonebraker et al. and closely
parallels the 'instance' level rule system.  It offers performance advantages
over 'instance' rules in some applications.
.pp
Views, versions, and \*(PQ functions are now supported via the rewrite system.
See the 'define rule(commands)' section of the reference manual for details.
.sh 2 "Aggregates"
.pp
Aggregates (or column-valued functions) are now supported.  The Reference
Manual describes how to define and use aggregates in detail.
.pp
.sh 2 "Large Objects"
.pp
Large Objects are now supported as "filename as an ADT".  The Reference
Manual describes the large object implementation in detail.  The 3.0
implementation is the first-cut implementation; a more fully-featured
implementation will be available in Release 4.0.
.pp
.sh 1 "Known Bugs"
.pp
There are a few known bugs that we were unable to 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 Retrieve Into query,
a spurious file, with the same name as the target class of the Retrieve Into,
will be left in the database directory.  This file can be safely deleted by the
database DBA. 
.sh 2 "Large Objects and failed backends"
.pp
If a backend fails while it is manipulating large objects, spurious large
object files will be left in the database directory.  Also, there is no
mechanism for getting rid of large objects which are returned by functions
but not stored in instances.
.sh 2 "Postgres User Id's and Unix UID's"
.pp
The userid of a Postgres registered user
.b must
match the user's UNIX user id.  In the release, the user id of the Postgres
user in /etc/passwd is presumed to be 6.  If it is not, Postgres will not run
properly.  This can be overcome for those who do not wish to renumber the
userid field in their password files by editing the file
.lp
.b src/lib/H/catalog/pg_user.h
.lp
and changing the "usesysid" field for the Postgres user to the one used
in /etc/passwd at your site
.b before
compiling and installing Postgres.  The line in this file you wish
to change looks like this:
.(1

DATA(insert OID =    6 ( postgres 6 t t t t ));

.)l
.lp
If you change the two 6's above to the value used for the "postgres"
user in your /etc/passwd file, this problem can be avoided.
.pp
.sh 1 "Machine-dependent Problems"
.pp
Postgres has been known to crash SunOS 4.0.3 on Sparcstations, due to a SunOS
bug in shared memory.  It appears to work on SunOS 4.1 and higher, so any
reports of crashes on SunOS 4.1 and higher are appreciated.