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/// @ingroup userver_components
17///
18/// @brief MongoDB client component
19///
20/// Provides access to a MongoDB database.
21///
22/// ## Dynamic options:
23/// * @ref MONGO_CONGESTION_CONTROL_DATABASES_SETTINGS
24/// * @ref MONGO_CONGESTION_CONTROL_ENABLED
25/// * @ref MONGO_CONGESTION_CONTROL_SETTINGS
26/// * @ref MONGO_CONNECTION_POOL_SETTINGS
27/// * @ref MONGO_DEFAULT_MAX_TIME_MS
28///
29/// ## Static configuration example:
30///
31/// ```
32/// mongo-taxi:
33/// dbalias: taxi
34/// appname: userver-sample
35/// conn_timeout: 2s
36/// so_timeout: 10s
37/// queue_timeout: 1s
38/// initial_size: 16
39/// max_size: 128
40/// idle_limit: 64
41/// connecting_limit: 8
42/// local_threshold: 15ms
43/// maintenance_period: 15s
44/// stats_verbosity: terse
45/// ```
46/// You must specify one of `dbalias` or `dbconnection`.
47///
48/// ## Static options of components::Mongo :
49/// @include{doc} scripts/docs/en/components_schema/mongo/src/storages/mongo/component.md
50///
51/// Options inherited from @ref components::MultiMongo
52/// @include{doc} scripts/docs/en/components_schema/mongo/src/storages/mongo/component_multi.md
53///
54/// Options inherited from @ref components::ComponentBase :
55/// @include{doc} scripts/docs/en/components_schema/core/src/components/impl/component_base.md
56///
57/// `stats_verbosity` accepts one of the following values:
58/// Value | Description
59/// ----- | -----------
60/// terse | Default value, report only cumulative stats and read/write totals
61/// full | Separate metrics for each operation, divided by read preference or write concern
62///
63/// It is a common practice to provide a database connection string via
64/// environment variables. To retrieve a value from the environment use
65/// `dbconnection#env: THE_ENV_VARIABLE_WITH_CONNECTION_STRING` as described
66/// in yaml_config::YamlConfig.
67///
68/// Note that if the `dbalias` option is provided and the components::Secdist component has `update-period` other
69/// than 0, then new connections are created or gracefully closed as the secdist configuration change to new value.
70///
71/// ## Secdist format
72///
73/// If a `dbalias` option is provided, for example
74/// `dbalias: some_name_of_your_database`, then the Secdist entry for that alias
75/// should look like following:
76/// @code{.json}
77/// {
78/// "mongo_settings": {
79/// "some_name_of_your_database": {
80/// "uri": "mongodb://user:password@host:port/database_name"
81/// }
82/// }
83/// }
84/// @endcode
85class Mongo : public ComponentBase {
86public:
87 /// Component constructor
88 Mongo(const ComponentConfig&, const ComponentContext&);
89
90 /// Component destructor
91 ~Mongo() override;
92
93 /// Client pool accessor
94 storages::mongo::PoolPtr GetPool() const;
95
96 static yaml_config::Schema GetStaticConfigSchema();
97
98private:
99 void OnSecdistUpdate(const storages::secdist::SecdistConfig& config);
100
101 std::string dbalias_;
102 storages::mongo::PoolPtr pool_;
103
104 // Subscriptions must be the last fields.
105 concurrent::AsyncEventSubscriberScope secdist_subscriber_;
106 utils::statistics::Entry statistics_holder_;
107};
108
109template <>
110inline constexpr bool kHasValidate<Mongo> = true;
111
112/// @ingroup userver_components
113///
114/// @brief Dynamically configurable MongoDB client component
115///
116/// Provides access to a dynamically reconfigurable set of MongoDB databases.
117///
118/// ## Dynamic options:
119/// * @ref MONGO_CONGESTION_CONTROL_DATABASES_SETTINGS
120/// * @ref MONGO_CONGESTION_CONTROL_ENABLED
121/// * @ref MONGO_CONGESTION_CONTROL_SETTINGS
122/// * @ref MONGO_CONNECTION_POOL_SETTINGS
123/// * @ref MONGO_DEFAULT_MAX_TIME_MS
124///
125/// ## Static configuration example:
126///
127/// ```
128/// multi-mongo:
129/// appname: userver-sample
130/// conn_timeout: 2s
131/// so_timeout: 10s
132/// queue_timeout: 1s
133/// initial_size: 16
134/// max_size: 128
135/// idle_limit: 64
136/// connecting_limit: 8
137/// local_threshold: 15ms
138/// stats_verbosity: terse
139/// ```
140///
141/// ## Static options:
142/// @include{doc} scripts/docs/en/components_schema/mongo/src/storages/mongo/component_multi.md
143///
144/// `stats_verbosity` accepts one of the following values:
145/// Value | Description
146/// ----- | -----------
147/// terse | Default value, report only cumulative stats and read/write totals
148/// full | Separate metrics for each operation, divided by read preference or write concern
149///
150/// Note that if the components::Secdist component has `update-period` other
151/// than 0, then new connections are created or gracefully closed as the secdist configuration change to new value.
152class MultiMongo : public ComponentBase {
153public:
154 /// @ingroup userver_component_names
155 /// @brief The default name of components::MultiMongo
156 static constexpr std::string_view kName = "multi-mongo";
157
158 /// Component constructor
159 MultiMongo(const ComponentConfig&, const ComponentContext&);
160
161 /// Component destructor
162 ~MultiMongo() override;
163
164 /// @brief Client pool accessor
165 /// @param dbalias name previously passed to `AddPool`
166 /// @throws PoolNotFound if no such database is enabled
167 storages::mongo::PoolPtr GetPool(const std::string& dbalias) const;
168
169 /// @brief Adds a database to the working set by its name.
170 /// Equivalent to
171 /// `NewPoolSet()`-`AddExistingPools()`-`AddPool(dbalias)`-`Activate()`
172 /// @param dbalias name of the database in secdist config
173 void AddPool(std::string dbalias);
174
175 /// @brief Removes the database with the specified name from the working set.
176 /// Equivalent to
177 /// `NewPoolSet()`-`AddExistingPools()`-`RemovePool(dbalias)`-`Activate()`
178 /// @param dbalias name of the database passed to AddPool
179 /// @returns whether the database was in the working set
180 bool RemovePool(const std::string& dbalias);
181
182 /// Creates an empty database set bound to the component
183 storages::mongo::MultiMongo::PoolSet NewPoolSet();
184
185 using PoolSet = storages::mongo::MultiMongo::PoolSet;
186
187 static yaml_config::Schema GetStaticConfigSchema();
188
189private:
190 storages::mongo::MultiMongo multi_mongo_;
191
192 // Subscriptions must be the last fields.
193 utils::statistics::Entry statistics_holder_;
194};
195
196template <>
197inline constexpr bool kHasValidate<MultiMongo> = true;
198
199} // namespace components
200
201USERVER_NAMESPACE_END