This is pgin.tcl/README, describing pgin.tcl: A PostgreSQL interface in Tcl
Last updated for pgin.tcl-2.2.0 on 2004-11-11
The project home page is: http://gborg.postgresql.org/project/pgintcl/
-----------------------------------------------------------------------------

OVERVIEW:

This is a pure-Tcl interface to the PostgreSQL Database Management System.
It implements almost all the commands in libpgtcl, the Tcl interface
bundled with PostgreSQL (until release 8.0), plus it has some extensions.
But it is written entirely in Tcl, so does not require compilation for a
specific platform.

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).

pgin.tcl uses the Tcl binary data and TCP socket features to communicate
directly with a PostgreSQL database server, using the internal PostgreSQL
frontend/backend protocol. Therefore, pgin.tcl is dependent on the
protocol, rather than being protected from its details as are libpq-based
applications. This version of pgin.tcl uses version 3 of the PostgreSQL
protocol, and only communicates with PostgreSQL-7.4 and higher servers.

pgin.tcl is also highly compatible with pgtcl-ng, the "Next Generation"
libpq-based implementation of the pgtcl interface. pgtcl-ng can be found at
  http://gborg.postgresql.org/project/pgtclng/
The same test suite is used to verify both interfaces.


REQUIREMENTS:

   Tcl 8.3.1 (minimum), Tcl 8.4.4 or higher (recommended)
   PostgreSQL-7.4 or higher
   Platforms: Linux, Windows NT/2000; should run on all systems which have
       the proper Tcl version, but others are untested.


CONTENTS:

  Documentation:
         Note: In the zip file distribution only, these documentation
         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 and change 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.
    pkgIndex.tcl ..... Package index file
    tkpsql.tcl ....... An example wish script for interactive database querying


FEATURES:

+ Written completely in Tcl 
+ Implements virtually all the standard (bundled) libpgtcl calls
+ Does large object calls
+ Supports listen/notify
+ Supports replacing the notice handler (extension)
+ 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 (feature in PostgreSQL 7.4 libpgtcl)
+ Supports distinguishing NULL database values from empty strings (extension)
+ Implements new pg_result -list, and pg_result -llist (as found Gborg pgtcl)
+ Implements pg_escape_string (was in beta Gborg pgtcl CVS, but removed),
  and pg_quote (from Gborg pgtcl)
+ Execute prepared statements with: pg_exec_prepared, including sending
  and receiving un-escaped binary data (extension)
+ Get PostgreSQL parameters with: pg_parameter_status (extension)
+ Get transaction status with: pg_transaction_status (extension)
+ Access expanded error message fields with: pg_result -errorField
  (extension). This was extended [at 2.2.0] to also apply to pg_result -error
  for compatibility with Gborg pgtcl.
+ Access extended attribute information with: pg_result -lxAttributes
  (extension)
+ Get command status tag with pg_result -cmdStatus (extension) [New: 2.0.1]
+ Separate parse and execute with: pg_exec_params, binary safe [New: 2.1.0]
+ Escape/unescape bytea with: pg_escape_bytea, pg_unescape_bytea [New: 2.2.0]


LIMITATIONS and DIFFERENCES:

+ pg_connect supports only the newer "-conninfo" style.
+ Does not support $HOME/.pgpass password file.
+ Only talks to v3 backend (PostgreSQL 7.4 or higher required).
+ Uses only TCP/IP sockets (defaults host to localhost, postmaster needs -i),
  does not support Unix Domain sockets.
+ 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 Gborg pgtcl and pgtcl-ng).
+ Support for COPY FROM/TO is not compatible with other versions of the
  interface - must use pg_copy_read and pg_copy_write, no I/O directly to
  connection handle.
+ With other pgtcl's, 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.
+ [Newly added at 2.1.0] Do not use "return -code N" (for N>4) in the script
  body for pg_select or pg_execute, because the effect is not well defined.
  You can safely use return, break, continue, and error (either directly
  or via return -code).
+ [Newly added at 2.2.0] pg_escape_bytea (and pg_unescape_bytea, to a
  lesser extent) is quite slow. Using it on large bytea objects is not
  recommended; you should use binary prepared queries instead.


RELEASE ISSUES:

There are some incompatibilities between this release and pre-2.0.0 releases:
  + pg_parameter_status can no longer fetch all parameters at once;
  + "pg_configure nulls" option is no longer available. The only way
    to distinguish NULL from empty string now is with pg_result -getNull.
  + Changes in large object call error handling.
  + COPY FROM/TO must use pg_copy_read/pg_copy_write; you cannot read or
    write copy data from the connection.
You will have to change your application if it relies on behavior which
changed.  See the file NEWS for more information.


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.

Optionally, you can install and use pgin.tcl as a Tcl package. You should
copy pgin.tcl and pkgIndex.tcl into a sub-directory of your Tcl
installation package library root directory (or you can extend auto_path:
see the Tcl documentation for the 'package' and 'pkgMkIndex' commands).
Then your application can load pgin.tcl with the following:
           package require pgintcl


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 it from
Explorer. 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?

This release has not been tested with PGAccess. The following applies
to previous versions of pgin.tcl:

Newer 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 was not available with the included libpgtcl DLLs.


WHAT ABOUT PostgreSQL 8.0?

At this time, PostgreSQL-8 is in beta. Pgin.tcl-2.2.0 was tested with
PostgreSQL-8.0.0beta3 without problems. No problems are anticipated when
PostgreSQL-8 is releases, as the backend protocol apparently is not
changing.

