This is pgintcl/NEWS, release notes and change information for pgintcl.
The project home page is: http://sourceforge.net/projects/pgintcl/
-----------------------------------------------------------------------------

* 2017-11-12 Released version 3.5.1

  This version contains a small fix for PostgreSQL-10.x.

  + The pg_server_version command now works with the new 2-part version
    numbers used starting with PostgreSQL-10.0, as well as with the 3-part
    version numbers in older releases.  Note that the PostgreSQL-10.1 version
    number as an integer is 100001, not 100100. See the PostgreSQL-10.x libpq
    documentation for PQserverVersion for an explanation.

* 2013-10-06 Released version 3.5.0

  This version adds 5 new commands, new pg_connect options, and new error
  field codes for pg_result.

  + New commands pg_escape_literal, which is an alternative to pg_quote, and
    pg_escape_identifier, for escaping SQL identifiers. [Feature Request #5]

  + New connection options are available in pg_connect. This command now
    supports a "-connlist {list}" form for option parameters. (The syntax
    is from Flightaware Pgtcl, but the implementation is new, and not
    completely compatible.) The advantage of using this form is that
    it does not require quoting or escaping, especially for the password.

    Also, pg_connect now accepts a URI for a connection string, as described
    in the PostgreSQL manual, for example:
       pg_connect -conninfo postgresql://myuser:secretd@host.example.com/dbname
    Note: pgintcl does not support options in URI connection strings.
    [Feature Request #3]

  + New commands for 64-bit Large Object offsets: pg_lo_lseek64,
    pg_lo_tell64, and pg_lo_truncate64. These only work when connected to
    a PostgreSQL-9.3.0 or higher server. [Feature Request #2]

  + pg_result -error and -errorField now support 5 new field codes, which
    were added in PostgreSQL-9.3.0 (and only return data when connected to
    a PostgreSQL-9.3.0 or higher server). These provide access to the
    schema, table, column, and constraint name.  [Feature Request #4]

    Compatibility Warning:

    PostgreSQL-9.2.0 started using lower case letters as the value of the
    new PG_DIAG_* symbols. This conflicts with case insensitive field codes
    in previous versions of pgintcl. Starting with pgintcl-3.5.0, field code
    single-character abbreviations are now case sensitive. This will require
    changes to scripts, if they used single-character lower case letters
    as field codes.  The full field code names remain case insensitive.
    For example:
        Both of these worked before, and continue to work:
           pg_result $res -errorField SEVERITY
           pg_result $res -errorField severity
        The single-character code for SEVERITY is 'S'. Starting with this
        release, an upper case 'S' must be used, as 's' is now used for
        SCHEMA_NAME.
           pg_result $res -errorField s
               Returned the error severity in previous releases.
               Returns the error object schema name in this release.


  This release was tested with Tcl-8.6.0 and PostgreSQL-9.3.0, as well as
  several older versions.


* 2011-09-17 Released version 3.4.0

  This version adds 2 new commands and 1 new command option, and fixes 1 bug.
  + New command pg_backend_pid to get the backend process ID.
  + New command pg_server_version to get the server version as an intger.
  + New -pid option to pg_listen, to pass the notifying client's backend
    process ID to the notification callback.
  + Bug fix: fold the notification name in pg_listen (also called channel name)
    to lower case, unless it is in double quotes (which are stripped off).
    This now works the same as SQL and pgtclng, but is not compatible with
    previous releases of pgintcl if pg_listen was used with a mixed-case or
    quoted name. For maximum compatibility, use unquoted lower case names in
    notifications, both with SQL and pgintcl.

  In addition to Tcl-8.4.x and Tcl-8.5.x, pgin.tcl was tested with Tcl-8.6
  (which is currently in beta). It was also tested with the just-released
  PostgreSQL-9.1


* 2011-03-21 Released version 3.3.0

  This version adds one new feature: pg_result $r -dict, which returns the
  query result as a Tcl dictionary. The idea for this feature came from
  the pgfoundry.org 'pgtcl' project. This feature requires Tcl-8.5 or higher.

  pgin.tcl now requires Tcl-8.4 or higher. Previous versions claimed to
  require Tcl-8.3 or higher, but were no longer tested with Tcl-8.3.


* 2010-10-11 Released version 3.2.1

  This version fixes bug #1010929, "pg_unescape_bytea fails with
  PostgreSQL-9.0". pg_unescape_bytea now handles 'hex' mode decoding, as well
  as 'escape' mode, for bytea types. It no longer fails to decode a bytea
  value selected from a PostgreSQL-9.0 server which has the default
  bytea_output=hex configuration setting.

     Note: Pgintcl-3.2.0 was withdrawn soon after release because of this
     problem, although 3.2.0 did not introduce the problem. The problem exists
     with all releases of all interfaces, and is caused by PostgreSQL-9.0
     defaulting to the new "hex" mode encoding in bytea type output. This is
     incompatible with all interfaces designed pre-9.0. So the same problem
     exists with all previous versions of Pgintcl, as well as any libpq-based
     interface built with pre-9.0 libpq.  However, since pgintcl-3.2.0 was
     supposed to be a release for use with PostgreSQL-9.0, it was felt that
     this problem needed to be fixed before allowing a release.


* 2010-10-10 Released version 3.2.0 (Note: release withdrawn - see note above.)

  This version has one new feature and one change for PostgreSQL-9.0.0:

  + Notification messages can now include a payload, which is passed to
    the notification listener callback proc. For example:
    Given (in one session):
        pg_listen $db my_channel my_callback_proc

    Then (possibly in another session):
        SQL> NOTIFY my_channel, 'the payload'
    This will result in execution of:  my_callback_proc "the payload"
    in the original session.

    And:
           SQL> NOTIFY my_channel
     or:   SQL> NOTIFY my_channel, ''
    This will result in execution of:  my_callback_proc
    in the original session.

  Compatibility Warning:
    This applies only if you use pg_listen to set up a notification listener
    callback procedure.

    Your listener callback should be defined to accept an optional argument
    for the payload, for example:   proc listen_handler {{payload ""}} { ... }
    Starting with version 3.2.0, pgin.tcl will pass a payload argument to the
    handler if a non-empty payload is provided in the SQL command. If an empty
    payload is provided, or no payload (including any usage with a PostgreSQL
    server older than 9.0.0), pgin.tcl will not supply the argument to the
    handler. This is intended to improve compatibility with older scripts that
    would throw an error if provided an unexpected argument.

    If you do not update your listener callback to have an optional argument,
    and you never include a payload in the notification SQL, your script will
    not have any problems. However, note that anyone who can connect to the
    database can send a notification (if they know the 'channel' name used
    in the pg_listen command), and they can include a payload. If your listener
    callback does not expect a payload argument, it will throw a background
    error (which may or may not terminate the script) if it receives such a
    payload argument.

  + Change in pg_result $result_handle -cmdTuples:
    It seems that starting with PostgreSQL-9.0, the function that this
    emulates (libpq PQcmdTuples) was extended to return the number of
    rows returned by SELECT. (Prior to this change, an empty string was
    returned for SELECT.) pgin.tcl was modified to work that way, and now
    returns row counts for -cmdTuples after SELECT and other commands.
    However, it is recommended to use -numTuples for SELECT and -cmdTuples
    for commands that modify tables.

* 2009-09-10 Released version 3.1.0

  This version contains four new commands:
  + pg_encrypt_password to encrypt a password for certain SQL commands
  + pg_lo_truncate to truncate a large object
  + pg_describe_cursor to return information about a cursor (portal)
  + pg_describe_prepared to return information about a prepared statement.

  This version adds two options to pg_result, for use with
  pg_describe_prepared to return information about a prepared statement.
  The options are -numParams and -paramTypes.

  In this release, pg_escape_string, pg_quote, and pg_escape_bytea
  accept an optional connection parameter, which allows pgin.tcl to
  use connection-specific information to properly handle string escaping.
  For more information, see the REFERENCE file.

  This is the first release that can properly escape strings and bytea's
  if standard_conforming_strings is ON (thus backslashes should not be
  doubled). This works as long as the client either: uses a single database
  connection, or uses multiple database connections all of which have the
  same setting for standard_conforming_strings, or always supplies the
  connection parameter to pg_escape_string, pg_quote, and pg_escape_bytea.

  The procedure that implements the backend reply protocol has been
  rewritten to more completely check that only expected messages are
  received, depending on the processing mode.

  Fixed error handling in pg_lo_import and pg_lo_export, to make sure
  the file is closed if an error occurs.


* 2008-04-26 Released version 3.0.2

  This version contains a bug fix in executing prepared queries with
  extended (non-ASCII) character query parameters.
  + Fix pg_exec_prepared to use the parameter length after encoding.
  Thanks to giorgio_v -at- mac.com for finding the bug.

* 2006-08-30 Released version 3.0.1

  This is the first release on pgfoundry.org. Previous releases were on
  gborg.postgresql.org. The release documentation was changed to reflect
  the new URL.

+ Fix/Change: pg_escape_bytea was changed to match a change in the
  PostgreSQL-8.1 libpq library function PQescapeBytea. For a single
  quote in the argument string, it now returns two quotes ('') instead
  of backslash-quote (\').


* 2005-04-16 Released beta version 3.0.0

  This is a beta release which adds character set encoding/decoding to fix
  misbehavior of pgin.tcl when used with non-ASCII character sets. Like
  Pgtcl, pgtcl-ng, and libpgtcl, pgin.tcl now sets PostgreSQL
  client_encoding to Unicode, and sends/receives UTF-8 encoded text
  strings to/from PostgreSQL.  Pgin.tcl also recodes COPY data, which
  the libpq-based Tcl interfaces do not correctly handle at this time.

  (Thanks to pfm developer Willem Herremans, who first convinced me that
  encoding was broken in pgin.tcl, then provided the understanding of how
  Tcl and PostgreSQL handle character set conversions and how to get them
  to play nicely together.)

  There are no changes to the pgin.tcl command usage from 2.2.0.

  At this time, it hasn't been decided if there will be two versions of
  pgin.tcl - one for Unicode, and one without - or if only the Unicode
  encoding version will suffice.


* 2004-11-11 Released version 2.2.0

+ New commands: pg_escape_bytea and pg_unescape_bytea, which emulate the
  libpq functions PQescapeBytea() and PQunescapeBytea().  These were
  suggest by J. Levan, with a fast implementation of pg_unescape_bytea
  provided by B. Riefenstahl. Note however that pg_escape_bytea is slow.
  (If possible, use prepared queries in binary mode for bytea types,
  not escape/unescape.) Also note that pg_unescape_bytea only produces
  valid results for data formated by the PostgreSQL backend bytea
  output function; it is not an accurate emulation of PQunescapeBytea().

+ Compatibility fixes for extended error codes.
  The Gborg pgtcl project (Karl Lehenbauer) release 1.4 contains a way to
  fetch extended error field values which is different from the way
  pgin.tcl and pgtclng already did it, but better. They extended
  pg_result -error, where I added a new subcommand pg_result -errorField.
  For compatibility, pg_result -error and pg_result -errorField are now
  identical. If an optional code is supplied, that error field value
  will be returned. Also added variations on the code names that Gborg
  pgtcl uses.

* Performance fix for prepared queries: As found by Nigel J. Andrews,
  prepared queries were slower than they should be. The fix was to
  allow Tcl to buffer up the multiple messages making up a prepared
  query execution; for some reason this avoids a TCP/IP delay.


* 2004-06-01 Released version 2.1.0

+ New command: pg_exec_params, parse/bind/execute extended query protocol.
  This complements pg_exec_prepared, which works with a pre-prepared
  statement. Both are binary safe.

+ pg_exec can take optional arguments which makes it a parameterized
  query like pg_exec_params, but with all text parameters and results.
  (idea from karl's implementation in Gborg pgtcl CVS).

+ New command: pg_quote, to quote and escape a string (from karl's
  implementation in Gborg pgtcl CVS), variation on pg_escape_string (which
  unfortunately was removed from Gborg pgtcl CVS, breaking compatibility).
  pgin.tcl will support both pg_escape_string and pg_quote.

+ Bug fix (GBorg #802) Fix typo in error return if pg_execute script throws
   an error (from n.j.andrews-at-investsystems.co.uk). Testing found
   another problem here; fixed error value returned.


* 2004-02-25 Version 2.0.1 (not released to Gborg)

+ New command option: pg_result $res -cmdStatus (suggested by levanj)
  Returns the command status tag, e.g. "INSERT 10020", for the result $res.


* 2004-02-14 Released version 2.0.0

Changes since beta release 2.0b1:

+ Pgin.tcl can now be installed as a Tcl package.

The package name is 'pgintcl'. (Not 'pgtcl', which is used by libpgtcl.
Since pgintcl is not 100% compatible, I didn't want to use the same name.
Also the version numbers of the two interfaces do not track.)
This means if you install pgin.tcl and pkgIndex.tcl into your package
directories, you can use {package require pgintcl} to load it.


+ Removed feature: Fetch all parameters with {pg_parameter_status $db}

Libpq does not support this, so to be compatible with future libpq-based
versions of the pgtcl interface, this feature was removed. You must supply
pg_parameter_status with a parameter name.


+ Documented incompatibility: pg_exec_prepared mixed text/binary return types

Although the pg_exec_prepared command in pgin.tcl supports mixing text and
binary return types, libpq does not, so libpq based versions of the pgtcl
interface will not work with these queries. This has now been noted in the
documentation, but support for these queries was not removed from pgin.tcl.


+ Incompatible feature change: Dealing with NULL values

Previous versions of pgin.tcl supported a command to set the string to be
returned if a database value was NULL: { pg_configure $db nulls "string" }.
This proved to be very inefficient to implement in the libpq-based version
of the pgtcl interface. It could slow down all queries, just to support a
feature that would be rarely used, so it was removed.  Instead, pgin.tcl
now only provides a way to determine if a database value is NULL:
    pg_result $res -getTuple $n
This returns a list of 1s and 0s indicating if each column in tuple $n
is NULL or not.


+ Command name change: Setting notice handler

In previous versions of pgin.tcl you could set the notice handler with:
    pg_configure $db notice ?command?
A new command is now used instead:
    pg_notice_handler $db ?command?
The pg_configure command is retained for compatibility but should not be
used.


+ Large Object Error Handling 'fixed'

Several of the Large Object calls had undefined or unclear error behavior,
and most were not documented in the PostgreSQL manual. Now pgin.tcl will
throw a Tcl error if any error occurs in any large object calls except for
pg_lo_read and pg_lo_write. Those two were already defined to return -1 on
error, so I left them that way even though I would prefer they threw errors.



* 2003-10-30 Released beta version 2.0b1:

This is a major rewrite for PostgreSQL-7.4 using the new V3 FE/BE protocol.

New commands for new features in the V3 protocol:
  pg_parameter_status       => Get backend-supplied parameter value
  pg_transaction_status     => Get current transaction/error state
  pg_exec_prepared          => Execute prepared SQL statement
  pg_result -errorField     => Show extended error code values
  pg_result -lxAttributes   => Show extended field attribute information

Changed commands: pg_configure no longer ignores the connection handle;
nulls and notice settings are now per-connection, not global to all
connections.

Change (incompatible): COPY FROM/TO must use the pg_copy_read and
pg_copy_write commands, and can not read / write the socket directly.
These calls were introduced in pgin.tcl-1.5.0, but were optional in that
version. Changes to the PostgreSQL protocol now makes it impossible for
pgin.tcl to support COPY with direct reading and writing the socket, so use
of these commands is not required.  See REFERENCE for more information.

The included sample tkpsql program has been updated in this release to be
more schema-aware, while still supporting pre-PostgreSQL-7.3 databases
(untested). Some new special queries were added.


* 2003-06-30 Released version 1.5.0

Change: default user name for connection now checks environment variable
USERNAME (for WindowsNT) after PGUSER, USER, and LOGNAME.

Fix: Tkpsql properly gets initial focus on startup on Windows.

Bug fix: Wrong data was returned by pg_result -getTuple, -list, or -llist
when the query contained duplicate column names. (For example:
       SELECT a.id, a.s, b.s FROM a, b WHERE a.id=b.id;
returns two columns named "s", and pg_result -getTuple incorrectly stored
the value from table "b" column "s" twice.) pgin.tcl now internally stores
values indexed by column number, not name, and will correctly store and
return all the values when those access methods are used.  Note that other
access methods such as pg_result -assign, -tupleArray, pg_select, and
pg_execute use the column name as an array index, so they are not
compatible with queries returning duplicate column names.  Also note you
really should use column name aliases when a query generates duplicate
column names. [gborg bug id #503]

New function: pg_escape_string to escape strings for SQL constants. This is
in the libpgtcl CVS.

Bug fixes for empty query. Previously threw an error, now properly handles
an empty query return and sets status to PGRES_EMPTY_QUERY.

Change: pg_result -cmdTuples returns "", not 0, for any SQL other than
Insert/Update/Delete, this apparently being the correct behavior per libpq.

Add support for overloaded fast-path function calls (same function name but
with different argument types).

Fix: pg_execute now handles empty query, COPY FROM, and COPY TO correctly.

New I/O routines for COPY FROM/TO: pg_copy_read and pg_copy_write. There is
no need to use these yet; you can just read and write from the connection
handle. I put them in for testing compatibility with the future PostgreSQL
FE/BE Protocol Version 3 pgin.tcl, where reading/writing from the connection
handle will not work.


* 2003-02-13 Released version 1.3.9

This is the first public release.
