What is this?
------------

This module implements a simple NaviServer/AOLserver database services
driver.  A database driver is a module which interfaces between the
NaviServer database-independent nsdb module and the API of a particular
DBMS.  A database driver's job is to open connections, send SQL
statements, and translate the results into the form used by nsdb.  In
this case, the driver is for the PostgreSQL ORDBMS from The PostgreSQL
Global Development Group.  This is the official driver for the OpenACS
project. PostgreSQL can be downloaded and installed on most Unix
systems.  To use this driver, you must have PostgreSQL installed on
your system.  For more information on PostgreSQL or to download the
code, open:

        http://www.postgresql.org

What's new?
-----------

See Changelog.

How does it work?
----------------

Driver modules look much like ordinary AOLserver modules but are
loaded differently.  Instead of being listed with other modules in the
[ns/server/<server-name>/modules] configuration section, a database
driver is listed in the [ns/db/drivers] section and nsdb does
the loading.  The database driver initialization function normally does
little more than call the nsdb Ns_DbRegisterDriver() function with an
array of pointers to functions.  The functions are then later used by
nsdb to open database connections and send and process queries.  This
architecture is much like ODBC on Windows.  In addition to open,
select, and getrow functions, the driver also provides system catalog
functions and a function for initializing a virtual server.  The
virtual server initialization function is called each time nsdb is
loaded into a virtual server.  In this case, the server initialization
function, Ns_PgServerInit, adds the "ns_pg" Tcl command to the server's
Tcl interpreters which can be used to fetch information about an active
PostgreSQL connection in a Tcl script.

Contributors to this file include:

        Don Baccus		<dhogaza@pacifier.com>
        Lamar Owen		<lamar.owen@wgcr.org>
        Jan Wieck		<wieck@debis.com>
        Keith Pasket		(SDL/USU)
        Scott Cannon, Jr.	(SDL/USU)
        Dan Wickstrom           <danw@rtp.ericsson.se>
        Scott S. Goodwin	<scott@scottg.net>
        Gustaf Neumann          <neumann@wu-wien.ac.at>

Original example driver by Jim Davidson


SAMPLE CONFIGURATION:

Use something like the following snippet in the configuration of
NaviServer. We assume here that the Tcl variables db_host, db_port,
db_name and db_user as set accordingly.

    ===========================================================
    ns_section ns/db/pools {
       ns_param   pool1              "Pool 1"
    }
    ns_section ns/db/pool/pool1 {
       # ns_param	maxidle            0
       # ns_param	maxopen            0
       ns_param   connections        15
       ns_param   LogMinDuration     0.01   ;# when SQL logging is on, log only statements above this duration
       ns_param   logsqlerrors       true
       ns_param   driver             postgres
       ns_param   datasource         "${db_host}:${db_port}:dbname=${db_name}"
       ns_param   user               $db_user
       ns_param   password           ""
    }
    ===========================================================

If the database is reachable just via SSL, the appropriate
PostgreSQL "conninfo" parameters can be added to the datasource.

    ===========================================================
    ...
       ns_param   datasource         "${db_host}:${db_port}:dbname=${db_name} sslmode=require"
    ...
    ===========================================================


Provided API:

 - ns_pg_bind:

   This is a variant of the "ns_db" API for evaluating PostgreSQL
   statements, supporting bind variables (denoted in SQL statements
   starting with a ":"). The values for the bind variables are either
   from the ns_set provided via the "-bind" option or from the calling
   environment.

       ns_pg_bind dml     /handle/ -bind /bind/ /sql/
       ns_pg_bind 1row    /handle/ -bind /bind/ /sql/
       ns_pg_bind 0or1row /handle/ -bind /bind/ /sql/
       ns_pg_bind select  /handle/ -bind /bind/ /sql/
       ns_pg_bind exec    /handle/ -bind /bind/ /sql/

 - ns_pg:

   ns_pg is a variant of the "ns_db" API for directly interacting with
   the PostgreSQL client library, including BLOB support (which is
   probably outdated).

       ns_pg blob_dml_file    /handle/ /blobId/ /filename/
       ns_pg blob_get         /handle/ /blobId/
       ns_pg blob_put         /handle/ /blobId/ /value/
       ns_pg blob_select_file /handle/ /blobId/ /filename/
       ns_pg blob_write       /handle/ /blobId/
       ns_pg db               /handle/
       ns_pg error            /handle/
       ns_pg host             /handle/
       ns_pg ntuples          /handle/
       ns_pg number           /handle/
       ns_pg options          /handle/
       ns_pg pid              /handle/
       ns_pg port             /handle/
       ns_pg status           /handle/

 - ns_pg_prepare /sql/

   Return a dict building a prepared statement for the passed-in SQL
   statement. The dict contains the keys "sql" and "args".


DEVELOPER'S GUIDE:

Run 'make help' for developer information.

The build step needs from PostgreSQL
 - the include file libpq-fe.h
 - the library libpq.*

Examples for a build operation:

     export PG=/usr/local/pg16
     make PGLIB=$PG/lib PGINCLUDE=$PG/include

     make PGINCLUDE=/usr/include/postgresql

To build/install on a non-standard path of PostgreSQL libraties, use e.g.:

     export PG=/usr/local/pg16
     make PGLIB=$PG/lib PGINCLUDE=$PG/include
     make PGLIB=$PG/lib PGINCLUDE=$PG/include install

In case NaviServer is installed at a differet location, use e.g.

     make PGLIB=... PGINCLUDE=... NAVISERVER=/opt/local/ns499/
     make PGLIB=... PGINCLUDE=... NAVISERVER=/opt/local/ns499/ install

Under MacPorts, you might use something like:

     PGPATH=postgresql16 && make PGLIB=/opt/local/lib/$PGPATH/ PGINCLUDE=/opt/local/include/$PGPATH/

For extended code checking via cppchek, one might use e.g.

     PGPATH=postgresql16 && make PGLIB=/opt/local/lib/$PGPATH/ PGINCLUDE=/opt/local/include/$PGPATH/ cppcheck

See the Makefile for further information on building this module.