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_truncate -- Truncate a large object to a given length
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

Command Namespace Command Description
pg_connect pg::connect open a connection to the server
pg_dbinfo pg::dbinfo returns the current connection/result handles
pg_disconnect pg::disconnect close a connection to the server
pg_conndefaults pg::conndefaults get connection options and their defaults
pg_exec pg::sqlexec send a command to the server
pg_exec_prepared pg::exec_prepared send a request to execute a prepared statement, with parameters
pg_result pg::result get information about a command result
pg_select pg::select loop over the result of a query
pg_execute pg::execute send a query and optionally loop over the results
pg_null_value_string pg::null_value_string set string to be returned for null values in query results
pg_quote pg::quote escape a string for inclusion into SQL statements
pg_escape_string pg::escape_string escape a binary string for inclusion into SQL statements
pg_escape_bytea pg::escape_bytea escape a binary string for inclusion into SQL statements
pg_unescape_bytea pg::unescape_bytea unescape a binary string from the backend
pg_listen pg::listen set or change a callback for asynchronous notification messages
pg_on_connection_loss pg::on_connection_loss set or change a callback for unexpected connection loss
pg_sendquery pg::sendquery issue pg_exec-style command asynchronously
pg_sendquery_prepared pg::sendquery_prepared send an asynchronous request to execute a prepared statement, with parameters
pg_getresult pg::getresult check on results from asynchronously issued commands
pg_isbusy pg::isbusy check to see if the connection is busy processing a query
pg_blocking pg::blocking set a database connection to be either blocking or nonblocking
pg_cancelrequest pg::cancelrequest request PostgreSQL abandon processing of the current command
pg_lo_creat pg::lo_creat create a large object
pg_lo_open pg::lo_open open a large object
pg_lo_close pg::lo_close close a large object
pg_lo_read pg::lo_read read from a large object
pg_lo_write pg::lo_write write to a large object
pg_lo_lseek pg::lo_lseek seek to a position in a large object
pg_lo_tell pg::lo_tell return the current seek position of a large object
pg_lo_truncate pg::lo_truncate Truncate (or pad) a large object to a specified length
pg_lo_unlink pg::lo_unlink delete a large object
pg_lo_import pg::lo_import import a large object from a file
pg_lo_export pg::lo_export export 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.