

Commands:

pg_conndefaults

pg_connect dbName [-host hostName] [-port portNumber] [-tty pqtty] ?-connhandle connHandleName?

    The result is either an error message or a handle for a database 
    connection.  Handles start with the prefix "pgp".  

    (DEPRECATED, use pg_connect -conninfo instead.)

pg_connect -conninfo conninfoString ?-connhandle connHandleName?

    The modern way to connect, all necessary information required for
    the connection (host, port, database, user, password, etc.) is
    specified in the connect info string.

pg_connect -connlist name_value_list ?-connhandle connHandleName?
    This was added to better suit Tcl style of data structures. You can set
    an array with the connection info, such as:

        array set myinfo {host myhost port 5000}

    And then do:
       
        pg_connect -connlist [array get myinfo]


pg_dbinfo connections
    This returns the currect connection handles

pg_dbinfo results $conn
    This returns the currect result handles for connection $conn

pg_disconnect $conn

    Close a backend connection.

pg_exec $conn query

    Send a query string to the backend connection.

    The return result is either an error message or a handle for a query result.
    Handles start with the prefix "pgp".


pg_select

    send a select query string to the backend connection

     syntax:
	 pg_select connection query var proc

     The query must be a select statement
     The var is used in the proc as an array
     The proc is run once for each row found

     example:

    set conn [pg_connect www]

    pg_select $conn "select * from users" user {
        parray user
    }

    pg_disconnect $conn


    You can "continue" and "return" in the body and it'll do the
    expected thing.
 
pg_result

    Get information about the results of a query.

    pg_result result ?option?

 the options are:

	-status		the status of the result

	-error		the error message, if the status indicates error; 
                             otherwise an empty string

	-conn		the connection that produced the result

	-oid		if command was an INSERT, the OID of the inserted tuple

	-numTuples	the number of tuples in the query

	-numAttrs	returns the number of attributes returned by the query

	-assign arrayName
			assign the results to an array, using 
			    subscripts of the form (tupno,attributeName)

	-assignbyidx arrayName ?appendstr?
			assign the results to an array using the first 
                            field's value as a key.

			All but the first field of each tuple are stored, 
                            using subscripts of the form 
                            (field0value,attributeNameappendstr)

	-getTuple tupleNumber
			returns the values of the tuple in a list

	-tupleArray tupleNumber arrayName
			stores the values of the tuple in array arrayName, 
                            indexed by the attributes returned

	-attributes     returns a list of the name/type pairs of the tuple 
                            attributes

	-lAttributes    returns a list of the {name type len} entries of the 
                            tuple attributes

	-list		returns a list with the results

	-llist		returns a list of lists with the results

	-dict		returns a dict object with the results

	-clear		clear the result buffer. Do not reuse after this

	-null_value_string ?value?
				if value is specified or has been set via the connection's
				pg_null_value_string, this string value is returned for
				the various query styles when the corresponding row element
				is NULL.


pg_results
    returns a list of result handles for a particular connection

    syntax:
        pg_results connhandle

pg_execute

     Send a query string to the backend connection and process the result.

     syntax:
       pg_execute ?-array name? ?-oid varname? connection query ?loop_body?

     The return result is the number of tuples processed. If the query
     returns tuples (i.e. a SELECT statement), the result is placed into
     variables.


pg_lo_open

    Open a large object

    syntax:

	pg_lo_open conn objOid mode

	...where mode can be either 'r', 'w', or 'rw'

pg_lo_close

    close a large object

    syntax:

	pg_lo_close conn fd

pg_lo_read

    reads at most len bytes from a large object into a variable named bufVar

    syntax:

	pg_lo_read conn fd bufVar len

    bufVar is the name of a variable in which to start the contents of the read

pg_lo_write
    write at most len bytes to a large object

    pg_lo_write conn fd buf len

pg_lo_seek
    seek to a certain position in a large object

    syntax
	pg_lo_seek conn fd offset whence

    whence can be either
	"SEEK_CUR", "SEEK_END", or "SEEK_SET"

pg_lo_creat

    create a new large object with mode

    syntax:
	pg_lo_creat conn mode

    mode can be any OR'ing together of INV_READ, INV_WRITE.
    For now, we don't support any additional storage managers.

pg_lo_tell
    returns the current seek location of the large object

    syntax:
	pg_lo_tell conn fd


pg_lo_creat

pg_lo_unlink
    unlink a file based on lobject id

    syntax:
	pg_lo_unlink conn lobjId

pg_lo_import
    import a UNIX file into an (inversion) large object
    returns the oid of that object upon success
    returns InvalidOid upon failure

    syntax:
	pg_lo_import conn filename

pg_lo_export
    export an inversion large object to a UNIX file

    syntax:
	pg_lo_export conn lobjId filename


pg_listen
        create or remove a callback request for notifies on a given name

 syntax:
   pg_listen conn notifyname ?callbackcommand?
                 
   With a fourth arg, creates or changes the callback command for
   notifies on the given name; without, cancels the callback request.

   Callbacks can occur whenever Tcl is executing its event loop.
   This is the normal idle loop in Tk; in plain tclsh applications,
   vwait or update can be used to enter the Tcl event loop.

pg_quote
    quotes a string suitable for SQL statements to the backend
   
    syntax:
        pg_quote string

pg_escape_string
    escapes a string suitable for SQL statements to the backend

    syntax:
        pg_escape_string string

pg_escape_bytea
    escapes a binary string suitable for SQL statements to the backend

    syntax:
        pg_escape_bytea binaryString

pg_unescape_bytea
    unescapes a binary string that was stored in the backend

    syntax:
        pg_unescape_bytea binaryString
