storages::postgres::Cluster Class Reference

Table of Contents

• Public Member Functions
• Detailed Description
• Constructor & Destructor Documentation
• Cluster()
• Member Function Documentation
• Begin() [1/4]
• Begin() [2/4]
• Begin() [3/4]
• Begin() [4/4]
• Execute() [1/2]
• Execute() [2/2]
• GetStatistics()
• SetConnectionSettings()

Interface for executing queries on a cluster of PostgreSQL servers. More...

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

Public Member Functions
	Cluster (DsnList dsns, clients::dns::Resolver *resolver, engine::TaskProcessor &bg_task_processor, const ClusterSettings &cluster_settings, DefaultCommandControls &&default_cmd_ctls, const testsuite::PostgresControl &testsuite_pg_ctl, const error_injection::Settings &ei_settings, testsuite::TestsuiteTasks &testsuite_tasks, dynamic_config::Source config_source, int shard_number)
ClusterStatisticsPtr	GetStatistics () const
void	SetDefaultCommandControl (CommandControl)
	Replaces globally updated command control with a static user-provided one.
CommandControl	GetDefaultCommandControl () const
	Returns current default command control.
void	SetHandlersCommandControl (CommandControlByHandlerMap handlers_command_control)
void	SetQueriesCommandControl (CommandControlByQueryMap queries_command_control)
void	SetConnectionSettings (const ConnectionSettings &settings)
void	SetPoolSettings (const PoolSettings &settings)
void	SetStatementMetricsSettings (const StatementMetricsSettings &settings)
Transaction start
Transaction	Begin (const TransactionOptions &, OptionalCommandControl={})
Transaction	Begin (ClusterHostTypeFlags, const TransactionOptions &, OptionalCommandControl={})
Transaction	Begin (const std::string &name, const TransactionOptions &)
Transaction	Begin (const std::string &name, ClusterHostTypeFlags, const TransactionOptions &)
Single-statement query in an auto-commit transaction
template<typename... Args>
ResultSet	Execute (ClusterHostTypeFlags, const Query &query, const Args &... args)
	Execute a statement at host of specified type.
template<typename... Args>
ResultSet	Execute (ClusterHostTypeFlags, OptionalCommandControl, const Query &query, const Args &... args)
	Execute a statement with specified host selection rules and command control settings.
ResultSet	Execute (ClusterHostTypeFlags flags, const Query &query, const ParameterStore &store)
	Execute a statement with stored arguments and specified host selection rules.
ResultSet	Execute (ClusterHostTypeFlags flags, OptionalCommandControl statement_cmd_ctl, const Query &query, const ParameterStore &store)
	Execute a statement with stored arguments, specified host selection rules and command control settings.

Detailed Description

Interface for executing queries on a cluster of PostgreSQL servers.

See Typed PostgreSQL results for usage examples of the storages::postgres::ResultSet.

Usually retrieved from components::Postgres component.

Todo:

Add information about topology discovery

Definition at line 85 of file cluster.hpp.

Constructor & Destructor Documentation

Cluster()

storages::postgres::Cluster::Cluster	(	DsnList	dsns,
		clients::dns::Resolver *	resolver,
		engine::TaskProcessor &	bg_task_processor,
		const ClusterSettings &	cluster_settings,
		DefaultCommandControls &&	default_cmd_ctls,
		const testsuite::PostgresControl &	testsuite_pg_ctl,
		const error_injection::Settings &	ei_settings,
		testsuite::TestsuiteTasks &	testsuite_tasks,
		dynamic_config::Source	config_source,
		int	shard_number
	)

Cluster constructor

Parameters

dsns	List of DSNs to connect to
resolver	asynchronous DNS resolver
bg_task_processor	task processor for blocking connection operations
cluster_settings	struct with settings fields: task_data_keys_settings - settings for per-handler command controls topology_settings - settings for host discovery pool_settings - settings for connection pools conn_settings - settings for individual connections
default_cmd_ctls	default command execution options
testsuite_pg_ctl	command execution options customizer for testsuite
ei_settings	error injection settings

Note

When max_connection_pool_size is reached, and no idle connections available, PoolError is thrown for every new connection request

Member Function Documentation

Begin() [1/4]

Transaction storages::postgres::Cluster::Begin	(	ClusterHostTypeFlags	,
		const TransactionOptions &	,
		OptionalCommandControl	= {}
	)

Start a transaction in a connection with specified host selection rules.

If the requested host role is not available, may fall back to another host role, see ClusterHostType. If the transaction is RW, only master connection can be used.

Exceptions

ClusterUnavailable

if no hosts are available

Begin() [2/4]

Transaction storages::postgres::Cluster::Begin	(	const std::string &	name,
		ClusterHostTypeFlags	,
		const TransactionOptions &
	)

Start a named transaction in a connection with specified host selection rules.

If the requested host role is not available, may fall back to another host role, see ClusterHostType. If the transaction is RW, only master connection can be used. name is used to set command control in config at runtime.

Exceptions

ClusterUnavailable

if no hosts are available

Begin() [3/4]

Transaction storages::postgres::Cluster::Begin	(	const std::string &	name,
		const TransactionOptions &
	)

Start a named transaction in any available connection depending on transaction options.

If the transaction is RW, will start transaction in a connection to master. If the transaction is RO, will start trying connections starting with slaves. name is used to set command control in config at runtime.

Exceptions

ClusterUnavailable

if no hosts are available

Begin() [4/4]

Transaction storages::postgres::Cluster::Begin	(	const TransactionOptions &	,
		OptionalCommandControl	= {}
	)

Start a transaction in any available connection depending on transaction options.

If the transaction is RW, will start transaction in a connection to master. If the transaction is RO, will start trying connections starting with slaves.

Exceptions

ClusterUnavailable

if no hosts are available

Execute() [1/2]

template<typename... Args>

ResultSet storages::postgres::Cluster::Execute	(	ClusterHostTypeFlags	flags,
		const Query &	query,
		const Args &...	args
	)

Execute a statement at host of specified type.

Note

You must specify at least one role from ClusterHostType here

std::size_t InsertSomeKey(storages::postgres::Cluster& pg,
                          std::string_view key) {
  auto res = pg.Execute(storages::postgres::ClusterHostType::kMaster,
                        "INSERT INTO keys VALUES ($1)", key);
  return res.RowsAffected();
}

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 235 of file cluster.hpp.

Execute() [2/2]

template<typename... Args>

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

Execute a statement with specified host selection rules and command control settings.

Note

You must specify at least one role from ClusterHostType here

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 241 of file cluster.hpp.

GetStatistics()

ClusterStatisticsPtr storages::postgres::Cluster::GetStatistics

(

)

const

Get cluster statistics

The statistics object is too big to fit on stack

SetConnectionSettings()

void storages::postgres::Cluster::SetConnectionSettings

(

const ConnectionSettings &

settings

)

Replaces cluster connection settings.

Connections with an old settings will be dropped and reestablished.

---

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

• userver/storages/postgres/cluster.hpp