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

#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
dsnsList of DSNs to connect to
resolverasynchronous DNS resolver
bg_task_processortask processor for blocking connection operations
cluster_settingsstruct 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_ctlsdefault command execution options
testsuite_pg_ctlcommand execution options customizer for testsuite
ei_settingserror 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
ClusterUnavailableif 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
ClusterUnavailableif 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
ClusterUnavailableif 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
ClusterUnavailableif 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/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) {
"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 253 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 259 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: