userver: userver/storages/postgres/options.hpp Source File
All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Modules Pages Concepts
options.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/postgres/options.hpp
4/// @brief Options
5
6#include <chrono>
7#include <cstdint>
8#include <iosfwd>
9#include <optional>
10#include <string>
11#include <unordered_map>
12
13#include <userver/congestion_control/controllers/linear.hpp>
14#include <userver/storages/postgres/postgres_fwd.hpp>
15#include <userver/utils/impl/transparent_hash.hpp>
16#include <userver/utils/str_icase.hpp>
17#include <userver/utils/string_literal.hpp>
18
19USERVER_NAMESPACE_BEGIN
20
21namespace storages::postgres {
22
23/*! [Isolation levels] */
24/// @brief SQL transaction isolation level
25/// @see https://www.postgresql.org/docs/current/static/sql-set-transaction.html
27 kReadCommitted, //!< READ COMMITTED
28 kRepeatableRead, //!< REPEATABLE READ
29 kSerializable, //!< SERIALIZABLE
30 kReadUncommitted //!< READ UNCOMMITTED @warning In Postgres READ UNCOMMITTED
31 //!< is treated as READ COMMITTED
32};
33/*! [Isolation levels] */
34
35std::ostream& operator<<(std::ostream&, IsolationLevel);
36
37/// @brief PostgreSQL transaction options
38///
39/// A transaction can be started using all isolation levels and modes
40/// supported by PostgreSQL server as specified in it's documentation.
41///
42/// Default isolation level is READ COMMITTED, default mode is READ WRITE.
43/// @code
44/// // Read-write read committed transaction.
45/// TransactionOptions opts;
46/// @endcode
47///
48/// Transaction class provides constants Transaction::RW, Transaction::RO and
49/// Transaction::Deferrable for convenience.
50///
51/// Other variants can be created with TransactionOptions constructors
52/// that are constexpr.
53///
54/// @see https://www.postgresql.org/docs/current/static/sql-set-transaction.html
56 /*! [Transaction modes] */
57 enum Mode : std::uint16_t {
58 kReadWrite = 0,
59 kReadOnly = 1,
60 kDeferrable = 3 //!< Deferrable transaction is read only
61 };
62 /*! [Transaction modes] */
64 Mode mode = kReadWrite;
65
66 constexpr TransactionOptions() = default;
67 constexpr explicit TransactionOptions(IsolationLevel lvl) : isolation_level{lvl} {}
68 constexpr TransactionOptions(IsolationLevel lvl, Mode m) : isolation_level{lvl}, mode{m} {}
69 constexpr explicit TransactionOptions(Mode m) : mode{m} {}
70
71 bool IsReadOnly() const { return mode & kReadOnly; }
72
73 /// The deferrable property has effect only if the transaction is also
74 /// serializable and read only
76};
77
78constexpr inline bool operator==(TransactionOptions lhs, TransactionOptions rhs) {
79 return lhs.isolation_level == rhs.isolation_level && lhs.mode == rhs.mode;
80}
81USERVER_NAMESPACE::utils::StringLiteral BeginStatement(TransactionOptions opts) noexcept;
82
83/// A structure to control timeouts for PosrgreSQL queries
84///
85/// There are two parameters, `execute` and `statement`.
86///
87/// `execute` parameter controls the overall time the driver spends executing a
88/// query, that includes:
89/// * connecting to PostgreSQL server, if there are no connections available and
90/// connection pool still has space for new connections;
91/// * waiting for a connection to become idle if there are no idle connections
92/// and connection pool already has reached it's max size;
93/// * preparing a statement if the statement is run for the first time on the
94/// connection;
95/// * binding parameters and executing the statement;
96/// * waiting for the first results to arrive from the server. If the result set
97/// is big, only time to the first data packet is taken into account.
98///
99/// `statement` is rather straightforward, it's the PostgreSQL server-side
100/// parameter, and it controls the time the database backend can spend executing
101/// a single statement. It is very costly to change the statement timeout
102/// often, as it requires a roundtrip to the database to change the setting.
103/// @see https://www.postgresql.org/docs/12/runtime-config-client.html
104///
105/// `execute` timeout should always be greater than the `statement` timeout!
106///
107/// In case of a timeout, either back-end or overall, the client gets an
108/// exception and the driver tries to clean up the connection for further reuse.
110 /// Overall timeout for a command being executed
111 TimeoutDuration network_timeout_ms{};
112 /// PostgreSQL server-side timeout
113 TimeoutDuration statement_timeout_ms{};
114
115 constexpr CommandControl(TimeoutDuration network_timeout_ms, TimeoutDuration statement_timeout_ms)
116 : network_timeout_ms(network_timeout_ms), statement_timeout_ms(statement_timeout_ms) {}
117
118 constexpr CommandControl WithExecuteTimeout(TimeoutDuration n) const noexcept { return {n, statement_timeout_ms}; }
119
120 constexpr CommandControl WithStatementTimeout(TimeoutDuration s) const noexcept { return {network_timeout_ms, s}; }
121
122 bool operator==(const CommandControl& rhs) const {
124 }
125
126 bool operator!=(const CommandControl& rhs) const { return !(*this == rhs); }
127};
128
129/// @brief storages::postgres::CommandControl that may not be set
130using OptionalCommandControl = std::optional<CommandControl>;
131
132using CommandControlByMethodMap = USERVER_NAMESPACE::utils::impl::TransparentMap<std::string, CommandControl>;
133using CommandControlByHandlerMap =
134 USERVER_NAMESPACE::utils::impl::TransparentMap<std::string, CommandControlByMethodMap>;
135using CommandControlByQueryMap = std::unordered_map<std::string, CommandControl>;
136
137OptionalCommandControl
138GetHandlerOptionalCommandControl(const CommandControlByHandlerMap& map, std::string_view path, std::string_view method);
139
140OptionalCommandControl
141GetQueryOptionalCommandControl(const CommandControlByQueryMap& map, const std::string& query_name);
142
143/// Default initial pool connection count
144inline constexpr std::size_t kDefaultPoolMinSize = 4;
145
146/// Default maximum replication lag
147inline constexpr auto kDefaultMaxReplicationLag = std::chrono::seconds{60};
148
149/// Default pool connections limit
150inline constexpr std::size_t kDefaultPoolMaxSize = 15;
151
152/// Default size of queue for clients waiting for connections
153inline constexpr std::size_t kDefaultPoolMaxQueueSize = 200;
154
155/// Default limit for concurrent establishing connections number
156inline constexpr std::size_t kDefaultConnectingLimit = 0;
157
158/// @brief PostgreSQL topology options
159///
160/// Dynamic option @ref POSTGRES_TOPOLOGY_SETTINGS
162 /// Maximum replication lag. Once the replica lag exceeds this value it will be automatically disabled.
164
165 /// List of manually disabled replicas (FQDNs).
166 std::unordered_set<std::string, USERVER_NAMESPACE::utils::StrIcaseHash, USERVER_NAMESPACE::utils::StrIcaseEqual>
168};
169
170/// @brief PostgreSQL connection pool options
171///
172/// Dynamic option @ref POSTGRES_CONNECTION_POOL_SETTINGS
174 /// Number of connections created initially
176
177 /// Maximum number of created connections
179
180 /// Maximum number of clients waiting for a connection
182
183 /// Limits number of concurrent establishing connections (0 - unlimited)
185
186 bool operator==(const PoolSettings& rhs) const {
187 return min_size == rhs.min_size && max_size == rhs.max_size && max_queue_size == rhs.max_queue_size &&
189 }
190};
191
192/// Default size limit for prepared statements cache
193inline constexpr std::size_t kDefaultMaxPreparedCacheSize = 200;
194
195/// Pipeline mode configuration
196///
197/// Dynamic option @ref POSTGRES_CONNECTION_PIPELINE_EXPERIMENT
198enum class PipelineMode { kDisabled, kEnabled };
199
200/// Whether to omit excessive D(escribe) message
201/// when executing prepared statements
202///
203/// Dynamic option @ref POSTGRES_OMIT_DESCRIBE_IN_EXECUTE
204enum class OmitDescribeInExecuteMode { kDisabled, kEnabled };
205
206/// PostgreSQL connection options
207///
208/// Dynamic option @ref POSTGRES_CONNECTION_SETTINGS
210 enum PreparedStatementOptions {
211 kCachePreparedStatements,
212 kNoPreparedStatements,
213 };
214 enum UserTypesOptions {
215 kUserTypesEnabled,
216 kUserTypesEnforced,
217 kPredefinedTypesOnly,
218 };
219 enum CheckQueryParamsOptions {
220 kIgnoreUnused,
221 kCheckUnused,
222 };
223 enum DiscardOnConnectOptions {
224 kDiscardNone,
225 kDiscardAll,
226 };
227 using SettingsVersion = std::size_t;
228
229 /// Cache prepared statements or not
230 PreparedStatementOptions prepared_statements = kCachePreparedStatements;
231
232 /// Enables the usage of user-defined types
233 UserTypesOptions user_types = kUserTypesEnabled;
234
235 /// Checks for not-NULL query params that are not used in query
236 CheckQueryParamsOptions ignore_unused_query_params = kCheckUnused;
237
238 /// Limits the size or prepared statements cache
240
241 /// Turns on connection pipeline mode
243
244 /// Enables protocol-level optimization when executing prepared statements
246
247 /// This many connection errors in 15 seconds block new connections opening
248 std::size_t recent_errors_threshold = 2;
249
250 /// The maximum lifetime of the connection after which it will be closed
251 std::optional<std::chrono::seconds> max_ttl{};
252
253 /// Execute discard all after establishing a new connection
254 DiscardOnConnectOptions discard_on_connect = kDiscardAll;
255
256 bool deadline_propagation_enabled = true;
257
258 /// Helps keep track of the changes in settings
259 SettingsVersion version{0U};
260
261 bool operator==(const ConnectionSettings& rhs) const {
262 return !RequiresConnectionReset(rhs) && recent_errors_threshold == rhs.recent_errors_threshold;
263 }
264
265 bool operator!=(const ConnectionSettings& rhs) const { return !(*this == rhs); }
266
267 bool RequiresConnectionReset(const ConnectionSettings& rhs) const {
268 // TODO: max_prepared_cache_size check could be relaxed
274 }
275};
276
277/// @brief PostgreSQL statements metrics options
278///
279/// Dynamic option @ref POSTGRES_STATEMENT_METRICS_SETTINGS
280struct StatementMetricsSettings final {
281 /// Store metrics in LRU of this size
282 std::size_t max_statements{0};
283
284 bool operator==(const StatementMetricsSettings& other) const { return max_statements == other.max_statements; }
285};
286
287/// Initialization modes
288enum class InitMode {
289 kSync = 0,
290 kAsync,
291};
292
293enum class ConnlimitMode {
294 kManual = 0,
295 kAuto,
296};
297
298/// Settings for storages::postgres::Cluster
300 /// settings for statements metrics
301 StatementMetricsSettings statement_metrics_settings;
302
303 /// settings for host discovery
305
306 /// settings for connection pools
308
309 /// settings for individual connections
311
312 /// initialization mode
314
315 /// database name
316 std::string db_name;
317
318 /// connection limit change mode
319 ConnlimitMode connlimit_mode = ConnlimitMode::kAuto;
320
321 /// congestion control settings
322 congestion_control::v2::LinearController::StaticConfig cc_config;
323};
324
325} // namespace storages::postgres
326
327USERVER_NAMESPACE_END