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

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 87 of file 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

QueryQueue	CreateQueryQueue (ClusterHostTypeFlags flags)

QueryQueue	CreateQueryQueue (ClusterHostTypeFlags flags, TimeoutDuration acquire_timeout)

NotifyScope	Listen (std::string_view channel, OptionalCommandControl={})
	Listen for notifications on channel.

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	SetTopologySettings (const TopologySettings &settings)

void	SetStatementMetricsSettings (const StatementMetricsSettings &settings)

Transaction start
Transaction	Begin (const TransactionOptions &, OptionalCommandControl={})

Transaction	Begin (ClusterHostTypeFlags, const TransactionOptions &, OptionalCommandControl={})

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

Transaction	Begin (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.

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

◆ Begin() [3/4]

Transaction storages::postgres::Cluster::Begin	(	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() [4/4]

Transaction storages::postgres::Cluster::Begin	(	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

◆ CreateQueryQueue() [1/2]

QueryQueue storages::postgres::Cluster::CreateQueryQueue ( ClusterHostTypeFlags flags )

Start a query queue with specified host selection rules and timeout for acquiring a connection.

◆ CreateQueryQueue() [2/2]

QueryQueue storages::postgres::Cluster::CreateQueryQueue	(	ClusterHostTypeFlags	flags,
		TimeoutDuration	acquire_timeout )

Start a query queue with specified host selection rules and timeout for acquiring a connection.

◆ Execute() [1/4]

ResultSet storages::postgres::Cluster::Execute	(	ClusterHostTypeFlags	flags,
		const Query &	query,
		const ParameterStore &	store )

Execute a statement with stored arguments and specified host selection rules.

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.

◆ Execute() [2/4]

ResultSet storages::postgres::Cluster::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.

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.

◆ Execute() [3/4]

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

◆ Execute() [4/4]

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

◆ GetStatistics()

ClusterStatisticsPtr storages::postgres::Cluster::GetStatistics ( ) const

Get cluster statistics

The statistics object is too big to fit on stack

◆ Listen()

NotifyScope storages::postgres::Cluster::Listen	(	std::string_view	channel,
		OptionalCommandControl	= {} )

Listen for notifications on channel.

Warning: Each NotifyScope owns a single connection taken from the pool, which effectively decreases the number of usable connections

◆ 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

Detailed Description

Public Member Functions

Constructor & Destructor Documentation

◆ Cluster()

Member Function Documentation

◆ Begin() [1/4]

◆ Begin() [2/4]

◆ Begin() [3/4]

◆ Begin() [4/4]

◆ CreateQueryQueue() [1/2]

◆ CreateQueryQueue() [2/2]

◆ Execute() [1/4]

◆ Execute() [2/4]

◆ Execute() [3/4]

◆ Execute() [4/4]

◆ GetStatistics()

◆ Listen()

◆ SetConnectionSettings()