#include <connection_base.hxx>
Inheritance diagram for pqxx::connection_base:
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< 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. | |
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.
| |
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 ¶ms) |
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::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 |
class | cursor_base |
Classes | |
struct | prepared_def |
Internal state: definition of a prepared statement. |
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.
|
|
Set up connection based on PostgreSQL connection string.
|
|
Set up connection based on PostgreSQL connection string.
|
|
Destructor. Implicitly closes the connection.
|
|
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. |
|
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.
|
|
|
|
Overridable: complete an initiated connection.
|
|
Name of database we're connected to, if any.
|
|
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. |
|
Explicitly close connection.
|
|
Overridable: drop any specialized state related to connection attempt.
|
|
For implementation classes: do we have a connection structure?
|
|
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.
|
|
Address of server (NULL for local connections).
|
|
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.
|
|
Is this connection open at the moment?
|
|
Full connection string as used to set up this connection.
|
|
Server port number we're connected to.
|
|
Define prepared statement with given parameter list.
|
|
Define prepared statement with given parameter list.
|
|
Define prepared statement that takes no parameters.
|
|
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.
|
|
For implementation classes: set connection structure pointer.
|
|
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.
|
|
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.
|
|
Overridable: initiate a connection.
|
|
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. |
|
Enable tracing to a given output stream, or NULL to disable.
|
|
Drop prepared statement.
|
|
Database user ID we're connected under, if any.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|