PostgreSQL transaction. More...

#include <userver/storages/postgres/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

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.

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 174 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 201 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 187 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 325 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 334 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 344 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 354 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 265 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 282 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 272 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

Shortcut transaction options constants

Query execution

Detailed Description

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