userver: storages::postgres::Transaction Class Reference
Loading...
Searching...
No Matches
storages::postgres::Transaction Class Reference

#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
 
Transactionoperator= (Transaction &&) noexcept
 
 Transaction (const Transaction &)=delete
 
Transactionoperator= (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

◆ 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:

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: