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