userver: userver/storages/postgres/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/postgres/component.hpp
4/// @brief @copybrief components::Postgres
5
6#include <chrono>
7
8#include <userver/components/component_base.hpp>
9#include <userver/concurrent/async_event_source.hpp>
10#include <userver/dynamic_config/snapshot.hpp>
11#include <userver/engine/mutex.hpp>
12#include <userver/storages/secdist/secdist.hpp>
13#include <userver/utils/statistics/entry.hpp>
14
15#include <userver/storages/postgres/database.hpp>
16
17USERVER_NAMESPACE_BEGIN
18
19namespace components {
20
21// clang-format off
22
23/// @ingroup userver_components
24///
25/// @brief PosgreSQL client component
26///
27/// Provides access to a PostgreSQL cluster.
28///
29/// ## Dynamic options:
30/// * @ref POSTGRES_DEFAULT_COMMAND_CONTROL
31/// * @ref POSTGRES_HANDLERS_COMMAND_CONTROL
32/// * @ref POSTGRES_QUERIES_COMMAND_CONTROL
33/// * @ref POSTGRES_CONNECTION_POOL_SETTINGS
34/// * @ref POSTGRES_TOPOLOGY_SETTINGS
35/// * @ref POSTGRES_CONNECTION_SETTINGS
36/// * @ref POSTGRES_STATEMENT_METRICS_SETTINGS
37/// * @ref POSTGRES_CONNLIMIT_MODE_AUTO_ENABLED
38///
39/// ## Static configuration example:
40///
41/// ```
42/// # yaml
43/// postgres-taxi:
44/// dbalias: taxi
45/// blocking_task_processor: task-processor-name
46/// max_replication_lag: 60s
47/// min_pool_size: 4
48/// max_pool_size: 15
49/// max_queue_size: 200
50/// max_statement_metrics: 50
51/// ```
52/// You must specify either `dbalias` or `dbconnection`.
53/// If the component is configured with an alias, it will lookup connection data
54/// in Secdist.
55///
56/// It is a common practice to provide a database connection string via
57/// environment variables. To retrieve a value from the environment use
58/// `dbconnection#env: THE_ENV_VARIABLE_WITH_CONNECTION_STRING` as described
59/// in yaml_config::YamlConfig.
60///
61/// You must specify `blocking_task_processor` as well.
62///
63/// `max_replication_lag` can be used to tune replication lag limit for replicas.
64/// Once the replica lag exceeds this value it will be automatically disabled.
65/// Note, however, that client-size lag detection is not precise in nature
66/// and can only provide the precision of couple seconds.
67///
68/// ## Secdist format
69///
70/// A PosgreSQL alias in secdist is described as a JSON array of objects
71/// containing a single cluster description. There are two formats of describing
72/// a cluster, the first one assigns predefined roles to DSNs, the second one
73/// is just a list of DSNs and the Postgres component takes care of discovering
74/// the cluster's topology itself.
75///
76/// ### Predefined roles
77///
78/// In predefined roles format the component requires single-host connection
79/// strings.
80///
81/// ```json
82/// {
83/// "shard_number" : 0,
84/// "master": "host=localhost dbname=example",
85/// "sync_slave": "host=localhost dbname=example",
86/// "slaves": [
87/// "host=localhost dbname=example"
88/// ]
89/// }
90/// ```
91///
92/// The predefined roles format is deprecated and the support will be removed
93/// soon.
94///
95/// ### Automatic discovery
96///
97/// In automatic discovery format the connection strings are any valid
98/// PostgreSQL connection strings including multi-host ones with the exception
99/// of `target_session_attrs` which will be ignored.
100///
101/// ```json
102/// {
103/// "shard_number" : 0,
104/// "hosts": [
105/// "host=host1,host2,host3 dbname=example",
106/// "postgresql://host1:5432,host2:6432,host3:12000/example"
107/// ]
108/// }
109/// ```
110///
111/// The `shard_number` parameter is required in both formats and must match the
112/// index of cluster description object in the alias array.
113///
114/// Please see [PostgreSQL documentation](https://www.postgresql.org/docs/12/libpq-connect.html#LIBPQ-CONNSTRING)
115/// on connection strings.
116///
117/// ## Static options:
118/// Name | Description | Default value
119/// ----------------------- | ----------------------------------------------------------------------------- | -------------
120/// dbalias | name of the database in secdist config (if available) | --
121/// dbconnection | connection DSN string (used if no dbalias specified) | --
122/// blocking_task_processor | name of task processor for background blocking operations | --
123/// max_replication_lag | replication lag limit for usable slaves | 60s
124/// sync-start | perform initial connections synchronously | true
125/// dns_resolver | server hostname resolver type (getaddrinfo or async) | 'async'
126/// persistent-prepared-statements | cache prepared statements or not | true
127/// user-types-enabled | allow use of user-defined types | true
128/// check-user-types | cancel service start if some user types have not been loaded, which helps to detect missing migrations | false
129/// ignore_unused_query_params| disable check for not-NULL query params that are not used in query | false
130/// monitoring-dbalias | name of the database for monitorings | calculated from dbalias or dbconnection options
131/// max_prepared_cache_size | prepared statements cache size limit | 200
132/// max_statement_metrics | limit of exported metrics for named statements | 0
133/// min_pool_size | number of connections created initially | 4
134/// max_pool_size | maximum number of created connections for "connlimit_mode: manual" | 15
135/// max_queue_size | maximum number of clients waiting for a connection | 200
136/// connecting_limit | limit for concurrent establishing connections number per pool (0 - unlimited) | 0
137/// connlimit_mode | max_connections setup mode (manual or auto), also see @ref scripts/docs/en/userver/pg_connlimit_mode_auto.md | auto
138/// error-injection | artificial error injection settings, error_injection::Settings | --
139
140// clang-format on
141
142class Postgres : public ComponentBase {
143public:
144 /// Default shard number
145 static constexpr size_t kDefaultShardNumber = 0;
146 /// Default command control
147 static constexpr storages::postgres::CommandControl kDefaultCommandControl{
148 std::chrono::milliseconds{500}, // network timeout
149 std::chrono::milliseconds{250} // statement timeout
150 };
151
152 /// Component constructor
153 Postgres(const ComponentConfig&, const ComponentContext&);
154 /// Component destructor
155 ~Postgres() override;
156
157 /// Cluster accessor for default shard number
158 storages::postgres::ClusterPtr GetCluster() const;
159
160 /// Cluster accessor for specific shard number
161 storages::postgres::ClusterPtr GetClusterForShard(size_t shard) const;
162
163 /// Get total shard count
165
166 /// Get database object
167 storages::postgres::DatabasePtr GetDatabase() const { return database_; }
168
169 /// Reports statistics for PostgreSQL driver
170 void ExtendStatistics(utils::statistics::Writer& writer);
171
172 static yaml_config::Schema GetStaticConfigSchema();
173
174private:
175 void OnConfigUpdate(const dynamic_config::Snapshot& cfg);
176
177 void OnSecdistUpdate(const storages::secdist::SecdistConfig& secdist);
178
179 std::string name_;
180 std::string db_name_;
181 std::string dbalias_;
182 storages::postgres::ClusterSettings initial_settings_;
183 storages::postgres::DatabasePtr database_;
184
185 // Subscriptions must be the last fields, because the fields above are used
186 // from callbacks.
187 concurrent::AsyncEventSubscriberScope config_subscription_;
188 concurrent::AsyncEventSubscriberScope secdist_subscription_;
189 utils::statistics::Entry statistics_holder_;
190 dynamic_config::Source config_source_;
191};
192
193template <>
194inline constexpr bool kHasValidate<Postgres> = true;
195
196} // namespace components
197
198USERVER_NAMESPACE_END