Chapter 1. pgtcl - Tcl Binding Library

Table of Contents
1.1. Overview
1.2. Loading pgtcl into an Application
1.3. pgtcl Command Reference
pg_connect -- open a connection to the server
pg_dbinfo -- returns a list of current open connection/result handles
pg_disconnect -- close a connection to the server
pg_conndefaults -- get connection options and their defaults
pg_exec -- send a command to the server
pg_exec_prepared -- send a request to execute a prepared SQL statement to the server
pg_result -- get information about a command result
pg_select -- loop over the result of a query
pg_execute -- send a query and optionally loop over the results
pg_listen -- set or change a callback for asynchronous notification messages
pg_on_connection_loss -- set or change a callback for unexpected connection loss
pg_sendquery -- send a query string to the backend connection without waiting for a result
pg_sendquery_prepared -- send a request to execute a prepared statement to the backend connection, without waiting for a result
pg_getresult -- process asychronous results
pg_isbusy -- see if a query is busy
pg_blocking -- see or set whether or not a connection is set to blocking or nonblocking
pg_cancelrequest -- request that PostgreSQL abandon processing of the current command
pg_null_value_string -- define a value to be returned for NULL fields distinct from the default value of an empty string.
pg_quote -- escapes a string for inclusion into SQL statements
pg_escape_string -- escapes a string for inclusion into SQL statements. This is the same as pg_quote. It was added for consistency.
pg_escape_bytea -- escapes a binary string for inclusion into SQL statements.
pg_unescape_bytea -- unescapes a binary string.
pg_lo_creat -- create a large object
pg_lo_open -- open a large object
pg_lo_close -- close a large object
pg_lo_read -- read from a large object
pg_lo_write -- write to a large object
pg_lo_lseek -- seek to a position of a large object
pg_lo_tell -- return the current seek position of a large object
pg_lo_unlink -- delete a large object
pg_lo_import -- import a large object from a file
pg_lo_export -- export a large object to a file
1.4. Tcl Namespace Support
1.5. Connection/result handles as commands
1.6. Example Program

pgtcl is a Tcl package for client programs to interface with PostgreSQL servers. It makes most of the functionality of libpq available to Tcl scripts.

1.1. Overview

Table 1-1 gives an overview over the commands available in pgtcl. These commands are described further on subsequent pages.

Table 1-1. pgtcl Commands

CommandNamespace CommandDescription
pg_connectpg::connectopen a connection to the server
pg_dbinfopg::dbinforeturns the current connection/result handles
pg_disconnectpg::disconnectclose a connection to the server
pg_conndefaultspg::conndefaultsget connection options and their defaults
pg_execpg::sqlexecsend a command to the server
pg_exec_preparedpg::exec_preparedsend a request to execute a prepared statement, with parameters
pg_resultpg::resultget information about a command result
pg_selectpg::selectloop over the result of a query
pg_executepg::executesend a query and optionally loop over the results
pg_null_value_stringpg::null_value_stringset string to be returned for null values in query results
pg_quotepg::quoteescape a string for inclusion into SQL statements
pg_escape_stringpg::escape_stringescape a binary string for inclusion into SQL statements
pg_escape_byteapg::escape_byteaescape a binary string for inclusion into SQL statements
pg_unescape_byteapg::unescape_byteaunescape a binary string from the backend
pg_listenpg::listenset or change a callback for asynchronous notification messages
pg_on_connection_losspg::on_connection_lossset or change a callback for unexpected connection loss
pg_sendquerypg::sendqueryissue pg_exec-style command asynchronously
pg_sendquery_preparedpg::sendquery_preparedsend an asynchronous request to execute a prepared statement, with parameters
pg_getresultpg::getresultcheck on results from asynchronously issued commands
pg_isbusypg::isbusycheck to see if the connection is busy processing a query
pg_blockingpg::blockingset a database connection to be either blocking or nonblocking
pg_cancelrequestpg::cancelrequestrequest PostgreSQL abandon processing of the current command
pg_lo_creatpg::lo_creatcreate a large object
pg_lo_openpg::lo_openopen a large object
pg_lo_closepg::lo_closeclose a large object
pg_lo_readpg::lo_readread from a large object
pg_lo_writepg::lo_writewrite to a large object
pg_lo_lseekpg::lo_lseekseek to a position in a large object
pg_lo_tellpg::lo_tellreturn the current seek position of a large object
pg_lo_unlinkpg::lo_unlinkdelete a large object
pg_lo_importpg::lo_importimport a large object from a file
pg_lo_exportpg::lo_exportexport a large object to a file

The pg_lo_* commands are interfaces to the large object features of PostgreSQL. The functions are designed to mimic the analogous file system functions in the standard Unix file system interface. The pg_lo_* commands should be used within a BEGIN/COMMIT transaction block because the descriptor returned by pg_lo_open is only valid for the current transaction. pg_lo_import and pg_lo_export must be used in a BEGIN/COMMIT transaction block.