|
| PGSTD::string | adorn_name (const PGSTD::string &) |
| | Used internally to generate identifiers for SQL objects (such as cursors and nested transactions) based on a given human-readable base name. More...
|
| |
| void | cancel_query () |
| | Attempt to cancel the ongoing query, if any. More...
|
| |
| void | disconnect () throw () |
| | Explicitly close connection. More...
|
| |
| PGSTD::string | esc (const char str[]) |
| | Escape string for use as SQL string literal on this connection. More...
|
| |
| PGSTD::string | esc (const char str[], size_t maxlen) |
| | Escape string for use as SQL string literal on this connection. More...
|
| |
| PGSTD::string | esc (const PGSTD::string &str) |
| | Escape string for use as SQL string literal on this connection. More...
|
| |
| PGSTD::string | esc_raw (const unsigned char str[], size_t len) |
| | Escape binary string for use as SQL string literal on this connection. More...
|
| |
| PGSTD::vector< errorhandler * > | get_errorhandlers () const |
| | Return pointers to the active errorhandlers. More...
|
| |
| PGSTD::string | get_variable (const PGSTD::string &) |
| | Read session variable. More...
|
| |
| error_verbosity | get_verbosity () const throw () |
| | Retrieve current error verbosity. More...
|
| |
| bool PQXX_PURE | is_open () const throw () |
| | Is this connection open at the moment? More...
|
| |
| void | process_notice (const char[]) throw () |
| | Invoke notice processor function. The message should end in newline. More...
|
| |
| void | process_notice (const PGSTD::string &) throw () |
| | Invoke notice processor function. Newline at end is recommended. More...
|
| |
| template<typename T > |
| PGSTD::string | quote (const T &t) |
| | Represent object as SQL string, including quoting & escaping. More...
|
| |
| PGSTD::string | quote (const binarystring &) |
| |
| PGSTD::string | quote_name (const PGSTD::string &identifier) |
| | Escape and quote an SQL identifier for use in a query. More...
|
| |
| PGSTD::string | quote_raw (const unsigned char str[], size_t len) |
| | Escape and quote a string of binary data. More...
|
| |
| void | set_client_encoding (const PGSTD::string &Encoding) |
| | Set client-side character encoding. More...
|
| |
| void | set_variable (const PGSTD::string &Var, const PGSTD::string &Value) |
| | Set session variable. More...
|
| |
| void | set_verbosity (error_verbosity verbosity) throw () |
| | Set session verbosity. More...
|
| |
| void | trace (PGSTD::FILE *) throw () |
| | Enable tracing to a given output stream, or NULL to disable. More...
|
| |
|
Connections can be temporarily deactivated, or they can break because of overly impatient firewalls dropping TCP connections.
Where possible, libpqxx will try to re-activate these when resume using them, or you can wake them up explicitly. You probably won't need this feature, but you should be aware of it.
|
| void | activate () |
| | Explicitly activate deferred or deactivated connection. More...
|
| |
| void | deactivate () |
| | Explicitly deactivate connection. More...
|
| |
| void | inhibit_reactivation (bool inhibit) |
| | Disallow (or permit) connection recovery. More...
|
| |
| void | simulate_failure () |
| | Make the connection fail. More...
|
| |
|
These are probably not of great interest, since most are derived from information supplied by the client program itself, but they are included for completeness.
|
| const char * | dbname () |
| | Name of database we're connected to, if any. More...
|
| |
| const char * | username () |
| | Database user ID we're connected under, if any. More...
|
| |
| const char * | hostname () |
| | Address of server, or NULL if none specified (i.e. default or local) More...
|
| |
| const char * | port () |
| | Server port number we're connected to. More...
|
| |
| int PQXX_PURE | backendpid () const throw () |
| | Process ID for backend process. More...
|
| |
| int PQXX_PURE | sock () const throw () |
| | Socket currently used for connection, or -1 for none. Use with care! More...
|
| |
|
| int | get_notifs () |
| | Check for pending notifications and take appropriate action. More...
|
| |
| int | await_notification () |
| | Wait for a notification to come in. More...
|
| |
| int | await_notification (long seconds, long microseconds) |
| | Wait for a notification to come in, or for given timeout to pass. More...
|
| |
|
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 statement definitions are not sensitive to transaction boundaries; a statement defined inside a transaction will remain defined outside that transaction, even if the transaction itself 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' prepared().exec() function to execute a prepared statement. Use prepared().exists() to find out whether a statement has been prepared under a given name.
A special case is the nameless prepared statement. You may prepare a statement without a name. The unnamed statement can be redefined at any time, without un-preparing it first.
- Warning
- Prepared statements are not necessarily defined on the backend right away; libpqxx generally does that lazily. This means that you can prepare statements before the connection is fully established, and that it's relatively cheap to pre-prepare lots of statements that you may or may not use during the session. On the other hand, it also means that errors in a prepared statement may not show up until you first try to invoke it. Such an error may then break the transaction it occurs in.
-
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 &definition) |
| | Define a prepared statement. More...
|
| |
| void | prepare (const PGSTD::string &definition) |
| | Define a nameless prepared statement. More...
|
| |
| void | unprepare (const PGSTD::string &name) |
| | Drop prepared statement. More...
|
| |
| void | prepare_now (const PGSTD::string &name) |
| | Request that prepared statement be registered with the server. More...
|
| |
|
See the transactor class template for more about transactors.
To use the transactor framework, encapsulate your transaction code in a class derived from an instantiation of the pqxx::transactor template. Then, to execute it, create an object of your transactor class and pass it to one of the perform() functions here.
The perform() functions may create and execute several copies of the transactor before succeeding or ultimately giving up. If there is any doubt over whether execution succeeded (this can happen if the connection to the server is lost just before the backend can confirm success), it is no longer retried and an in_doubt_error is thrown.
Take care: no member functions will ever be invoked on the transactor object you pass into perform(). The object you pass in only serves as a "prototype" for the job to be done. The perform() function will copy-construct transactors from the original you passed in, executing the copies only. The original object remains "clean" in its original state.
|
| template<typename TRANSACTOR > |
| void | perform (const TRANSACTOR &T, int Attempts) |
| | Perform the transaction defined by a transactor-based object. More...
|
| |
| template<typename TRANSACTOR > |
| void | perform (const TRANSACTOR &T) |
| | Perform the transaction defined by a transactor-based object. More...
|
| |
|
| | connection_base (const connection_base &) |
| |
| void | add_reactivation_avoidance_count (int) |
| |
| void | add_receiver (notification_receiver *) |
| |
| void PQXX_PRIVATE | AddVariables (const PGSTD::map< PGSTD::string, PGSTD::string > &) |
| |
| void PQXX_PRIVATE | check_result (const result &) |
| |
| void PQXX_PRIVATE | clearcaps () throw () |
| |
| bool PQXX_PRIVATE | consume_input () throw () |
| |
| int PQXX_PRIVATE | encoding_code () |
| |
| void PQXX_PRIVATE | EndCopyWrite () |
| |
| const char *PQXX_PURE | ErrMsg () const throw () |
| |
| result PQXX_PRIVATE | Exec (const char[], int Retries) |
| |
| prepare::internal::prepared_def & | find_prepared (const PGSTD::string &) |
| |
| internal::pq::PGresult * | get_result () |
| |
| void PQXX_PRIVATE | InternalSetTrace () throw () |
| |
| bool PQXX_PRIVATE | is_busy () const throw () |
| |
| result | make_result (internal::pq::PGresult *rhs, const PGSTD::string &query) |
| |
| connection_base & | operator= (const connection_base &) |
| |
| result | parameterized_exec (const PGSTD::string &query, const char *const params[], const int paramlengths[], const int binaries[], int nparams) |
| |
| result | prepared_exec (const PGSTD::string &, const char *const [], const int[], const int[], int) |
| |
| bool | prepared_exists (const PGSTD::string &) const |
| |
| void PQXX_PRIVATE | process_notice_raw (const char msg[]) throw () |
| |
| internal::pq::PGconn * | RawConnection () const |
| |
| PGSTD::string PQXX_PRIVATE | RawGetVar (const PGSTD::string &) |
| |
| void PQXX_PRIVATE | RawSetVar (const PGSTD::string &, const PGSTD::string &) |
| |
| void | read_capabilities () throw () |
| |
| bool PQXX_PRIVATE | ReadCopyLine (PGSTD::string &) |
| |
| void PQXX_PRIVATE | register_errorhandler (errorhandler *) |
| |
| prepare::internal::prepared_def & | register_prepared (const PGSTD::string &) |
| |
| void PQXX_PRIVATE | RegisterTransaction (transaction_base *) |
| |
| void | remove_receiver (notification_receiver *) throw () |
| |
| void PQXX_PRIVATE | Reset () |
| |
| void PQXX_PRIVATE | RestoreVars () |
| |
| void PQXX_PRIVATE | SetupState () |
| |
| void PQXX_PRIVATE | start_exec (const PGSTD::string &) |
| |
| int PQXX_PRIVATE PQXX_PURE | Status () const throw () |
| |
| void PQXX_PRIVATE | unregister_errorhandler (errorhandler *) throw () |
| |
| void PQXX_PRIVATE | UnregisterTransaction (transaction_base *) throw () |
| |
| void PQXX_PRIVATE | WriteCopyLine (const PGSTD::string &) |
| |
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, or somewhere inbetween. The connection is automatically closed upon destruction (if it hasn't been closed already).
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).
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 temp tables or connection-local variables defined with PostgreSQL's SET command, will be lost. Whenever you create such state, either keept it local to one transaction, where possible, or inhibit automatic reactivation of the connection using the inhibit_reactivation() method.
When a connection breaks, you will typically get a broken_connection exception. This can happen at almost any point, and the details may depend on which connection class (all derived from this one) you use.
As a general rule, always avoid raw queries if libpqxx offers a dedicated function for the same purpose. There may be hidden logic to hide certain complications from you, such as reinstating session variables when a broken or disabled connection is reactivated.
- Warning
- On Unix-like systems, including GNU and BSD systems, your program may receive the SIGPIPE signal when the connection to the backend breaks. By default this signal will abort your program. Use "signal(SIGPIPE, SIG_IGN)" if you want your program to continue running after a connection fails.
| void pqxx::connection_base::inhibit_reactivation |
( |
bool |
inhibit | ) |
|
|
inline |
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.
1.8.3.1 
