userver: userver/storages/mongo/component.hpp Source File
Loading...
Searching...
No Matches
component.hpp
Go to the documentation of this file.
1#pragma once
2
3/// @file userver/storages/mongo/component.hpp
4/// @brief @copybrief components::Mongo
5
6#include <userver/components/component_base.hpp>
7#include <userver/storages/mongo/multi_mongo.hpp>
8#include <userver/storages/mongo/pool.hpp>
9#include <userver/storages/secdist/component.hpp>
10#include <userver/utils/statistics/entry.hpp>
11
12USERVER_NAMESPACE_BEGIN
13
14namespace components {
15
16// clang-format off
17
18/// @ingroup userver_components
19///
20/// @brief MongoDB client component
21///
22/// Provides access to a MongoDB database.
23///
24/// ## Dynamic options:
25/// * @ref MONGO_CONGESTION_CONTROL_DATABASES_SETTINGS
26/// * @ref MONGO_CONGESTION_CONTROL_ENABLED
27/// * @ref MONGO_CONGESTION_CONTROL_SETTINGS
28/// * @ref MONGO_CONNECTION_POOL_SETTINGS
29/// * @ref MONGO_DEFAULT_MAX_TIME_MS
30///
31/// ## Static configuration example:
32///
33/// ```
34/// mongo-taxi:
35/// dbalias: taxi
36/// appname: userver-sample
37/// conn_timeout: 2s
38/// so_timeout: 10s
39/// queue_timeout: 1s
40/// initial_size: 16
41/// max_size: 128
42/// idle_limit: 64
43/// connecting_limit: 8
44/// local_threshold: 15ms
45/// maintenance_period: 15s
46/// stats_verbosity: terse
47/// ```
48/// You must specify one of `dbalias` or `dbconnection`.
49///
50/// ## Static options:
51/// Name | Description | Default value
52/// ---- | ----------- | -------------
53/// dbalias | name of the database in secdist config (if available) | --
54/// dbconnection | connection string (used if no dbalias specified) | --
55/// appname | application name for the DB server | userver
56/// conn_timeout | connection timeout | 2s
57/// so_timeout | socket timeout | 10s
58/// queue_timeout | max connection queue wait time | 1s
59/// initial_size | number of connections created initially | 16
60/// max_size | limit for total connections number | 128
61/// idle_limit | limit for idle connections number | 64
62/// connecting_limit | limit for establishing connections number | 8
63/// local_threshold | latency window for instance selection | mongodb default
64/// max_replication_lag | replication lag limit for usable secondaries, min. 90s | -
65/// maintenance_period | pool maintenance period (idle connections pruning etc.) | 15s
66/// stats_verbosity | changes the granularity of reported metrics | 'terse'
67/// dns_resolver | server hostname resolver type (getaddrinfo or async) | 'async'
68///
69/// `stats_verbosity` accepts one of the following values:
70/// Value | Description
71/// ----- | -----------
72/// terse | Default value, report only cumulative stats and read/write totals
73/// full | Separate metrics for each operation, divided by read preference or write concern
74///
75/// It is a common practice to provide a database connection string via
76/// environment variables. To retrieve a value from the environment use
77/// `dbconnection#env: THE_ENV_VARIABLE_WITH_CONNECTION_STRING` as described
78/// in yaml_config::YamlConfig.
79///
80/// ## Secdist format
81///
82/// If a `dbalias` option is provided, for example
83/// `dbalias: some_name_of_your_database`, then the Secdist entry for that alias
84/// should look like following:
85/// @code{.json}
86/// {
87/// "mongo_settings": {
88/// "some_name_of_your_database": {
89/// "dbsettings": {
90/// "uri": "mongodb://user:password@host:port/database_name"
91/// }
92/// }
93/// }
94/// }
95/// @endcode
96
97// clang-format on
98
99class Mongo : public ComponentBase {
100public:
101 /// Component constructor
102 Mongo(const ComponentConfig&, const ComponentContext&);
103
104 /// Component destructor
105 ~Mongo() override;
106
107 /// Client pool accessor
108 storages::mongo::PoolPtr GetPool() const;
109
110 static yaml_config::Schema GetStaticConfigSchema();
111
112private:
113 storages::mongo::PoolPtr pool_;
114
115 // Subscriptions must be the last fields.
116 utils::statistics::Entry statistics_holder_;
117};
118
119template <>
120inline constexpr bool kHasValidate<Mongo> = true;
121
122// clang-format off
123
124/// @ingroup userver_components
125///
126/// @brief Dynamically configurable MongoDB client component
127///
128/// Provides access to a dynamically reconfigurable set of MongoDB databases.
129///
130/// ## Dynamic options:
131/// * @ref MONGO_CONGESTION_CONTROL_DATABASES_SETTINGS
132/// * @ref MONGO_CONGESTION_CONTROL_ENABLED
133/// * @ref MONGO_CONGESTION_CONTROL_SETTINGS
134/// * @ref MONGO_CONNECTION_POOL_SETTINGS
135/// * @ref MONGO_DEFAULT_MAX_TIME_MS
136///
137/// ## Static configuration example:
138///
139/// ```
140/// multi-mongo:
141/// appname: userver-sample
142/// conn_timeout: 2s
143/// so_timeout: 10s
144/// queue_timeout: 1s
145/// initial_size: 16
146/// max_size: 128
147/// idle_limit: 64
148/// connecting_limit: 8
149/// local_threshold: 15ms
150/// stats_verbosity: terse
151/// ```
152///
153/// ## Static options:
154/// Name | Description | Default value
155/// ---- | ----------- | -------------
156/// appname | application name for the DB server | userver
157/// conn_timeout | connection timeout | 2s
158/// so_timeout | socket timeout | 10s
159/// queue_timeout | max connection queue wait time | 1s
160/// initial_size | number of connections created initially (per database) | 16
161/// max_size | limit for total connections number (per database) | 128
162/// idle_limit | limit for idle connections number (per database) | 64
163/// connecting_limit | limit for establishing connections number (per database) | 8
164/// local_threshold | latency window for instance selection | mongodb default
165/// max_replication_lag | replication lag limit for usable secondaries, min. 90s | -
166/// stats_verbosity | changes the granularity of reported metrics | 'terse'
167/// dns_resolver | server hostname resolver type (getaddrinfo or async) | 'async'
168///
169/// `stats_verbosity` accepts one of the following values:
170/// Value | Description
171/// ----- | -----------
172/// terse | Default value, report only cumulative stats and read/write totals
173/// full | Separate metrics for each operation, divided by read preference or write concern
174
175// clang-format on
176
177class MultiMongo : public ComponentBase {
178public:
179 /// @ingroup userver_component_names
180 /// @brief The default name of components::MultiMongo
181 static constexpr std::string_view kName = "multi-mongo";
182
183 /// Component constructor
184 MultiMongo(const ComponentConfig&, const ComponentContext&);
185
186 /// Component destructor
187 ~MultiMongo() override;
188
189 /// @brief Client pool accessor
190 /// @param dbalias name previously passed to `AddPool`
191 /// @throws PoolNotFound if no such database is enabled
192 storages::mongo::PoolPtr GetPool(const std::string& dbalias) const;
193
194 /// @brief Adds a database to the working set by its name.
195 /// Equivalent to
196 /// `NewPoolSet()`-`AddExistingPools()`-`AddPool(dbalias)`-`Activate()`
197 /// @param dbalias name of the database in secdist config
198 void AddPool(std::string dbalias);
199
200 /// @brief Removes the database with the specified name from the working set.
201 /// Equivalent to
202 /// `NewPoolSet()`-`AddExistingPools()`-`RemovePool(dbalias)`-`Activate()`
203 /// @param dbalias name of the database passed to AddPool
204 /// @returns whether the database was in the working set
205 bool RemovePool(const std::string& dbalias);
206
207 /// Creates an empty database set bound to the component
209
210 using PoolSet = storages::mongo::MultiMongo::PoolSet;
211
212 static yaml_config::Schema GetStaticConfigSchema();
213
214private:
215 storages::mongo::MultiMongo multi_mongo_;
216
217 // Subscriptions must be the last fields.
218 utils::statistics::Entry statistics_holder_;
219};
220
221template <>
222inline constexpr bool kHasValidate<MultiMongo> = true;
223
224} // namespace components
225
226USERVER_NAMESPACE_END