Github   Telegram
Loading...
Searching...
No Matches
Public Member Functions | List of all members
storages::postgres::Cluster Class Reference

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)
 
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 (const CommandControlByHandlerMap &handlers_command_control)
 
void SetQueriesCommandControl (const CommandControlByQueryMap &queries_command_control)
 
void SetConnectionSettings (const ConnectionSettings &settings)
 
void SetPoolSettings (const PoolSettings &settings)
 
void SetStatementMetricsSettings (const StatementMetricsSettings &settings)
 
void SetPipelineMode (PipelineMode mode)
 
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. More...
 
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. More...
 
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 83 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 
)

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

Warning
It will overwrite pipeline mode settings set by SetPipelineMode.

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