ZPyGreSQLDA 0.03 README
-----------------------

This is the Z PyGreSQL database adapter product for the 
Z Object Publishing Environment. It was produced by modifying
ZMySQLDA's __init__.py, DA.py and db.py files to get pgmodule
from PyGreSQL-2.3 to work with Zope.

***** IMPORTANT *****

This product is distributed as a NON-BINARY release!

This product requires compiled Python extensions that are
NOT included as binaries with this release. You must build
or install the required extensions using the instructions 
below before the product will work properly!


Installation
------------

The ZPyGreSQL database adapter product requires that the Python
_pgmodule extension be installed. 

The source files and associated files required to build the 
required PyGreSQL module are included in this product distribution.
Follow the steps below to build the extension on UNIX platforms.
I do not know if the included files support building on win32 
platforms.

  o Ensure that you have PostgeSQL installed on your machine,
    INCLUDING THE FILES AND LIBRARIES NECESSARY TO DEVELOP
    APPLICATIONS. If you do not have the developer 
    files installed, you will need to download them from
    the PostgeSQL web site at http://www.postgresql.org. Please contact
    the maintainers with all questions pertaining to
    the use or installation of development files. Make sure that
    the postmaster has been started with the -i flag if you want to use a
    TCP/IP connection to the backend process. The flag is not necessary when
    using Unix sockets.

  o Ensure that you have extracted the ZPyGreSQLDA product distribution
    in your top-level Zope directory. This should have created a 
    subdirectory named lib/python/Products/ZPyGreSQLDA containing the 
    product files as well as this README file.

  o Change to the /src directory of your ZPyGreSQLDA product directory
    and issue the following commands:

    make -f Makefile.pre.in boot
    make

    Note 1. Add -DNO_PQSOCKET to the Setup file if you are using a version of PostgreSQL
            before 6.4 that does not have the PQsocket function. For example:

    _pg pgmodule.c -I/opt/postgres/include -L/opt/postgres/lib -lpq -lcrypt -DNO_PQSOCKET

    Note 2. On Solaris it may be necessary to add -R option to Setup file before running make.
	    For example:

    _pg pgmodule.c -I/opt/postgres/include -L/opt/postgres/lib -R/opt/postgres/lib -lpq -lcrypt

    This should create the file _pgmodule.so in your src directory.
    If errors occur when trying to build the extension, you may need
    to modify the Setup file to ensure that the correct PostgreSQL include
    and lib directory options are being passed to the compiler.

    Finally, copy the output file _pgmodule.so up one directory into
    your ZPyGreSQLDA product directory and restart your Zope installation 
    to complete the product installation.

Sample Data
-----------

The /data directory of the ZPyGreSQLDA directory includes some sample data. Issue the commands:

    createdb baseball
    psql -e baseball <team.sql

from the command line in the data directory to create a baseball database and load the sample
data into it. This will create two tables called team and game and data into the appropriate
tables.

The connection string in Zope should be:

    baseball@localhost:5432 your_user_name if you wish to use TCP/IP and have specified
    the -i flag when starting the postmaster, or

    baseball your_user_name if you wish to use Unix sockets.

To Do
-----

The variable "desc" in file db.py is supposed to receive the name, type and width of each
field in the query result. Unfortunately, the _pgmodule extension does not provide a
method which returns the type and width for each field. As a stop-gap, I added a simple
findType method and took the field width to be the width of the field header returned
by postgresql. I imagine the best fix would be to modify the extension module
to return the required information. Nonetheless, this fix worked with queries I did on the sample
tables mentioned above. Doubtless, this will require more work. Please send me any bug
fixes and suggestions you come up with.

Note: As of March 1, 1999, I've had no reports of anyone having problems with this so I'll
      leave it alone for now. I didn't take the time to look at PyGreSQL-2.3 to see if it
      provides a better solution for this.

Maury Davis
mjd@networklogic.com