userver: userver/storages/postgres/cluster.hpp Source File
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
cluster.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/postgres/cluster.hpp
4/// @brief @copybrief storages::postgres::Cluster
5
6#include <memory>
7
8#include <userver/clients/dns/resolver_fwd.hpp>
9#include <userver/dynamic_config/source.hpp>
10#include <userver/engine/task/task_processor_fwd.hpp>
11#include <userver/engine/task/task_with_result.hpp>
12#include <userver/error_injection/settings_fwd.hpp>
13#include <userver/testsuite/postgres_control.hpp>
14#include <userver/testsuite/tasks.hpp>
15
16#include <userver/storages/postgres/cluster_types.hpp>
17#include <userver/storages/postgres/database.hpp>
18#include <userver/storages/postgres/detail/non_transaction.hpp>
19#include <userver/storages/postgres/notify.hpp>
20#include <userver/storages/postgres/options.hpp>
21#include <userver/storages/postgres/query.hpp>
22#include <userver/storages/postgres/query_queue.hpp>
23#include <userver/storages/postgres/statistics.hpp>
24#include <userver/storages/postgres/transaction.hpp>
25
26/// @page pg_topology uPg: Cluster topology discovery
27///
28/// @par Principles of PgaaS role determination
29/// - Every host except master is in recovery state from PostgreSQL's POV.
30/// This means the check 'select pg_is_in_recovery()' returns `false` for the
31/// master and `true` for every other host type.
32/// - Some hosts are in sync slave mode. This may be determined by executing
33/// 'show synchronous_standby_names' on the master.
34/// See
35/// https://www.postgresql.org/docs/current/runtime-config-replication.html#GUC-SYNCHRONOUS-STANDBY-NAMES
36/// for more information.
37///
38/// @par PgaaS sync slaves lag
39/// By default, PgaaS synchronous slaves are working with 'synchronous_commit'
40/// set to 'remote_apply'. Therefore, sync slave may be lagging behind the
41/// master and thus is not truly 'synchronous' from the reader's POV,
42/// but things may change with time.
43///
44/// @par Implementation
45/// Topology update runs every second.
46///
47/// Every host is assigned a connection with special ID (4100200300).
48/// Using this connection we check for host availability, writability
49/// (master detection) and perform RTT measurements.
50///
51/// After the initial check we know about master presence and RTT for each host.
52/// Master host is queried about synchronous replication status. We use this
53/// info to identify synchronous slaves and to detect "quorum commit" presence.
54///
55///
56/// ----------
57///
58/// @htmlonly <div class="bottom-nav"> @endhtmlonly
59/// ⇦ @ref pg_errors | @ref scripts/docs/en/userver/pg_connlimit_mode_auto.md ⇨
60/// @htmlonly </div> @endhtmlonly
61
62USERVER_NAMESPACE_BEGIN
63
64namespace components {
65class Postgres;
66} // namespace components
67
68namespace storages::postgres {
69
70namespace detail {
71
72class ClusterImpl;
73using ClusterImplPtr = std::unique_ptr<ClusterImpl>;
74
75} // namespace detail
76
77/// @ingroup userver_clients
78///
79/// @brief Interface for executing queries on a cluster of PostgreSQL servers
80///
81/// See @ref pg_user_row_types "Typed PostgreSQL results" for usage examples of
82/// the storages::postgres::ResultSet.
83///
84/// Usually retrieved from components::Postgres component.
85///
86/// @todo Add information about topology discovery
87class Cluster {
88public:
89 /// Cluster constructor
90 /// @param dsns List of DSNs to connect to
91 /// @param resolver asynchronous DNS resolver
92 /// @param bg_task_processor task processor for blocking connection operations
93 /// @param cluster_settings struct with settings fields:
94 /// task_data_keys_settings - settings for per-handler command controls
95 /// topology_settings - settings for host discovery
96 /// pool_settings - settings for connection pools
97 /// conn_settings - settings for individual connections
98 /// @param default_cmd_ctls default command execution options
99 /// @param testsuite_pg_ctl command execution options customizer for testsuite
100 /// @param ei_settings error injection settings
101 /// @param testsuite_tasks see @ref testsuite::TestsuiteTasks
102 /// @param config_source see @ref dynamic_config::Source
103 /// @param shard_number shard number
104 /// @note When `max_connection_pool_size` is reached, and no idle connections
105 /// available, `PoolError` is thrown for every new connection
106 /// request
108 DsnList dsns,
109 clients::dns::Resolver* resolver,
110 engine::TaskProcessor& bg_task_processor,
111 const ClusterSettings& cluster_settings,
112 DefaultCommandControls&& default_cmd_ctls,
113 const testsuite::PostgresControl& testsuite_pg_ctl,
114 const error_injection::Settings& ei_settings,
115 testsuite::TestsuiteTasks& testsuite_tasks,
116 dynamic_config::Source config_source,
117 USERVER_NAMESPACE::utils::statistics::MetricsStoragePtr metrics,
118 int shard_number
119 );
120 ~Cluster();
121
122 /// Get cluster statistics
123 ///
124 /// The statistics object is too big to fit on stack
125 ClusterStatisticsPtr GetStatistics() const;
126
127 /// @name Transaction start
128 /// @{
129
130 /// Start a transaction in any available connection depending on transaction
131 /// options.
132 ///
133 /// If the transaction is RW, will start transaction in a connection
134 /// to master. If the transaction is RO, will start trying connections
135 /// starting with slaves.
136 /// @throws ClusterUnavailable if no hosts are available
137 Transaction Begin(const TransactionOptions&, OptionalCommandControl = {});
138
139 /// Start a transaction in a connection with specified host selection rules.
140 ///
141 /// If the requested host role is not available, may fall back to another
142 /// host role, see ClusterHostType.
143 /// If the transaction is RW, only master connection can be used.
144 /// @throws ClusterUnavailable if no hosts are available
145 Transaction Begin(ClusterHostTypeFlags, const TransactionOptions&, OptionalCommandControl = {});
146
147 /// Start a named transaction in any available connection depending on
148 /// transaction options.
149 ///
150 /// If the transaction is RW, will start transaction in a connection
151 /// to master. If the transaction is RO, will start trying connections
152 /// starting with slaves.
153 /// `name` is used to set command control in config at runtime.
154 /// @throws ClusterUnavailable if no hosts are available
155 Transaction Begin(std::string name, const TransactionOptions&);
156
157 /// Start a named transaction in a connection with specified host selection
158 /// rules.
159 ///
160 /// If the requested host role is not available, may fall back to another
161 /// host role, see ClusterHostType.
162 /// If the transaction is RW, only master connection can be used.
163 /// `name` is used to set command control in config at runtime.
164 /// @throws ClusterUnavailable if no hosts are available
165 Transaction Begin(std::string name, ClusterHostTypeFlags, const TransactionOptions&);
166 /// @}
167
168 /// Start a query queue with specified host selection rules and timeout for
169 /// acquiring a connection.
170 [[nodiscard]] QueryQueue CreateQueryQueue(ClusterHostTypeFlags flags);
171
172 /// Start a query queue with specified host selection rules and timeout for
173 /// acquiring a connection.
174 [[nodiscard]] QueryQueue CreateQueryQueue(ClusterHostTypeFlags flags, TimeoutDuration acquire_timeout);
175
176 /// @name Single-statement query in an auto-commit transaction
177 /// @{
178
179 /// @brief Execute a statement at host of specified type.
180 /// @note You must specify at least one role from ClusterHostType here
181 /// @note You may write a query in `.sql` file and generate a header file with Query from it.
182 /// See @ref scripts/docs/en/userver/sql_files.md for more information.
183 ///
184 /// @snippet storages/postgres/tests/landing_test.cpp Exec sample
185 ///
186 /// @warning Do NOT create a query string manually by embedding arguments!
187 /// It leads to vulnerabilities and bad performance. Either pass arguments
188 /// separately, or use storages::postgres::ParameterScope.
189 template <typename... Args>
190 ResultSet Execute(ClusterHostTypeFlags, const Query& query, const Args&... args);
191
192 /// @brief Execute a statement with specified host selection rules and command
193 /// control settings.
194 /// @note You must specify at least one role from ClusterHostType here
195 /// @note You may write a query in `.sql` file and generate a header file with Query from it.
196 /// See @ref scripts/docs/en/userver/sql_files.md for more information.
197 ///
198 /// @warning Do NOT create a query string manually by embedding arguments!
199 /// It leads to vulnerabilities and bad performance. Either pass arguments
200 /// separately, or use storages::postgres::ParameterScope.
201 template <typename... Args>
202 ResultSet Execute(ClusterHostTypeFlags, OptionalCommandControl, const Query& query, const Args&... args);
203
204 /// @brief Execute a statement with stored arguments and specified host
205 /// selection rules.
206 /// @note You may write a query in `.sql` file and generate a header file with Query from it.
207 /// See @ref scripts/docs/en/userver/sql_files.md for more information.
208 ///
209 /// @warning Do NOT create a query string manually by embedding arguments!
210 /// It leads to vulnerabilities and bad performance. Either pass arguments
211 /// separately, or use storages::postgres::ParameterScope.
212 ResultSet Execute(ClusterHostTypeFlags flags, const Query& query, const ParameterStore& store);
213
214 /// @brief Execute a statement with stored arguments, specified host selection
215 /// rules and command control settings.
216 /// @note You may write a query in `.sql` file and generate a header file with Query from it.
217 /// See @ref scripts/docs/en/userver/sql_files.md for more information.
218 ///
219 /// @warning Do NOT create a query string manually by embedding arguments!
220 /// It leads to vulnerabilities and bad performance. Either pass arguments
221 /// separately, or use storages::postgres::ParameterScope.
223 ClusterHostTypeFlags flags,
224 OptionalCommandControl statement_cmd_ctl,
225 const Query& query,
226 const ParameterStore& store
227 );
228 /// @}
229
230 /// @brief Listen for notifications on channel
231 /// @warning Each NotifyScope owns a single connection taken from the pool,
232 /// which effectively decreases the number of usable connections
233 NotifyScope Listen(std::string_view channel, OptionalCommandControl = {});
234
235 /// Replaces globally updated command control with a static user-provided one
237
238 /// Returns current default command control
240
241 void SetHandlersCommandControl(CommandControlByHandlerMap handlers_command_control);
242
243 void SetQueriesCommandControl(CommandControlByQueryMap queries_command_control);
244
245 /// @cond
246 /// Updates default command control from global config (if not set by user)
247 void ApplyGlobalCommandControlUpdate(CommandControl);
248 /// @endcond
249
250 /// Replaces cluster connection settings.
251 ///
252 /// Connections with an old settings will be dropped and reestablished.
254
255 void SetPoolSettings(const PoolSettings& settings);
256
257 void SetTopologySettings(const TopologySettings& settings);
258
259 void SetStatementMetricsSettings(const StatementMetricsSettings& settings);
260
261 void SetDsnList(const DsnList&);
262
263private:
264 detail::NonTransaction Start(ClusterHostTypeFlags, OptionalCommandControl);
265
266 OptionalCommandControl GetQueryCmdCtl(const std::string& query_name) const;
267 OptionalCommandControl GetHandlersCmdCtl(OptionalCommandControl cmd_ctl) const;
268
269 detail::ClusterImplPtr pimpl_;
270};
271
272template <typename... Args>
273ResultSet Cluster::Execute(ClusterHostTypeFlags flags, const Query& query, const Args&... args) {
274 return Execute(flags, OptionalCommandControl{}, query, args...);
275}
276
277template <typename... Args>
279 ClusterHostTypeFlags flags,
280 OptionalCommandControl statement_cmd_ctl,
281 const Query& query,
282 const Args&... args
283) {
284 if (!statement_cmd_ctl && query.GetName()) {
285 statement_cmd_ctl = GetQueryCmdCtl(query.GetName()->GetUnderlying());
286 }
287 statement_cmd_ctl = GetHandlersCmdCtl(statement_cmd_ctl);
288 auto ntrx = Start(flags, statement_cmd_ctl);
289 return ntrx.Execute(statement_cmd_ctl, query, args...);
290}
291
292} // namespace storages::postgres
293
294USERVER_NAMESPACE_END