Transaction classes

Abstract base class responsible for bracketing a backend transaction. More...

Classes
class	pqxx::basic_robusttransaction
class	pqxx::basic_transaction
class	pqxx::robusttransaction< ISOLATIONLEVEL >
	Slightly slower, better-fortified version of transaction. More...
class	pqxx::transaction< ISOLATIONLEVEL, READWRITE >
	Standard back-end transaction, templatized on isolation level. More...

Typedefs
typedef transaction < read_committed, read_only >	pqxx::read_transaction
	Read-only transaction. More...
typedef transaction	pqxx::work
	Bog-standard, default transaction type. More...

Detailed Description

Abstract base class responsible for bracketing a backend transaction.

Interface definition (and common code) for "transaction" classes.

Simple "transaction" class offering no transactional integrity.

Use a dbtransaction-derived object such as "work" (transaction<>) to enclose operations on a database in a single "unit of work." This ensures that the whole series of operations either succeeds as a whole or fails completely. In no case will it leave half-finished work behind in the database.

Once processing on a transaction has succeeded and any changes should be allowed to become permanent in the database, call commit(). If something has gone wrong and the changes should be forgotten, call abort() instead. If you do neither, an implicit abort() is executed at destruction time.

It is an error to abort a transaction that has already been committed, or to commit a transaction that has already been aborted. Aborting an already aborted transaction or committing an already committed one has been allowed to make errors easier to deal with. Repeated aborts or commits have no effect after the first one.

Database transactions are not suitable for guarding long-running processes. If your transaction code becomes too long or too complex, please consider ways to break it up into smaller ones. There's no easy, general way to do this since application-specific considerations become important at this point.

The actual operations for beginning and committing/aborting the backend transaction are implemented by a derived class. The implementing concrete class must also call Begin() and End() from its constructors and destructors, respectively, and implement do_exec().

Warning

Read-only transactions require backend version 8.0 or better. On older backends, these transactions will be able to modify the database. Even if you have a newer server version, it is not wise to rely on read-only transactions alone to enforce a security model.

nontransaction, like transaction or any other transaction_base-derived class, provides access to a database through a connection. Unlike its siblings, however, nontransaction does not maintain any kind of transactional integrity. This may be useful eg. for read-only access to the database that does not require a consistent, atomic view on its data; or for operations that are not allowed within a backend transaction, such as creating tables.

For queries that update the database, however, a real transaction is likely to be faster unless the transaction consists of only a single record update.

Also, you can keep a nontransaction open for as long as you like. Actual back-end transactions are limited in lifespan, and will sometimes fail just because they took too long to execute or were left idle for too long. This will not happen with a nontransaction (although the connection may still time out, e.g. when the network is unavailable for a very long time).

Any query executed in a nontransaction is committed immediately, and neither commit() nor abort() has any effect.

Database features that require a backend transaction, such as cursors or large objects, will not work in a nontransaction.

All database access must be channeled through one of these classes for safety, although not all implementations of this interface need to provide full transactional integrity.

Several implementations of this interface are shipped with libpqxx, including the plain transaction class, the entirely unprotected nontransaction, and the more cautions robusttransaction.

Typedef Documentation

typedef transaction<read_committed, read_only> pqxx::read_transaction

Read-only transaction.

typedef transaction pqxx::work

Bog-standard, default transaction type.