postgres.pike

/*
 * This is part of the Postgres module for Pike.
 *
 * $Id: postgres.pike,v 1.32 2008/07/05 11:17:45 srb Exp $
 *
 */

//! This is an interface to the Postgres (Postgres95, pgsql) database
//! server. This module may or may not be availible on your Pike,
//! depending whether the appropriate include and library files could
//! be found at compile-time. Note that you @b{do not@} need to have a
//! Postgres server running on your host to use this module: you can
//! connect to the database over a TCP/IP socket.
//!
//! @note
//! Also note that @b{this module uses blocking I/O@} I/O to connect
//! to the server. Postgres is quite slow, and so you might want to
//! consider this particular aspect. It is (at least should be)
//! thread-safe, and so it can be used in a multithread environment.
//!
//! The behavior of the Postgres C API also depends on certain
//! environment variables defined in the environment of the Pike
//! interpreter.
//!
//! @string
//!   @value "PGHOST"
//!     Sets the name of the default host to connect to. It defaults
//! 	to @expr{"localhost"@}.
//!   @value "PGOPTIONS"
//!     Sets some extra flags for the frontend-backend connection.
//!     @b{do not set@} unless you're sure of what you're doing.
//!   @value "PGPORT"
//!     Sets the default port to connect to, otherwise it will use
//!     compile-time defaults (that is: the time you compiled the postgres
//! 	library, not the Pike driver).
//!   @value "PGTTY"
//!     Sets the file to be used for Postgres frontend debugging.
//!     Do not use, unless you're sure of what you're doing.
//!   @value "PGDATABASE"
//!     Sets the default database to connect to.
//!   @value "PGREALM"
//!     Sets the default realm for Kerberos authentication. I never used
//!   	this, so I can't help you.
//! @endstring
//!
//! Refer to the Postgres documentation for further details.
//!
//! @seealso
//!  @[Sql.Sql], @[Postgres.postgres], @[Sql.postgres_result]

#pike __REAL_VERSION__

#if constant(Postgres.postgres)

#define ERROR(X) throw (({X,backtrace()}))

inherit Postgres.postgres: mo;
private protected mixed  callout;
private string has_relexpires = "unknown";

//! @decl void select_db(string dbname)
//!
//! This function allows you to connect to a database. Due to
//! restrictions of the Postgres frontend-backend protocol, you always
//! have to be connected to a database, so in fact this function just
//! allows you to connect to a different database on the same server.
//!
//! @note
//! This function @b{can@} raise exceptions if something goes wrong
//! (backend process not running, not enough permissions..)