#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/main.cpp.

Definition at line 144 of file transaction.hpp.

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 {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. Note You may write a query in `.sql` file and generate a header file with Query from it. See External SQL/YQL files for more information. 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)
	Create a portal for fetching results of a statement with arbitrary parameters.

template<typename... Args>
Portal	MakePortal (OptionalCommandControl statement_cmd_ctl, const Query &query, const Args &... args)
	Create a portal for fetching results of a statement with arbitrary parameters and per-statement command control.

Portal	MakePortal (const Query &query, const ParameterStore &store)
	Create a portal for fetching results of a statement with stored parameters.

Portal	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.

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/main.cpp.

◆ Execute() [1/4]

template<typename... Args>

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

inline

Examples: samples/postgres_service/main.cpp.

Definition at line 187 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

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 219 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

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() [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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

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.

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

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

Definition at line 378 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

Definition at line 386 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).

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

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 399 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).

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

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 406 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

Definition at line 308 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

Definition at line 329 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

Definition at line 318 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.

Note: You may write a query in .sql file and generate a header file with Query from it. See External SQL/YQL files for more information.

◆ 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/main.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

TransactionOptions storages::postgres::Transaction::Deferrable {TransactionOptions::Deferrable()}

staticconstexpr

Read-only serializable deferrable transaction.

Definition at line 153 of file transaction.hpp.

◆ kDefaultRowsInChunk

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

staticconstexpr

Definition at line 156 of file transaction.hpp.

◆ RO

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

staticconstexpr

Read-only read committed transaction.

Definition at line 151 of file transaction.hpp.

◆ RW

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

staticconstexpr

Read-write read committed transaction.

Definition at line 149 of file transaction.hpp.

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

userver/storages/postgres/transaction.hpp

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