libpqxx  v4.0-1
C++ library for PostgreSQL
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
Connection classes

The connection classes are where the use of a database begins. More...

Classes

class  pqxx::connect_async
 Asynchronous connection policy; connects "in the background". More...
 
class  pqxx::connect_direct
 Connection policy; creates an immediate connection to a database. More...
 
class  pqxx::connect_lazy
 Lazy connection policy; causes connection to be deferred until first use. More...
 
class  pqxx::connect_null
 Nonfunctional, always-down connection policy for testing/debugging purposes. More...
 
class  pqxx::connectionpolicy
 

Typedefs

typedef basic_connection
< connect_async > 
pqxx::asyncconnection
 "Asynchronous" connection type: start connecting, but don't wait for it More...
 
typedef basic_connection
< connect_direct > 
pqxx::connection
 The "standard" connection type: connect to database right now. More...
 
typedef basic_connection
< connect_lazy > 
pqxx::lazyconnection
 A "lazy" connection type: connect to database only when needed. More...
 
typedef basic_connection
< connect_null > 
pqxx::nullconnection
 A "dummy" connection type: don't connect to any database at all. More...
 

Detailed Description

The connection classes are where the use of a database begins.

You must connect to a database in order to access it. Your connection represents a session with the database. In the context of that connection you can create transactions, which in turn you can use to execute SQL. A connection can have only one regular transaction open at a time, but you can break your work down into any number of consecutive transactions and there is also some support for transaction nesting (using the subtransaction class).

Many things come together in the connection classes. Handling of error and warning messages, for example, is defined by errorhandlers in the context of a connection. Prepared statements are also defined here.

Several types of connections are available, including plain connection and lazyconnection. These types are typedefs combining a derivative of the connection_base class (where essentially all connection-related functionality is defined) with a policy class which governs how the connection is to be established. You pass details such as the database you wish to connect to, username and password, and so on as as PostgreSQL "connection string" and certain environment variables that you can learn more about from the core postgres documentation.

See the connection_base documentation for a full list of features inherited by all connection classes. Connections can be deactivated and reactivated if needed (within reason, of course–you can't do this in the middle of a transaction), and where possible, disabled or broken connections are transparently re-enabled when you use them again. This is called "reactivation," and you may need to understand it because you'll want it disabled in certain situations.

You can also set certain variables defined by the backend to influence its behaviour for the duration of your session, such as the applicable text encoding. You can query the connection's capabilities (because some features will depend on the versions of libpq and of the server backend that you're using) and parameters that you set in your connection string and/or environment variables.

Typedef Documentation

typedef basic_connection<connect_async> pqxx::asyncconnection

"Asynchronous" connection type: start connecting, but don't wait for it

typedef basic_connection<connect_direct> pqxx::connection

The "standard" connection type: connect to database right now.

typedef basic_connection<connect_lazy> pqxx::lazyconnection

A "lazy" connection type: connect to database only when needed.

typedef basic_connection<connect_null> pqxx::nullconnection

A "dummy" connection type: don't connect to any database at all.