Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

pqxx::connection_base Class Reference
[Connection classes]

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

#include <connection_base.hxx>

Inheritance diagram for pqxx::connection_base:

Inheritance graph
[legend]
Collaboration diagram for pqxx::connection_base:

Collaboration graph
[legend]
List of all members.

Connection properties

These are probably not needed very often: since most are derived from information supplied by the client program itself, but are included for completeness.

enum  capability {
  cap_create_table_with_oids, cap_cursor_scroll, cap_cursor_with_hold, cap_cursor_update,
  cap_end
}
 Session capabilities. More...
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.
int sock () const throw ()
 Socket currently used for connection, or -1 for none. Use with care!
bool supports (capability c) const throw ()
 Does this connection seem to support the given capability?
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.

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.
PGSTD::auto_ptr< noticerset_noticer (PGSTD::auto_ptr< noticer > N) throw ()
 Set handler for postgresql errors or warning messages.
noticerget_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.
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.
template<typename TRANSACTOR>
void perform (const TRANSACTOR &T, int Attempts)
 Perform the transaction defined by a transactor-based object.
template<typename TRANSACTOR>
void perform (const TRANSACTOR &T)
 Perform the transaction defined by a transactor-based object.
Connection state
void disconnect () throw ()
 Explicitly close connection.
void activate ()
 Explicitly activate deferred or deactivated connection.
void deactivate ()
 Explicitly deactivate connection.
void inhibit_reactivation (bool inhibit)
 Disallow (or permit) connection recovery.
bool is_open () const throw ()
 Is this connection open at the moment?
Prepared statements
PostgreSQL supports prepared SQL statements, i.e. statements that can be registered under a client-provided name, optimized once by the backend, and executed any number of times under the given name.

Prepared statements are not held to transaction boundaries; a statement defined inside a transaction will remain defined outside that transaction, even if the transaction is subsequently aborted. Once a statement has been prepared, only closing the connection or explicitly "unpreparing" it can make it go away.

Use the transaction classes' exec_prepared() functions to execute a prepared statement.

Warning:
Prepared statements are not necessarily defined on the backend right away; they may be cached by libpqxx. This means that statements may be prepared before the connection is fully established, and that it's relatively cheap to pre-prepare lots of statements that may or may not be used during the session. It also means, however, that errors in the prepared statement may not show up until it is first used. Such failure may cause the current transaction to roll back.

Never try to prepare, execute, or unprepare a prepared statement manually using direct SQL queries. Always use the functions provided by libpqxx.



void prepare (const PGSTD::string &name, const PGSTD::string &def)
 Define prepared statement that takes no parameters.
template<typename ITER>
void prepare (const PGSTD::string &name, const PGSTD::string &def, ITER beginparms, ITER endparms)
 Define prepared statement with given parameter list.
template<typename CNTNR>
void prepare (const PGSTD::string &name, const PGSTD::string &def, const CNTNR &params)
 Define prepared statement with given parameter list.
void unprepare (const PGSTD::string &name)
 Drop prepared statement.

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::PGconnget_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
class cursor_base

Classes

struct  prepared_def
 Internal state: definition of a prepared statement.

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.


Member Enumeration Documentation

enum pqxx::connection_base::capability
 

Session capabilities.

Some functionality is only available in certain versions of the backend, or only when speaking certain versions of the communications protocol that connects us to the backend. This includes clauses for SQL statements that were not accepted in older database versions, but are required in newer versions to get the same behaviour.

Enumeration values:
cap_create_table_with_oids  Can we specify WITH OIDS with CREATE TABLE? If we can, we should.
cap_cursor_scroll  Can cursors be declared SCROLL?
cap_cursor_with_hold  Can cursors be declared WITH HOLD?
cap_cursor_update  Can cursors be updateable?
cap_end  Not a capability value; end-of-enumeration marker.


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::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?

PGSTD::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).

void pqxx::connection_base::inhibit_reactivation bool  inhibit  ) 
 

Disallow (or permit) connection recovery.

A connection whose underlying socket is not currently connected to the server will normally (re-)establish communication with the server whenever needed, or when the client program requests it (although for reasons of integrity, never inside a transaction; but retrying the whole transaction may implicitly cause the connection to be restored). In normal use this is quite a convenient thing to have and presents a simple, safe, predictable interface.

There is at least one situation where this feature is not desirable, however. Although most session state (prepared statements, session variables) is automatically restored to its working state upon connection reactivation, temporary tables and so-called WITH HOLD cursors (which can live outside transactions) are not.

Cursors that live outside transactions are automatically handled, and the library will quietly ignore requests to deactivate or reactivate connections while they exist; it does not want to give you the illusion of being back in your transaction when in reality you just dropped a cursor. With temporary tables this is not so easy: there is no easy way for the library to detect their creation or track their lifetimes.

So if your program uses temporary tables, and any part of this use happens outside of any database transaction (or spans multiple transactions), some of the work you have done on these tables may unexpectedly be undone if the connection is broken or deactivated while any of these tables exists, and then reactivated or implicitly restored before you are finished with it.

If this describes any part of your program, guard it against unexpected reconnections by inhibiting reconnection at the beginning. And if you want to continue doing work on the connection afterwards that no longer requires the temp tables, you can permit it again to get the benefits of connection reactivation for the remainder of the program.

Parameters:
inhibit should reactivation be inhibited from here on?
Warning:
Some connection types (the lazy and asynchronous types) defer completion of the socket-level connection until it is actually needed by the client program. Inhibiting reactivation before this connection is really established will prevent these connection types from doing their work. For those connection types, if you are sure that reactivation needs to be inhibited before any query goes across the connection, activate() the connection first. This will ensure that definite activation happens before you inhibit it.

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.

const char* pqxx::connection_base::port  ) 
 

Server port number we're connected to.

template<typename CNTNR>
void pqxx::connection_base::prepare const PGSTD::string &  name,
const PGSTD::string &  def,
const CNTNR &  params
 

Define prepared statement with given parameter list.

template<typename ITER>
void pqxx::connection_base::prepare const PGSTD::string &  name,
const PGSTD::string &  def,
ITER  beginparms,
ITER  endparms
 

Define prepared statement with given parameter list.

void pqxx::connection_base::prepare const PGSTD::string &  name,
const PGSTD::string &  def
 

Define prepared statement that takes no parameters.

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.

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.

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

Socket currently used for connection, or -1 for none. Use with care!

Query the current socket number. This is intended for event loops based on functions such as select() or poll(), where multiple file descriptors are watched.

Please try to stay away from this function. It is really only meant for event loops that need to wait on more than one file descriptor. If all you need is to block until a trigger notification arrives, for instance, use await_notification(). If you want to issue queries and retrieve results in nonblocking fashion, check out the pipeline class.

Warning:
Don't store this value anywhere, and always be prepared for the possibility that there is no socket. The socket may change or even go away during any invocation of libpqxx code, no matter how trivial.

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

Overridable: initiate a connection.

bool pqxx::connection_base::supports capability  c  )  const throw ()
 

Does this connection seem to support the given capability?

Don't try to be smart by caching this information anywhere. Obtaining it is quite fast (especially after the first time) and what's more, a capability may "suddenly" appear or disappear if the connection is broken or deactivated, and then restored. This may happen silently any time no backend transaction is active; if it turns out that the server was upgraded or restored from an older backup, or the new connection goes to a different backend, then the restored session may have different capabilities than were available previously.

Some guesswork is involved in establishing the presence of any capability; try not to rely on this function being exactly right. Older versions of libpq may not detect any capabilities.

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

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

void pqxx::connection_base::unprepare const PGSTD::string &  name  ) 
 

Drop prepared statement.

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 cursor_base [friend]
 

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 file:
Generated on Mon Oct 3 20:29:04 2005 for libpqxx by  doxygen 1.4.2