This is pgin.tcl/README, describing pgin.tcl: A PostgreSQL interface in Tcl
Last updated for pgin.tcl-1.5.0 on 2003-06-30
-----------------------------------------------------------------------------

OVERVIEW:

This is a pure-Tcl interface to the PostgreSQL Database backend.  It
implements almost all the commands in libpgtcl, the primary Tcl interface
to PostgreSQL, plus it has some extensions.

I wrote this to be able to use Tcl/Tk database clients on platforms where
the PostgreSQL client library (libpq) and the Tcl interface (libpgtcl) are
not available (or were not available at the time, or were too much trouble
to build).

This script uses the Tcl binary data and TCP socket features to communicate
directly with a PostgreSQL database server, using the internal PostgreSQL
frontend/backend protocol.  This protocol is well documented but subject to
change at any time by the PostgreSQL developers.  You've been warned.


CONTENTS:

  DOCUMENTATION:
           Note: In the zip distribution only, these files
           have a ".txt" extension and MS-DOS line endings.
    README ........... This file
    COPYING .......... The license for pgin.tcl (BSD/Berkeley Open Source)
    NEWS ............. Release information
    Changelog ........ Detailed change log and history
    REFERENCE ........ Reference documentation for programmers using pgin.tcl
    INTERNALS ........ Some information about the innards of pgin.tcl

  SCRIPTS:

    pgin.tcl ......... This is the complete implementation of the interface.
    tkpsql.tcl ....... An example wish script for interactive database querying


FEATURES:

+ Written completely in Tcl 
+ Implements virtually all the standard libpgtcl calls
+ Does large object calls
+ Supports listen/notify
+ Supports replacing the notice handler (extension to libpgtcl)
+ Supports the new pg_execute call
+ Supports PostgreSQL MD5 challenge/response authentication
+ New pg_result -cmdTuples returns the number of tuples affected by an 
  INSERT, DELETE, or UPDATE (extension to libpgtcl, may be in PostgreSQL 7.4)
+ Supports user-defined result value for database NULL (extension to libpgtcl)
+ Implements new pg_result -list, and pg_result -llist (as found in new 
  beta libpgtcl)
+ Implements new pg_escape_string (in beta libpgtcl CVS)

LIMITATIONS and DIFFERENCES:

+ pg_connect supports only the newer "-conninfo" style.
+ Does not support $HOME/.pgpass password file
+ Only talks to v2 backend (PostgreSQL 6.4 or higher required).
+ Uses only TCP/IP sockets (defaults host to localhost, postmaster needs -i)
+ Notification messages are only received while reading query results.
+ Performance isn't great, especially when retrieving large amounts of data.
+ The values of connection handles and result handles are of a different
  format than libpgtcl, but nobody should be relying on these anyway.
+ No pg_on_connection_loss (New at PostgreSQL 7.3)
+ No asynchronous calls (found in beta libpgtcl)
+ Support for COPY FROM/TO is not 100% compatible with libpgtcl
+ With libpgtcl, you can have up to 128 active result structures (so leaks
  can be caught). pgin.tcl has no limits and will not catch result structure
  leaks.


INSTALLATION AND USAGE:

There is no install script. Just copy the script "pgin.tcl" anywhere your
application can access it.  In your application, insert "source .../pgin.tcl"
at the top level, where ... is the directory. This must be run at the top
level, so if you need it inside a proc use uplevel as shown below.

Note: pgin.tcl is not yet a Tcl package, so you can't use {package require}
to load it.

You can use the included "tkpsql.tcl" script to try it out.  This is a
simple interactive GUI program to issue database queries, vaguely like the
Sybase ASA "dbisql" program.  On **ix systems, type "wish tkpsql.tcl" to
start it; under Windows you should be able to double click on its icon. You
need to press F1 or click on the Run button after each query.

If you run tkpsql under "pgtksh" instead of "wish", it won't load pgin.tcl.
You can use this same method in your own scripts to conditionally load
pgin.tcl if needed. Here's how:
    if {[info commands pg_connect] == ""} {
      uplevel #0 {source [file join [file dirname [info script]] pgin.tcl]}
    }
If you run this under pgtclsh or pgtksh, it does nothing, otherwise it loads
pgin.tcl from the same directory as the script.


DOES IT WORK WITH PGACCESS?

Recent versions (CVS and/or snapshots after 2003-03-23) of PGAccess include
pgin.tcl and some changes to PGAccess to support it. You need to use the
"-pgintcl" command-line option to activate it. The next full release of
PGAccess should include pgin.tcl.

More information on PGAccess can be found at http://www.pgaccess.org

PGAccess -pgintcl on Windows supports PostgreSQL MD5 password protocol,
which is not available with the libpgtcl DLLs.
