Welcome to the world of object oriented database management systems (OODBMS)!


You hopefully have successfully completed the installation of Postgres,
when you read this file.  There should be a new user named "postgres"
on your system, and you should log in as "postgres" for the demos
mentioned in this file to work.  If you can't log in as postgres, try
running the shell script in /install/doinst.sh once again.  It will
create the user, or at least tell you, what is wrong.

For postgres to work, you must have TCP/IP enabled, and "talking to
yourself" via the loopback device must work.  Most modern linux
distributions include networking, so this shouldn't be the problem.
Also, your kernel needs IPC support.  This is on by default, because
DOSEMU needs IPC as well.


Preloaded Database
==================

There is a preloaded database named "linux", and it contains a table
named "lsm".  Well, that's the linux software map.  To retrieve data
from it, we can use the postgres front end "spog".  Try the following:

	postmaster &
	spog linux
	retrieve (lsm.oid, lsm.Description) where lsm.Keywords ~ "[pP]lot"

The first command starts the postmaster, which is a background daemon
accepting connections to the database.  It has to be started only once,
after you have booted the system.  The second command starts "spog"
with the database "linux".  The third line is a database query.  It
will print a list with the Descriptions of all packages in the Linux
Software Map entries, which match the Keyword "plot" or "Plot".

The oid (object ID) is a number, which is different for all objects.
You can use it to retrieve more information about a particular item:

	retrieve (lsm.Comments, lsm.Required) where lsm.oid = "23048"::oid

Or if you are looking for all packages, which are shareware:

	retrieve (lsm.oid, lsm.Title) where lsm.CoypPolicy ~ "[sS]areware"

Well, you probably got it: in the parenthesis after "retrieve", you type
the name of the fields, you want to be listed.  And after "where", you
type an condition, which fields you want.  You can use an "=" for exact
match, or "~" for an regular expression match.

In the Linux Software Map, the following fields are available:

	Author AuthorEmail Comments CopyPolicy
	DateEntered Description EmailEntered Keywords
	Location1 Location2 Location3 Location4
	Location5 Location6 Location7 Location8
	MaintEmail Maintainer RelatedFiles Required
	Title Version WhoEntered oid

When finished, you leave spog with the command:

	exit


Graphical Front End: pgbrowse
=============================

Ascii interfaces like "spog" are not everybody's choice.  For those,
that have X--Windows and the tcl/tk toolkit from John K. Ousterhout
installed and 8 MB RAM, "pgbrowse" is an alternative.  tcl/tk can be
found on the disks named tcl1 and tcl2 of the slackware distribution.

You start the postgres browser with the command "pgbrowse".  If it prints
error messages, you probably forgot to start the postmaster (see above).
pgbrowse will open a window with a list of available databases.  If you
have not created your own databases, this list will contain "linux" and
"template1".  The later is an empty database, which is used as a starting
point, when new databases are created.

Double click on "linux", and you will get a list of available classes
(which are also called "relations" or "tables").  Double click on "lsm",
and you will get a window with a list of the fields in that class.
Below that window is the button "Query".  Clicking it will give you an
query tool.  It contains a list of all fields, and allows you to input
regular expressions you want to search for.  Try entering:

	LaTeX

into the wide box after the label "Title (text)".  The small box contains
an "~", this is the relational operator to use.  An click on the buttona
"Retrieve", and you will get the matching items, in yet another window.

Because the LSM has so many fields, they won't fit all in their windows.
Try using the scroll bars below and right to the main region of each
window.  If a text is too long for an window, click and hold the middle
mouse button over it, then move the mouse a bit to the left or right.  The
text will follow, several times accelerated.


What's next
===========

You have now seen postgres from a user's point of view: using it to
retrieve data.  There are some more demos provided with the distribution,
contained in the directory ~/src/regress:

- demo: demonstration of some of the object oriented features.
- bench: the Wisconsin benchmark, testing performance with medium
	amounts of data (1 Megabyte)
- video: another set of demo's, partially overlapping with those in
	demo.  Please note, that creating the index on the "fast_emp4000"
	table may need an hour or two, if your computer does not have
	a math coprocessor.
- multi: tests for the multi-user capabilities of postgres.
- regress: this subdirectory has been left out in the "newbie" package,
	to keep its size within bounds.

To run any of these demos, changes into the according dir, and type:

	bmake runtest

bmake is an extended make utility.


Documentation
=============

There is lots of documentation.  Take a look into the "doc" directory.
You will find the following files:

- postgres-setup: the instructions to install postgres.  This distribution
	(hopefully) takes most of the hazzle from you, so you shouldn't
	read this file too deeply.  It might be very helpfull, though,
	to find errors, if things don't run.
- release: the release notes, most important for users of earlier versions
	of postgres.
- manual: the user manual, an introduction to postgres
- ref: the reference manual, explaining all commands in detail

Files with the extension ".ps" are postscript files.  You can for example
use "ghostview" to view them.  ".cat" are ascii files.  A good viewer is
"less -i".


There are also man pages for the postgres utilities and the postquel
commands, found in the man subdir.  You may have to tell your manual
pager to consider this directory, or copy these files to a standard
man tree like /usr/local/man.


Future
======

Postgres *was* a research project at the University of California,
Berkeley.  It is finished, and they will no longer work on it.  I think,
though, that the code is too usefull to let it die.  I want to work on
it, so do some other linux people.  If you want to get involved, try
joining the mailing list:

	linux-postgres@native-ed.bc.ca

by sending mail to:

	linux-postgres-request@native-ed.bc.ca



That's it.  Have Fun with postgres!

Kai
wpp@marie.physik.tu-berlin.de
