pqxx::connection_base Class Reference

connection_base abstract base class; represents a connection to a database. More...

#include <connection_base.hxx>

Inheritance diagram for pqxx::connection_base:

List of all members.

Public Member Functions
	connection_base (const PGSTD::string &ConnInfo)
	Set up connection based on PostgreSQL connection string.
	connection_base (const char ConnInfo[])
	Set up connection based on PostgreSQL connection string.
virtual	~connection_base ()=0
	Destructor. Implicitly closes the connection.
void	disconnect () throw ()
	Explicitly close connection.
bool	is_open () const throw ()
	Is this connection open at the moment?
template<typename TRANSACTOR>
void	perform (const TRANSACTOR &T, int Attempts=3)
	Perform the transaction defined by a transactor-based object.
PGSTD::auto_ptr< noticer >	set_noticer (PGSTD::auto_ptr< noticer > N) throw ()
	Set handler for postgresql errors or warning messages.
noticer *	get_noticer () const throw ()
void	process_notice (const char[]) throw ()
	Invoke notice processor function. The message should end in newline.
void	process_notice (const PGSTD::string &) throw ()
	Invoke notice processor function. Newline at end is recommended.
void	trace (FILE *) throw ()
	Enable tracing to a given output stream, or NULL to disable.
int	get_notifs ()
	Check for pending trigger notifications and take appropriate action.
const char *	dbname ()
	Name of database we're connected to, if any.
const char *	username ()
	Database user ID we're connected under, if any.
const char *	hostname ()
	Address of server (NULL for local connections).
const char *	port ()
	Server port number we're connected to.
const char *	options () const throw ()
	Full connection string as used to set up this connection.
int	backendpid () const throw ()
	Process ID for backend process.
void	activate ()
	Explicitly activate deferred or deactivated connection.
void	deactivate ()
	Explicitly deactivate connection.
void	set_client_encoding (const PGSTD::string &Encoding)
	Set client-side character encoding.
void	set_variable (const PGSTD::string &Var, const PGSTD::string &Value)
	Set session variable.
PGSTD::string	get_variable (const PGSTD::string &)
	Read session variable.
int	await_notification ()
	Wait for a trigger notification notification to come in.
int	await_notification (long seconds, long microseconds)
	Wait for a trigger notification to come in, or for given timeout to pass.
Protected Member Functions
virtual void	startconnect ()=0
	Overridable: initiate a connection.
virtual void	completeconnect ()=0
	Overridable: complete an initiated connection.
virtual void	dropconnect () throw ()
	Overridable: drop any specialized state related to connection attempt.
internal::pq::PGconn *	get_conn () const throw ()
	For implementation classes: do we have a connection structure?
void	set_conn (internal::pq::PGconn *C) throw ()
	For implementation classes: set connection structure pointer.
void	close () throw ()
void	wait_read () const
void	wait_read (long seconds, long microseconds) const
void	wait_write () const
Friends
class	transaction_base
class	largeobject
class	trigger
class	pipeline

---

Detailed Description

connection_base abstract base class; represents a connection to a database.

This is the first class to look at when you wish to work with a database through libpqxx. Depending on the implementing concrete child class, a connection can be automatically opened when it is constructed, or when it is first used. The connection is automatically closed upon destruction, if it hasn't already been closed manually.

To query or manipulate the database once connected, use one of the transaction classes (see pqxx/transaction_base.hxx) or preferably the transactor framework (see pqxx/transactor.hxx).

A word of caution: if a network connection to the database server fails, the connection will be restored automatically (although any transaction going on at the time will have to be aborted). This also means that any information set in previous transactions that is not stored in the database, such as connection-local variables defined with PostgreSQL's SET command, will be lost. Whenever you need to create such state, either do it within each transaction that may need it, or if at all possible, use specialized functions made available by libpqxx. Always avoid raw queries if libpqxx offers a dedicated function for the same purpose.

---

Constructor & Destructor Documentation

pqxx::connection_base::connection_base (  const PGSTD::string &  ConnInfo  )  [explicit]

Set up connection based on PostgreSQL connection string. Parameters: ConnInfo  a PostgreSQL connection string specifying any required parameters, such as server, port, database, and password. These values override any of the environment variables recognized by libpq that may have been defined for the same parameters. The README file for libpqxx gives a quick overview of how connection strings work; see the PostgreSQL documentation (particularly for libpq, the C-level interface) for a complete list.

pqxx::connection_base::connection_base (  const char  ConnInfo[]  )  [explicit]

Set up connection based on PostgreSQL connection string. Parameters: ConnInfo  a PostgreSQL connection string specifying any required parameters, such as server, port, database, and password. As a special case, a null pointer is taken as the empty string.

pqxx::connection_base::~connection_base (   )  [pure virtual]

Destructor. Implicitly closes the connection.

---

Member Function Documentation

void pqxx::connection_base::activate (   )

Explicitly activate deferred or deactivated connection. Use of this method is entirely optional. Whenever a connection is used while in a deferred or deactivated state, it will transparently try to bring itself into an activated state. This function is best viewed as an explicit hint to the connection that "if you're not in an active state, now would be a good time to get into one." Whether a connection is currently in an active state or not makes no real difference to its functionality. There is also no particular need to match calls to activate() with calls to deactivate(). A good time to call activate() might be just before you first open a transaction on a lazy connection.

int pqxx::connection_base::await_notification (  long  seconds, long  microseconds )

Wait for a trigger notification to come in, or for given timeout to pass. The wait may also be terminated by other events, such as the connection to the backend failing. Returns: The number of pending notifications upon return

int pqxx::connection_base::await_notification (   )

Wait for a trigger notification notification to come in. The wait may also be terminated by other events, such as the connection to the backend failing. The number of notifications received is returned.

int pqxx::connection_base::backendpid (   )  const throw ()

Process ID for backend process. Use with care: connections may be lost and automatically re-established without your knowledge, in which case this process ID may no longer be correct. You may, however, assume that this number remains constant and reliable within the span of a successful backend transaction. If the transaction fails, which may be due to a lost connection, then this number will have become invalid at some point within the transaction. Returns: Process identifier, or 0 if not currently connected.

void pqxx::connection_base::close (   )  throw () [protected]

virtual void pqxx::connection_base::completeconnect (   )  [protected, pure virtual]

Overridable: complete an initiated connection.

const char* pqxx::connection_base::dbname (   )

Name of database we're connected to, if any.

void pqxx::connection_base::deactivate (   )

Explicitly deactivate connection. Like its counterpart activate(), this method is entirely optional. Calling this function really only makes sense if you won't be using this connection for a while and want to reduce the number of open connections on the database server. There is no particular need to match or pair calls to deactivate() with calls to activate(), but calling deactivate() during a transaction is an error.

void pqxx::connection_base::disconnect (   )  throw ()

Explicitly close connection.

virtual void pqxx::connection_base::dropconnect (   )  throw () [protected, virtual]

Overridable: drop any specialized state related to connection attempt.

internal::pq::PGconn* pqxx::connection_base::get_conn (   )  const throw () [protected]

For implementation classes: do we have a connection structure?

noticer* pqxx::connection_base::get_noticer (   )  const throw ()

int pqxx::connection_base::get_notifs (   )

Check for pending trigger notifications and take appropriate action. Exceptions thrown by client-registered trigger handlers are reported, but not passed on outside this function. Returns: Number of pending notifications

string pqxx::connection_base::get_variable (  const PGSTD::string &   )

Read session variable. Will try to read the value locally, from the list of variables set with the set_variable function. If that fails, the database is queried. Warning: Do not mix the set_variable interface with manual setting of variables by executing the corresponding SQL commands, and do not get or set variables while a tablestream or pipeline is active on the same connection.

const char* pqxx::connection_base::hostname (   )

Address of server (NULL for local connections).

bool pqxx::connection_base::is_open (   )  const throw ()

Is this connection open at the moment? Warning: This function is not needed in most code. Resist the temptation to check it after opening a connection; rely on the exception that will be thrown on connection failure instead.

const char* pqxx::connection_base::options (   )  const throw ()

Full connection string as used to set up this connection.

template<typename TRANSACTOR> void pqxx::connection_base::perform (  const TRANSACTOR &  T, int  Attempts = 3 )

Perform the transaction defined by a transactor-based object. The function may create and execute several copies of the transactor before it succeeds. If there is any doubt over whether it succeeded (this can happen if the connection is lost just before the backend can confirm success), it is no longer retried and an error message is generated. Parameters: T  The transactor to be executed. Attempts  Maximum number of attempts to be made to execute T.

const char* pqxx::connection_base::port (   )

Server port number we're connected to.

void pqxx::connection_base::process_notice (  const PGSTD::string &   )  throw ()

Invoke notice processor function. Newline at end is recommended.

void pqxx::connection_base::process_notice (  const   char[]  )  throw ()

Invoke notice processor function. The message should end in newline.

void pqxx::connection_base::set_client_encoding (  const PGSTD::string &  Encoding  )

Set client-side character encoding. Search the PostgreSQL documentation for "multibyte" or "character set encodings" to find out more about the available encodings, how to extend them, and how to use them. Not all server-side encodings are compatible with all client-side encodings or vice versa. Parameters: Encoding  Name of the character set encoding to use

void pqxx::connection_base::set_conn (  internal::pq::PGconn *  C  )  throw () [protected]

For implementation classes: set connection structure pointer.

auto_ptr< pqxx::noticer > pqxx::connection_base::set_noticer (  PGSTD::auto_ptr< noticer >  N  )  throw ()

Set handler for postgresql errors or warning messages. The use of auto_ptr implies ownership, so unless the returned value is copied to another auto_ptr, it will be deleted directly after the call. This may be important when running under Windows, where a DLL cannot free memory allocated by the main program. The auto_ptr will delete the object from your code context, rather than from inside the library. If a noticer exists when the connection_base is destructed, it will also be deleted. Parameters: N  New message handler; must not be null or equal to the old one Returns: Previous handler

void pqxx::connection_base::set_variable (  const PGSTD::string &  Var, const PGSTD::string &  Value )

Set session variable. Set a session variable for this connection, using the SET command. If the connection to the database is lost and recovered, the last-set value will be restored automatically. See the PostgreSQL documentation for a list of variables that can be set and their permissible values. If a transaction is currently in progress, aborting that transaction will normally discard the newly set value. Known exceptions are nontransaction (which doesn't start a real backend transaction) and PostgreSQL versions prior to 7.3. Warning: Do not mix the set_variable interface with manual setting of variables by executing the corresponding SQL commands, and do not get or set variables while a tablestream or pipeline is active on the same connection. Parameters: Var  Variable to set Value  Value vor Var to assume: an identifier, a quoted string, or a number.

virtual void pqxx::connection_base::startconnect (   )  [protected, pure virtual]

Overridable: initiate a connection.

void pqxx::connection_base::trace (  FILE *   )  throw ()

Enable tracing to a given output stream, or NULL to disable.

const char* pqxx::connection_base::username (   )

Database user ID we're connected under, if any.

void pqxx::connection_base::wait_read (  long  seconds, long  microseconds )  const [protected]

void pqxx::connection_base::wait_read (   )  const [protected]

void pqxx::connection_base::wait_write (   )  const [protected]

---

Friends And Related Function Documentation

friend class largeobject [friend]

friend class pipeline [friend]

friend class transaction_base [friend]

friend class trigger [friend]

---

The documentation for this class was generated from the following files:

• connection_base.hxx
• transactor.hxx
• connection_base.cxx

---