storages::postgres::Transaction Class Reference

Table of Contents

• Detailed Description
• Shortcut transaction options constants
• Query execution
• Member Function Documentation
• Commit()
• Execute() [1/4]
• Execute() [2/4]
• Execute() [3/4]
• Execute() [4/4]
• ExecuteBulk() [1/2]
• ExecuteBulk() [2/2]
• ExecuteDecomposeBulk() [1/2]
• ExecuteDecomposeBulk() [2/2]
• MakePortal() [1/4]
• MakePortal() [2/4]
• MakePortal() [3/4]
• MakePortal() [4/4]
• Rollback()
• SetParameter()
• Member Data Documentation
• Deferrable
• kDefaultRowsInChunk
• RO
• RW

#include <userver/storages/postgres/transaction.hpp>

Detailed Description

PostgreSQL transaction.

RAII wrapper for running transactions on PostgreSQL connections. Should be retrieved by calling storages::postgres::Cluster::Begin().

Non-copyable.

If the transaction is not explicitly finished (either committed or rolled back) it will roll itself back in the destructor.

Usage synopsis

auto trx = someCluster.Begin(/* transaction options */);
auto res = trx.Execute("select col1, col2 from schema.table");
DoSomething(res);
res = trx.Execute("update schema.table set col1 = $1 where col2 = $2", v1, v2);
// If in the above lines an exception is thrown, then the transaction is
// rolled back in the destructor of trx.
trx.Commit();

Examples

samples/postgres_service/postgres_service.cpp.

Definition at line 136 of file transaction.hpp.

Collaboration diagram for storages::postgres::Transaction:

Shortcut transaction options constants
static constexpr TransactionOptions	RW {}
	Read-write read committed transaction.
static constexpr TransactionOptions	RO {TransactionOptions::kReadOnly}
	Read-only read committed transaction.
static constexpr TransactionOptions	Deferrable
	Read-only serializable deferrable transaction.
static constexpr std::size_t	kDefaultRowsInChunk = 1024
	Transaction (Transaction &&) noexcept
Transaction &	operator= (Transaction &&) noexcept
	Transaction (const Transaction &)=delete
Transaction &	operator= (const Transaction &)=delete

Query execution
Execute statement with arbitrary parameters. Suspends coroutine for execution. std::size_t InsertInTransaction(storages::postgres::Transaction& transaction, std::string_view key) { auto res = transaction.Execute("INSERT INTO keys VALUES ($1)", key); return res.RowsAffected(); }
template<typename... Args>
ResultSet	Execute (const Query &query, const Args &... args)
template<typename... Args>
ResultSet	Execute (OptionalCommandControl statement_cmd_ctl, const Query &query, const Args &... args)
ResultSet	Execute (const Query &query, const ParameterStore &store)
ResultSet	Execute (OptionalCommandControl statement_cmd_ctl, const Query &query, const ParameterStore &store)
template<typename Container >
void	ExecuteBulk (const Query &query, const Container &args, std::size_t chunk_rows=kDefaultRowsInChunk)
template<typename Container >
void	ExecuteBulk (OptionalCommandControl statement_cmd_ctl, const Query &query, const Container &args, std::size_t chunk_rows=kDefaultRowsInChunk)
template<typename Container >
void	ExecuteDecomposeBulk (const Query &query, const Container &args, std::size_t chunk_rows=kDefaultRowsInChunk)
template<typename Container >
void	ExecuteDecomposeBulk (OptionalCommandControl statement_cmd_ctl, const Query &query, const Container &args, std::size_t chunk_rows=kDefaultRowsInChunk)
template<typename... Args>
Portal	MakePortal (const Query &query, const Args &... args)
template<typename... Args>
Portal	MakePortal (OptionalCommandControl statement_cmd_ctl, const Query &query, const Args &... args)
Portal	MakePortal (const Query &query, const ParameterStore &store)
Portal	MakePortal (OptionalCommandControl statement_cmd_ctl, const Query &query, const ParameterStore &store)
void	SetParameter (const std::string &param_name, const std::string &value)
void	Commit ()
void	Rollback ()
OptionalCommandControl	GetConnTransactionCommandControlDebug () const
	Used in tests.
TimeoutDuration	GetConnStatementTimeoutDebug () const

Member Function Documentation

Commit()

void storages::postgres::Transaction::Commit

(

)

Commit the transaction Suspends coroutine until command complete. After Commit or Rollback is called, the transaction is not usable any more.

Examples

samples/postgres_service/postgres_service.cpp.

Execute() [1/4]

template<typename... Args>

ResultSet storages::postgres::Transaction::Execute ( const Query & query, const Args &... args )

inline

Examples

samples/postgres_service/postgres_service.cpp.

Definition at line 176 of file transaction.hpp.

Execute() [2/4]

ResultSet storages::postgres::Transaction::Execute ( const Query & query, const ParameterStore & store )

inline

Execute statement with stored parameters.

Suspends coroutine for execution.

Warning

Do NOT create a query string manually by embedding arguments! It leads to vulnerabilities and bad performance. Either pass arguments separately, or use storages::postgres::ParameterScope.

Definition at line 203 of file transaction.hpp.

Execute() [3/4]

template<typename... Args>

ResultSet storages::postgres::Transaction::Execute ( OptionalCommandControl statement_cmd_ctl, const Query & query, const Args &... args )

inline

Execute statement with arbitrary parameters and per-statement command control.

Suspends coroutine for execution.

Warning

Do NOT create a query string manually by embedding arguments! It leads to vulnerabilities and bad performance. Either pass arguments separately, or use storages::postgres::ParameterScope.

Definition at line 189 of file transaction.hpp.

Execute() [4/4]

ResultSet storages::postgres::Transaction::Execute	(	OptionalCommandControl	statement_cmd_ctl,
		const Query &	query,
		const ParameterStore &	store )

Execute statement with stored parameters and per-statement command control.

Suspends coroutine for execution.

ExecuteBulk() [1/2]

template<typename Container >

void storages::postgres::Transaction::ExecuteBulk	(	const Query &	query,
		const Container &	args,
		std::size_t	chunk_rows = kDefaultRowsInChunk )

Execute statement that uses an array of arguments splitting that array in chunks and executing the statement with a chunk of arguments.

Useful for statements that unnest their arguments to avoid the need to increase timeouts due to data amount growth.

Definition at line 328 of file transaction.hpp.

ExecuteBulk() [2/2]

template<typename Container >

void storages::postgres::Transaction::ExecuteBulk	(	OptionalCommandControl	statement_cmd_ctl,
		const Query &	query,
		const Container &	args,
		std::size_t	chunk_rows = kDefaultRowsInChunk )

Execute statement that uses an array of arguments splitting that array in chunks and executing the statement with a chunk of arguments.

Useful for statements that unnest their arguments to avoid the need to increase timeouts due to data amount growth.

Definition at line 337 of file transaction.hpp.

ExecuteDecomposeBulk() [1/2]

template<typename Container >

void storages::postgres::Transaction::ExecuteDecomposeBulk	(	const Query &	query,
		const Container &	args,
		std::size_t	chunk_rows = kDefaultRowsInChunk )

Execute statement that uses an array of arguments transforming that array into N arrays of corresponding fields and executing the statement with a chunk of each of these arrays values. Basically, a column-wise ExecuteBulk.

Useful for statements that unnest their arguments to avoid the need to increase timeouts due to data amount growth, but providing an explicit mapping from Container::value_type to PG type is infeasible for some reason (otherwise, use ExecuteBulk).

struct IdAndValue final {
  int id{};
  std::string value;
};
 
void InsertDecomposedInChunks(pg::Transaction& trx,
                              const std::vector<IdAndValue>& rows) {
  trx.ExecuteDecomposeBulk(
      "INSERT INTO decomposed_chunked_array_test(id, value) "
      "VALUES(UNNEST($1), UNNEST($2))",
      rows);
}

Definition at line 347 of file transaction.hpp.

ExecuteDecomposeBulk() [2/2]

template<typename Container >

void storages::postgres::Transaction::ExecuteDecomposeBulk	(	OptionalCommandControl	statement_cmd_ctl,
		const Query &	query,
		const Container &	args,
		std::size_t	chunk_rows = kDefaultRowsInChunk )

Execute statement that uses an array of arguments transforming that array into N arrays of corresponding fields and executing the statement with a chunk of each of these arrays values. Basically, a column-wise ExecuteBulk.

Useful for statements that unnest their arguments to avoid the need to increase timeouts due to data amount growth, but providing an explicit mapping from Container::value_type to PG type is infeasible for some reason (otherwise, use ExecuteBulk).

struct IdAndValue final {
  int id{};
  std::string value;
};
 
void InsertDecomposedInChunks(pg::Transaction& trx,
                              const std::vector<IdAndValue>& rows) {
  trx.ExecuteDecomposeBulk(
      "INSERT INTO decomposed_chunked_array_test(id, value) "
      "VALUES(UNNEST($1), UNNEST($2))",
      rows);
}

Definition at line 357 of file transaction.hpp.

MakePortal() [1/4]

template<typename... Args>

Portal storages::postgres::Transaction::MakePortal ( const Query & query, const Args &... args )

inline

Create a portal for fetching results of a statement with arbitrary parameters.

Definition at line 267 of file transaction.hpp.

MakePortal() [2/4]

Portal storages::postgres::Transaction::MakePortal ( const Query & query, const ParameterStore & store )

inline

Create a portal for fetching results of a statement with stored parameters.

Definition at line 284 of file transaction.hpp.

MakePortal() [3/4]

template<typename... Args>

Portal storages::postgres::Transaction::MakePortal ( OptionalCommandControl statement_cmd_ctl, const Query & query, const Args &... args )

inline

Create a portal for fetching results of a statement with arbitrary parameters and per-statement command control.

Definition at line 274 of file transaction.hpp.

MakePortal() [4/4]

Portal storages::postgres::Transaction::MakePortal	(	OptionalCommandControl	statement_cmd_ctl,
		const Query &	query,
		const ParameterStore &	store )

Create a portal for fetching results of a statement with stored parameters and per-statement command control.

Rollback()

void storages::postgres::Transaction::Rollback

(

)

Rollback the transaction Suspends coroutine until command complete. After Commit or Rollback is called, the transaction is not usable any more.

Examples

samples/postgres_service/postgres_service.cpp.

SetParameter()

void storages::postgres::Transaction::SetParameter	(	const std::string &	param_name,
		const std::string &	value )

Set a connection parameter https://www.postgresql.org/docs/current/sql-set.html The parameter is set for this transaction only

Member Data Documentation

Deferrable

constexpr TransactionOptions storages::postgres::Transaction::Deferrable

staticconstexpr

Initial value:

{
      TransactionOptions::Deferrable()}

Read-only serializable deferrable transaction.

Definition at line 145 of file transaction.hpp.

kDefaultRowsInChunk

constexpr std::size_t storages::postgres::Transaction::kDefaultRowsInChunk = 1024

staticconstexpr

Definition at line 149 of file transaction.hpp.

RO

constexpr TransactionOptions storages::postgres::Transaction::RO {TransactionOptions::kReadOnly}

staticconstexpr

Read-only read committed transaction.

Definition at line 143 of file transaction.hpp.

RW

constexpr TransactionOptions storages::postgres::Transaction::RW {}

staticconstexpr

Read-write read committed transaction.

Definition at line 141 of file transaction.hpp.

---

The documentation for this class was generated from the following file:

• userver/storages/postgres/transaction.hpp